iOS Developer Library — Prerelease

Developer

UIKit User Interface Catalog

On This Page

Collection Views

A collection view displays an ordered collection of data items using standard or custom layouts. Similar to a table view, a collection view gets data from your custom data source objects and displays it using a combination of cell, layout, and supplementary views. A collection view can display items in a grid or in a custom layout that you design. Regardless of the layout style you choose, a collection view is best suited to display nonhierarchical, ordered data items.

image: ../Art/uicollectionview_intro.png

Purpose. Collection views allow users to:

  • View a catalog of variably sized items, optionally sorted into multiple sections

  • Add to, rearrange, and edit a collection of items

  • Choose from a frequently changing display of items

Implementation.

Configuration. Configure collection views in Interface Builder, in the Collection View section of the Attributes Inspector. A few configurations cannot be made through the Attributes Inspector, so you must make them programmatically. You can set other configurations programmatically, too, if you prefer.

image: ../Art/uicollectionview_attributes_inspector_plain_2x.png
image: ../Art/uicollectionreusableview_attributes_inspector_plain_2x.png

Content of Collection Views

Cells present the main content of your collection view. The job of a cell is to present the content for a single item from your data source object. Each cell must be an instance of the UICollectionViewCell class, which you may subclass as needed to present your content. Cell objects provide inherent support for managing their own selection and highlight state, although some custom code must be written to actually apply a highlight to a cell. A UICollectionViewCell object is a specific type of reusable view that you use for your main data items.

To manage the visual presentation of data, a collection view works with many related classes, such as UICollectionViewController, UICollectionViewDataSource, UICollectionViewDelegate, UICollectionReusableView, UICollectionViewCell, UICollectionViewLayout, and UICollectionViewLayoutAttributes.

Collection views enforce a strict separation between the data being presented and the visual elements used for presentation. Your app is solely responsible for managing the data via your custom data source objects. (To learn how to create these objects, see Designing Your Data Objects.) Your app also provides the view objects used to present that data. The collection view takes your views and—with the help of a layout object, which specifies placement and other visual attributes—does all the work of displaying them onscreen.

image: ../Art/uicollectionview_callouts.png

To display content onscreen in an efficient way, a collection view uses the following reusable view objects:

  • Cell. Represents one data item.

  • Supplementary view. Represents information related to the data items, such as a section header or footer.

  • Decoration view. Represents purely decorative content that’s not part of your data, such as a background image.

image: ../Art/uicollectionview_attributes_inspector_subgroup-layout_flow.png

Because a collection view works with these and other objects to determine the visual presentation of your data, configuring a collection view in Interface Builder means that you need to configure some objects separately.

  • Items. The number of different types of data for which you define distinct cell objects. If your app works with only one type of data item—regardless of the total number of data items you display—set this value to 1.

  • Accessories. The existence of a header or footer view for each section (this property isn’t available for custom layouts). Select Section Header or Section Footer as appropriate.

In Collection Reusable View Attributes inspector—which governs supplementary views, decoration views, and cells—you can set the Identifier (identifier) field. Enter the ID you use in your code to identify the reusable cell, decoration, or supplementary view object.

image: ../Art/uicollectionviewcell_attributes_inspector_identifier_2x.png

Behavior of Collection Views

There are several behaviors you can support in your collection view. For example, you might want to allow users to:

  • Select one or more items

  • Insert, delete, and reorder items or sections

  • Edit an item

By default, a collection view detects when the user taps a specific cell and it updates the cell’s selected or highlighted properties as appropriate. You can write code that configures a collection view to support multiple-item selection or that draws the selected or highlighted states yourself. To learn how to support multiple selection or custom selection states, see Managing the Visual State for Selections and Highlights.

To support insertion, deletion, or reordering of cells in a collection view, you make changes to your data source and then tell the collection view to redisplay the content. By default, a collection view animates the insertion, deletion, or movement of a single item; if you want to animate these changes for multiple items at once, you use code blocks to batch the update. To learn how animate multiple changes to a collection view, see Inserting, Deleting, and Moving Sections and Items. To let users move an item or items by dragging, you also need to incorporate a custom gesture recognizer. (To learn how to do this, see Manipulating Cells and Views.)

If you support editing for an item, the collection view automatically displays the Edit menu when it detects a long-press gesture on a specific cell. To learn how to support editing in a collection view, see Showing the Edit Menu for a Cell.

