Contents

UICollectionView

An object that manages an ordered collection of data items and presents them using customizable layouts.

Declaration

@MainActor class UICollectionView

Mentioned in

Overview

When you add a collection view to your user interface, your app’s main job is to manage the data associated with that collection view. The collection view gets its data from the data source object, stored in the collection view’s dataSource property. For your data source, you can use a UICollectionViewDiffableDataSource object, which provides the behavior you need to simply and efficiently manage updates to your collection view’s data and user interface. Alternatively, you can create a custom data source object by adopting the UICollectionViewDataSource protocol.

Data in the collection view is organized into individual items, which you can group into sections for presentation. An item is the smallest unit of data you want to present. For example, in a photos app, an item might be a single image. The collection view presents items onscreen using a cell, which is an instance of the UICollectionViewCell class that your data source configures and provides.

[Image]

In addition to its cells, a collection view can present data using other types of views. These supplementary views can be, for example, section headers and footers that are separate from the individual cells but still convey information. Support for supplementary views is optional and defined by the collection view’s layout object, which is also responsible for defining the placement of those views.

Besides embedding a UICollectionView in your user interface, you use the methods of the collection view to ensure that the visual presentation of items matches the order in your data source object. A UICollectionViewDiffableDataSource object manages this process automatically. If you’re using a custom data source, then whenever you add, delete, or rearrange data in your collection, you use the methods of UICollectionView to insert, delete, and rearrange the corresponding cells.

You also use the collection view object to manage the selected items, although for this behavior the collection view works with its associated delegate object.

Layouts

A layout object defines the visual arrangement of the content in the collection view. A subclass of the UICollectionViewLayout class, the layout object defines the organization and location of all cells and supplementary views inside the collection view. Although it defines their locations, the layout object doesn’t actually apply that information to the corresponding views. The collection view applies layout information to the corresponding views because the creation of cells and supplementary views involves coordination between the collection view and your data source object. The layout object is like another data source, except it provides visual information instead of item data.

You typically specify a layout object when you create a collection view, but you can also change the layout of a collection view dynamically. The layout object is stored in the collectionViewLayout property. Setting this property directly updates the layout immediately, without animating the changes. If you want to animate the changes, call the setCollectionViewLayout(_:animated:completion:) method instead.

To create an interactive transition — one that is driven by a gesture recognizer or touch events — use the startInteractiveTransition(to:completion:) method to change the layout object. That method installs an intermediate layout object, which works with your gesture recognizer or event-handling code to track the transition progress. When your event-handling code determines that the transition is finished, it calls the finishInteractiveTransition() or cancelInteractiveTransition() method to remove the intermediate layout object and install the intended target layout object.

For more information, see Layouts.

Cells and supplementary views

The collection view’s data source object provides both the content for items and the views used to present that content. When the collection view first loads its content, it asks its data source to provide a view for each visible item. The collection view maintains a queue or list of view objects that the data source has marked for reuse. Instead of creating new views explicitly in your code, you always dequeue views.

There are two methods for dequeueing views. The one you use depends on which type of view has been requested:

Before you call either of these methods, you must tell the collection view how to create the corresponding view if one doesn’t already exist. For this, you must register either a class or a nib file with the collection view. For example, when registering cells, you use the register(_:forCellWithReuseIdentifier:) method to register a class or the register(_:forCellWithReuseIdentifier:) method to register a nib file. As part of the registration process, you specify the reuse identifier that identifies the purpose of the view. This is the same string you use when dequeueing the view later.

After dequeueing the appropriate view in your data source method, configure its content and return it to the collection view for use. After getting the layout information from the layout object, the collection view applies it to the view and displays it.

Data prefetching

Collection views provide two prefetching techniques you can use to improve responsiveness:

  • Cell prefetching prepares cells in advance of the time they’re required. When a collection view requires a large number of cells simultaneously — for example, a new row of cells in grid layout — the cells are requested earlier than the time required for display. Cell rendering is therefore spread across multiple layout passes, resulting in a smoother scrolling experience. Cell prefetching is enabled by default.

  • Data prefetching provides a mechanism whereby you’re notified of the data requirements of a collection view in advance of the requests for cells. This is useful if the content of your cells relies on an expensive data loading process, such as a network request. Assign an object that conforms to the UICollectionViewDataSourcePrefetching protocol to the prefetchDataSource property to receive notifications of when to prefetch data for cells.

Reorder items interactively

Collection views allow you to move items around based on user interactions. Typically, the order of items in a collection view is defined by your data source. If you allow users to reorder items, you can configure a gesture recognizer to track the user’s interactions with a collection view item and update that item’s position.

To begin the interactive repositioning of an item, call the beginInteractiveMovementForItem(at:) method of the collection view. While your gesture recognizer is tracking touch events, call the updateInteractiveMovementTargetPosition(_:) method to report changes in the touch location. When you’re done tracking the gesture, call the endInteractiveMovement() or cancelInteractiveMovement() method to conclude the interactions and update the collection view.

During user interactions, the collection view invalidates its layout dynamically to reflect the current position of the item. If you do nothing, the default layout behavior repositions the items for you, but you can customize the layout animations if you want. When interactions finish, the collection view updates its data source object with the new location of the item.

The UICollectionViewController class provides a default gesture recognizer that you can use to rearrange items in its managed collection view. To install this gesture recognizer, set the installsStandardGestureForInteractiveMovement property of the collection view controller to true.

Interface Builder attributes

The following table lists the attributes that you configure for collection views in Interface Builder.

Attribute

Description

Items

The number of prototype cells. This property controls the specified number of prototype cells for you to configure in your storyboard. Collection views must always have at least one cell and may have multiple cells for displaying different types of content or for displaying the same content in different ways.

Layout

The layout object to use. Use this control to select between the Uicollectionviewflowlayout object and a custom layout object that you define. [Image] When the flow layout is selected, you can also configure the scrolling direction for the collection view’s content and whether the flow layout has header and footer views. Enabling header and footer views adds reusable views to your storyboard that you can configure with your header and footer content. You can also create those views programmatically. [Image] When a custom layout is selected, you must specify the Uicollectionviewlayout subclass to use.

When the Flow layout is selected, the Size inspector for the collection view contains additional attributes for configuring flow layout metrics. Use those attributes to configure the size of your cells, the size of headers and footers, the minimum spacing between cells, and any margins around each section of cells. For more information about the meaning of the flow layout metrics, see UICollectionViewFlowLayout.

Internationalization

A collection view has no direct content of its own to internationalize. Instead, you internationalize the cells and reusable views of the collection view. For more information about internationalization, see Localization.

Accessibility

A collection view has no content of its own to make accessible. If your cells and reusable views contain standard UIKit controls such as UILabel and UITextField, you can make those controls accessible. When a collection view changes its onscreen layout, it posts the layoutChanged notification.

For general information about making your interface accessible, see Accessibility for UIKit.

Topics

Creating a collection view

Providing the collection view data

Prefetching collection view cells and data

Managing collection view interactions

Creating cells

Creating headers and footers

Configuring the background view

Changing the layout

Getting the state of the collection view

Inserting, moving, and deleting Items

Inserting, moving, and deleting sections

Reordering items interactively

Managing drag interactions

Managing drop interactions

Selecting cells

Putting the collection view into edit mode

Locating items and views in the collection view

Getting layout information

Scrolling an item into view

Animating multiple changes to the collection view

Reloading content

Identifying collection view elements

Working with focus

Managing context menus

Resizing self-sizing cells

Instance Methods

See Also

View