When configuring cells and supplementary views in a storyboard, you do so by dragging the item onto your collection view and configuring it there. This creates a relationship between the collection view and the corresponding cell or view. For cells, drag a collection view cell from the object library and drop it onto your collection view. Set the custom class and the collection reusable view identifier of your cell to appropriate values.

Whether the user is selecting or deselecting a cell, the cell’s selected state is always the last thing to change. Taps in a cell always result in changes to the cell’s highlighted state first. Only after the tap sequence ends and any highlights applied during that sequence are removed, does the selected state of the cell change. When designing your cells, you should make sure that the visual appearance of your highlights and selected state do not conflict in unintended ways.

When the user performs a long-tap gesture on a cell, the collection view attempts to display an Edit menu for that cell. The Edit menu can be used to cut, copy, and paste cells in the collection view.

If you’re working with the UICollectionViewFlowLayout class, you can use the Attributes inspector to set the “Scroll Direction” (scrollDirection) field to Horizontal or Vertical. Note that this property isn’t available for custom layouts.

image: ../Art/uicollectionview_attributes_inspector_subgroup-layout_flow.png

Appearance of Collection Views

Layout

A collection view relies on a layout object to define the layout of its cells, supplementary views, and decoration views.

The Layout field determines the layout of the cells. The default value is Flow, which refers to the layout defined by the UICollectionViewFlowLayout class. If you provide a custom layout class, choose Custom instead.

image: ../Art/uicollectionview_attributes_inspector_subgroup-layout_custom.pdf

To learn more about creating a custom layout class, see Collection View Programming Guide for iOS.

Background

To use a custom background for a collection view, you can specify a view that's positioned underneath all of the other content and sized automatically to fill the entire bounds of the collection view. You can set this value using the backgroundView property. Because this background view doesn’t scroll with the collection view’s content, it’s not an appropriate way to display a decorative background such as the appearance of wooden shelves.

Cell Background

To use a custom background for a single collection view cell, you can specify a view that’s positioned behind the cell’s content view and that fills the cell’s bounds. You can set this value using the backgroundView property.

You can also specify a custom selected background by providing a view that’s displayed above the cell’s background view—and behind the content view—when the user selects the cell. Set this value using the selectedBackgroundView property.

Spacing

In the Collection View Flow Layout Size Inspector, you can set size values (in points) for the layout object to use when laying out cells and supplementary views.

image: ../Art/uicollectionview_size_inspector_min_spacing.png

For spacing between cells you can set the following Min Spacing values:

  • For Cells. The minimum space to maintain between cells on one line.

  • For Lines. The minimum space to maintain between lines of cells.

Cell Padding

image: ../Art/uicollectionview_size_inspector_section_insets.png

To add padding around cells so that space appears above, below, or on either side of the cells in a section, use the “Section Insets” fields in the Collection View Flow Layout Size Inspector. Specifying nonzero inset values reduces the amount of space available for laying out cells, which lets you limit the number of cells that can appear on one row or the number of rows that can appear in one section. The insets you can specify are:

  • Top. The space to add between the bottom of the header view and the top of the first line of cells.

  • Bottom. The space to add between the bottom last line of cells and the top of the footer

  • Left. The space to add between the left edge of the cells and the left edge of the collection view.

  • Right. The space to add between the right edge of the cells and the right edge of the collection view.

Using Auto Layout with Collection Views

You can create Auto Layout constraints between a collection view and other user interface elements. You can create any type of constraint for a collection view besides a baseline constraint.

For general information about using Auto Layout with iOS views, see Using Auto Layout with Views.

Making Collection Views Accessible

The data items in a collection view are accessible by default when they are represented by standard UIKit objects, such as UILabel and UITextField.

When a collection view changes its onscreen layout, it posts the UIAccessibilityLayoutChangedNotification notification.

For general information about making iOS views accessible, see Making Views Accessible.

Internationalizing Collection Views

For more information, see Internationalization and Localization Guide.

Elements Similar to a Collection View

The following elements provide similar functionality to a collection view:

  • Table View. A scrolling view that displays data items in a single-column list. For more information, see Table Views.

  • Scroll View. A scrolling view that displays content without support for any specific layout or ordering scheme. For more information, see Scroll Views.