iOS Developer Library

Developer

UIKit Framework Reference UICollectionView Class Reference

Options
Deployment Target:

On This Page
Language:

UICollectionView

Inherits From


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 6.0 and later

The UICollectionView class manages an ordered collection of data items and presents them using customizable layouts. Collection views provide the same general function as table views except that a collection view is able to support more than just single-column layouts. Collection views support customizable layouts that can be used to implement multi-column grids, tiled layouts, circular layouts, and many more. You can even change the layout of a collection view dynamically if you want.

When adding 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, which is an object that conforms to the UICollectionViewDataSource protocol and is provided by your app. Data in the collection view is organized into individual items, which can then be grouped 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.

In addition to its cells, a collection view can present data using other types of views too. These supplementary views can be things like section headers and footers that are separate from the individual cells but still convey some sort of 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 it in your user interface, you use the methods of UICollectionView object to ensure that the visual presentation of items matches the order in your data source object. Thus, whenever you add, delete, or rearrange data in your collection, you use the methods of this class 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.

Collection Views and Layout Objects

A very important object associated with a collection view is the layout object, which is a subclass of the UICollectionViewLayout class. The layout object is responsible for defining the organization and location of all cells and supplementary views inside the collection view. Although it defines their locations, the layout object does not actually apply that 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 collection view actually applies layout information to the views. Thus, in a sense, the layout object is like another data source, only providing visual information instead of item data.

You normally specify a layout object when creating 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, you must call the setCollectionViewLayout:animated:completion: method instead.

If you want to create an interactive transition—one that is driven by a gesture recognizer or touch events—use the startInteractiveTransitionToCollectionViewLayout:completion: method to change the layout object. That method installs an intermediate layout object whose purpose is to work 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.

Creating 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. To simplify the creation process for your code, the collection view requires that you always dequeue views, rather than create them explicitly in your code. 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 does not 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 registerClass:forCellWithReuseIdentifier: or registerNib:forCellWithReuseIdentifier: method. 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 delegate 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.

For more information about implementing the data source methods to create and configure views, see UICollectionViewDataSource Protocol Reference.

For more information about appearance and behavior configuration, see Collection Views.

  • Initializes and returns a newly allocated collection view object with the specified frame and layout.

    Declaration

    Swift

    init(frame frame: CGRect, collectionViewLayout layout: UICollectionViewLayout)

    Objective-C

    - (instancetype)initWithFrame:(CGRect)frame collectionViewLayout:(UICollectionViewLayout *)layout

    Parameters

    frame

    The frame rectangle for the collection view, measured in points. The origin of the frame is relative to the superview in which you plan to add it. This frame is passed to the superclass during initialization.

    layout

    The layout object to use for organizing items. The collection view stores a strong reference to the specified object. Must not be nil.

    Return Value

    An initialized collection view object or nil if the object could not be created.

    Discussion

    Use this method when initializing a collection view object programmatically.

    This method is the designated initializer.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • delegate delegate Property

    The object that acts as the delegate of the collection view.

    Declaration

    Swift

    unowned(unsafe) var delegate: UICollectionViewDelegate?

    Objective-C

    @property(nonatomic, assign) id< UICollectionViewDelegate > delegate

    Discussion

    The delegate must adopt the UICollectionViewDelegate protocol. The collection view maintains a weak reference to the delegate object.

    The delegate object is responsible for managing selection behavior and interactions with individual items.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • The object that provides the data for the collection view.

    Declaration

    Swift

    unowned(unsafe) var dataSource: UICollectionViewDataSource?

    Objective-C

    @property(nonatomic, assign) id< UICollectionViewDataSource > dataSource

    Discussion

    The data source must adopt the UICollectionViewDataSource protocol. The collection view maintains a weak reference to the data source object.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • The view that provides the background appearance.

    Declaration

    Swift

    var backgroundView: UIView?

    Objective-C

    @property(nonatomic, retain) UIView *backgroundView

    Discussion

    The view (if any) in this property is positioned underneath all of the other content and sized automatically to fill the entire bounds of the collection view. The background view does not scroll with the collection view’s other content. The collection view maintains a strong reference to the background view object.

    This property is nil by default, which displays the background color of the collection view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Register a class for use in creating new collection view cells.

    Declaration

    Swift

    func registerClass(_ cellClass: AnyClass?, forCellWithReuseIdentifier identifier: String)

    Objective-C

    - (void)registerClass:(Class)cellClass forCellWithReuseIdentifier:(NSString *)identifier

    Parameters

    cellClass

    The class of a cell that you want to use in the collection view.

    identifier

    The reuse identifier to associate with the specified class. This parameter must not be nil and must not be an empty string.

    Discussion

    Prior to calling the dequeueReusableCellWithReuseIdentifier:forIndexPath: method of the collection view, you must use this method or the registerNib:forCellWithReuseIdentifier: method to tell the collection view how to create a new cell of the given type. If a cell of the specified type is not currently in a reuse queue, the collection view uses the provided information to create a new cell object automatically.

    If you previously registered a class or nib file with the same reuse identifier, the class you specify in the cellClass parameter replaces the old entry. You may specify nil for cellClass if you want to unregister the class from the specified reuse identifier.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Register a nib file for use in creating new collection view cells.

    Declaration

    Swift

    func registerNib(_ nib: UINib?, forCellWithReuseIdentifier identifier: String)

    Objective-C

    - (void)registerNib:(UINib *)nib forCellWithReuseIdentifier:(NSString *)identifier

    Parameters

    nib

    The nib object containing the cell object. The nib file must contain only one top-level object and that object must be of the type UICollectionViewCell.

    identifier

    The reuse identifier to associate with the specified nib file. This parameter must not be nil and must not be an empty string.

    Discussion

    Prior to calling the dequeueReusableCellWithReuseIdentifier:forIndexPath: method of the collection view, you must use this method or the registerClass:forCellWithReuseIdentifier: method to tell the collection view how to create a new cell of the given type. If a cell of the specified type is not currently in a reuse queue, the collection view uses the provided information to create a new cell object automatically.

    If you previously registered a class or nib file with the same reuse identifier, the object you specify in the nib parameter replaces the old entry. You may specify nil for nib if you want to unregister the nib file from the specified reuse identifier.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Registers a class for use in creating supplementary views for the collection view.

    Declaration

    Swift

    func registerClass(_ viewClass: AnyClass?, forSupplementaryViewOfKind elementKind: String, withReuseIdentifier identifier: String)

    Objective-C

    - (void)registerClass:(Class)viewClass forSupplementaryViewOfKind:(NSString *)elementKind withReuseIdentifier:(NSString *)identifier

    Parameters

    viewClass

    The class to use for the supplementary view.

    elementKind

    The kind of supplementary view to create. This value is defined by the layout object. This parameter must not be nil.

    identifier

    The reuse identifier to associate with the specified class. This parameter must not be nil and must not be an empty string.

    Discussion

    Prior to calling the dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: method of the collection view, you must use this method or the registerNib:forSupplementaryViewOfKind:withReuseIdentifier: method to tell the collection view how to create a supplementary view of the given type. If a view of the specified type is not currently in a reuse queue, the collection view uses the provided information to create a view object automatically.

    If you previously registered a class or nib file with the same element kind and reuse identifier, the class you specify in the viewClass parameter replaces the old entry. You may specify nil for viewClass if you want to unregister the class from the specified element kind and reuse identifier.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Registers a nib file for use in creating supplementary views for the collection view.

    Declaration

    Swift

    func registerNib(_ nib: UINib?, forSupplementaryViewOfKind kind: String, withReuseIdentifier identifier: String)

    Objective-C

    - (void)registerNib:(UINib *)nib forSupplementaryViewOfKind:(NSString *)kind withReuseIdentifier:(NSString *)identifier

    Parameters

    nib

    The nib object containing the view object. The nib file must contain only one top-level object and that object must be of the type UICollectionReusableView.

    kind

    The kind of supplementary view to create. The layout defines the types of supplementary views it supports. The value of this string may correspond to one of the predefined kind strings or to a custom string that the layout added to support a new type of supplementary view. This parameter must not be nil.

    identifier

    The reuse identifier to associate with the specified nib file. This parameter must not be nil and must not be an empty string.

    Discussion

    Prior to calling the dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: method of the collection view, you must use this method or the registerClass:forSupplementaryViewOfKind:withReuseIdentifier: method to tell the collection view how to create a supplementary view of the given type. If a view of the specified type is not currently in a reuse queue, the collection view uses the provided information to create a view object automatically.

    If you previously registered a class or nib file with the same element kind and reuse identifier, the class you specify in the viewClass parameter replaces the old entry. You may specify nil for nib if you want to unregister the class from the specified element kind and reuse identifier.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns a reusable cell object located by its identifier

    Declaration

    Swift

    func dequeueReusableCellWithReuseIdentifier(_ identifier: String, forIndexPath indexPath: NSIndexPath!) -> AnyObject

    Objective-C

    - (id)dequeueReusableCellWithReuseIdentifier:(NSString *)identifier forIndexPath:(NSIndexPath *)indexPath

    Parameters

    identifier

    The reuse identifier for the specified cell. This parameter must not be nil.

    indexPath

    The index path specifying the location of the cell. The data source receives this information when it is asked for the cell and should just pass it along. This method uses the index path to perform additional configuration based on the cell’s position in the collection view.

    Return Value

    A valid UICollectionReusableView object.

    Discussion

    Call this method from your data source object when asked to provide a new cell for the collection view. This method dequeues an existing cell if one is available or creates a new one based on the class or nib file you previously registered.

    If you registered a class for the specified identifier and a new cell must be created, this method initializes the cell by calling its initWithFrame: method. For nib-based cells, this method loads the cell object from the provided nib file. If an existing cell was available for reuse, this method calls the cell’s prepareForReuse method instead.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns a reusable supplementary view located by its identifier and kind.

    Declaration

    Swift

    func dequeueReusableSupplementaryViewOfKind(_ elementKind: String, withReuseIdentifier identifier: String, forIndexPath indexPath: NSIndexPath!) -> AnyObject

    Objective-C

    - (id)dequeueReusableSupplementaryViewOfKind:(NSString *)elementKind withReuseIdentifier:(NSString *)identifier forIndexPath:(NSIndexPath *)indexPath

    Parameters

    elementKind

    The kind of supplementary view to retrieve. This value is defined by the layout object. This parameter must not be nil.

    identifier

    The reuse identifier for the specified view. This parameter must not be nil.

    indexPath

    The index path specifying the location of the supplementary view in the collection view. The data source receives this information when it is asked for the view and should just pass it along. This method uses the information to perform additional configuration based on the view’s position in the collection view.

    Return Value

    A valid UICollectionReusableView object.

    Discussion

    Call this method from your data source object when asked to provide a new supplementary view for the collection view. This method dequeues an existing view if one is available or creates a new one based on the class or nib file you previously registered.

    If you registered a class for the specified identifier and a new cell must be created, this method initializes the cell by calling its initWithFrame: method. For nib-based cells, this method loads the cell object from the provided nib file. If an existing cell was available for reuse, this method calls the cell’s prepareForReuse method instead.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • The layout used to organize the collected view’s items.

    Declaration

    Swift

    var collectionViewLayout: UICollectionViewLayout

    Objective-C

    @property(nonatomic, retain) UICollectionViewLayout *collectionViewLayout

    Discussion

    Assigning a new layout object to this property causes the new layout to be applied (without animations) to the collection view’s items.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Changes the collection view’s layout and optionally animates the change.

    Declaration

    Swift

    func setCollectionViewLayout(_ layout: UICollectionViewLayout, animated animated: Bool)

    Objective-C

    - (void)setCollectionViewLayout:(UICollectionViewLayout *)layout animated:(BOOL)animated

    Parameters

    layout

    The new layout object for the collection view.

    animated

    Specify YEStrue if you want to animate changes from the current layout to the new layout specified by the layout parameter. Specify NOfalse to make the change without animations.

    Discussion

    This method makes the layout change without further interaction from the user. If you choose to animate the layout change, the animation timing and parameters are controlled by the collection view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Changes the collection view’s layout and notifies you when the animations complete.

    Declaration

    Swift

    func setCollectionViewLayout(_ layout: UICollectionViewLayout, animated animated: Bool, completion completion: ((Bool) -> Void)!)

    Objective-C

    - (void)setCollectionViewLayout:(UICollectionViewLayout *)layout animated:(BOOL)animated completion:(void (^)(BOOL finished))completion

    Parameters

    layout

    The new layout object for the collection view.

    animated

    Specify YEStrue if you want to animate changes from the current layout to the new layout specified by the layout parameter. Specify NOfalse to make the change without animations.

    completion

    The block that is executed when the layout transition finishes or is aborted by the user. This block takes the following parameter:

    finished

    A Boolean indicating whether the transition completed successfully. This parameter is YEStrue if the transition finished and the new layout is installed. It is NOfalse if the user aborted the transition and returned to the old layout.

    Discussion

    This method initiates a layout change programmatically, notifying you when the transition is complete. If you choose to animate the layout change, the animation timing and parameters are controlled by the collection view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later

  • Changes the collection view’s current layout using an interactive transition effect.

    Declaration

    Swift

    func startInteractiveTransitionToCollectionViewLayout(_ layout: UICollectionViewLayout, completion completion: UICollectionViewLayoutInteractiveTransitionCompletion?) -> UICollectionViewTransitionLayout

    Objective-C

    - (UICollectionViewTransitionLayout *)startInteractiveTransitionToCollectionViewLayout:(UICollectionViewLayout *)layout completion:(UICollectionViewLayoutInteractiveTransitionCompletion)completion

    Parameters

    layout

    The new layout object for the collected views. This is the layout that you want the collection view to use after the interactive transition is done.

    completion

    A completion handler to execute after the transition finishes.

    Return Value

    The intermediate transition layout object responsible for managing the interactive transition behavior.

    Discussion

    Call this method when you want to change the layout of your collection view using an intermediate transition. When you call this method, the collection view quietly makes the returned transition layout object its current layout object. It is your responsibility to set up a gesture recognizer or other touch-event handling code to track the transition progress. As progress changes, update the transitionProgress property of the transition layout object and invalidate the layout. Invalidating its layout causes the transition layout object to update the position of items based on the new progress value.

    When your event-handling code determines that the user has finished the transition to the new layout, call the finishInteractiveTransition method. If your code determines that the user has canceled the transition, call the cancelInteractiveTransition method to revert the changes instead. Calling either of these methods removes the transition layout object from the collection view and installs the appropriate target layout object.

    This method returns an instance of the UICollectionViewTransitionLayout class by default. If you want it to return a custom transition object instead, implement the collectionView:transitionLayoutForOldLayout:newLayout: method of your collection view delegate and use that method to return your custom object.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later

  • Tells the collection view to finish an interactive transition by installing the intended target layout.

    Declaration

    Swift

    func finishInteractiveTransition()

    Objective-C

    - (void)finishInteractiveTransition

    Discussion

    Call this method after a call to the startInteractiveTransitionToCollectionViewLayout:completion: method and after you determine through a gesture recognizer or other event-handling code that the user wants to transition to the new layout. This method removes the intermediate transition layout object from the collection view and installs the intended target layout object. It then performs any final animations to get the collection view’s items from their current positions to the positions specified by the newly installed layout object.

    After calling this method, you can also remove the gesture recognizer or event-handling code you installed to manage the interactive portions of the transition.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later

  • Tells the collection view to abort an interactive transition and return to its original layout object.

    Declaration

    Swift

    func cancelInteractiveTransition()

    Objective-C

    - (void)cancelInteractiveTransition

    Discussion

    Call this method after a call to the startInteractiveTransitionToCollectionViewLayout:completion: method and after you determine through a gesture recognizer or other event-handling code that the user wants to revert to the collection view’s original layout. This method removes the intermediate transition layout object from the collection view and reinstalls the original layout object. It then performs any final animations to get the collection view’s items from their current positions to the positions specified by the original layout object.

    After calling this method, you can also remove the gesture recognizer or event-handling code you installed to manage the interactive portions of the transition.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later

  • Reloads all of the data for the collection view.

    Declaration

    Swift

    func reloadData()

    Objective-C

    - (void)reloadData

    Discussion

    Call this method to reload all of the items in the collection view. This causes the collection view to discard any currently visible items and redisplay them. For efficiency, the collection view only displays those cells and supplementary views that are visible. If the collection data shrinks as a result of the reload, the collection view adjusts its scrolling offsets accordingly.

    You should not call this method in the middle of animation blocks where items are being inserted or deleted. Insertions and deletions automatically cause the table’s data to be updated appropriately.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Reloads the data in the specified sections of the collection view.

    Declaration

    Swift

    func reloadSections(_ sections: NSIndexSet)

    Objective-C

    - (void)reloadSections:(NSIndexSet *)sections

    Parameters

    sections

    The indexes of the sections to reload.

    Discussion

    Call this method to selectively reload only the items in the specified sections. This causes the collection view to discard any cells associated with those items and redisplay them.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Reloads just the items at the specified index paths.

    Declaration

    Swift

    func reloadItemsAtIndexPaths(_ indexPaths: [AnyObject])

    Objective-C

    - (void)reloadItemsAtIndexPaths:(NSArray *)indexPaths

    Parameters

    indexPaths

    An array of NSIndexPath objects identifying the items you want to update.

    Discussion

    Call this method to selectively reload only the specified items. This causes the collection view to discard any cells associated with those items and redisplay them.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns the number of sections displayed by the collection view.

    Declaration

    Swift

    func numberOfSections() -> Int

    Objective-C

    - (NSInteger)numberOfSections

    Return Value

    The number of sections in the collection view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns the number of items in the specified section.

    Declaration

    Swift

    func numberOfItemsInSection(_ section: Int) -> Int

    Objective-C

    - (NSInteger)numberOfItemsInSection:(NSInteger)section

    Parameters

    section

    The index of the section for which you want a count of the items.

    Return Value

    The number of items in the specified section.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns an array of visible cells currently displayed by the collection view.

    Declaration

    Swift

    func visibleCells() -> [AnyObject]

    Objective-C

    - (NSArray *)visibleCells

    Return Value

    An array of UICollectionViewCell objects. If no cells are visible, this method returns an empty array.

    Discussion

    This method returns the complete list of visible cells displayed by the collection view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Inserts new items at the specified index paths.

    Declaration

    Swift

    func insertItemsAtIndexPaths(_ indexPaths: [AnyObject])

    Objective-C

    - (void)insertItemsAtIndexPaths:(NSArray *)indexPaths

    Parameters

    indexPaths

    An array of NSIndexPath objects, each of which contains a section index and item index at which to insert a new cell. This parameter must not be nil.

    Discussion

    Call this method to insert one or more new items into the collection view. You might do this when your data source object receives data for new items or in response to user interactions with the collection view. The collection view gets the layout information for the new cells as part of calling this method. And if the layout information indicates that the cells should appear onscreen, the collection view asks your data source to provide the appropriate views, animating them into position as needed.

    You can also call this method from a block passed to the performBatchUpdates:completion: method when you want to animate multiple separate changes into place at the same time. See the description of that method for more information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Moves an item from one location to another in the collection view.

    Declaration

    Swift

    func moveItemAtIndexPath(_ indexPath: NSIndexPath, toIndexPath newIndexPath: NSIndexPath)

    Objective-C

    - (void)moveItemAtIndexPath:(NSIndexPath *)indexPath toIndexPath:(NSIndexPath *)newIndexPath

    Parameters

    indexPath

    The index path of the item you want to move. This parameter must not be nil.

    newIndexPath

    The index path of the item’s new location. This parameter must not be nil.

    Discussion

    Use this method to reorganize existing data items. You might do this when you rearrange the items within your data source object or in response to user interactions with the collection view. You can move items between sections or within the same section. The collection view updates the layout as needed to account for the move, animating cells into position as needed.

    You can also call this method from a block passed to the performBatchUpdates:completion: method when you want to animate multiple separate changes into place at the same time. See the description of that method for more information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Deletes the items at the specified index paths.

    Declaration

    Swift

    func deleteItemsAtIndexPaths(_ indexPaths: [AnyObject])

    Objective-C

    - (void)deleteItemsAtIndexPaths:(NSArray *)indexPaths

    Parameters

    indexPaths

    An array of NSIndexPath objects, each of which contains a section index and item index for the item you want to delete from the collection view. This parameter must not be nil.

    Discussion

    Use this method to remove items from the collection view. You might do this when you remove the items from your data source object or in response to user interactions with the collection view. The collection view updates the layout of the remaining items to account for the deletions, animating the remaining items into position as needed.

    You can also call this method from a block passed to the performBatchUpdates:completion: method when you want to animate multiple separate changes into place at the same time. See the description of that method for more information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Inserts new sections at the specified indexes.

    Declaration

    Swift

    func insertSections(_ sections: NSIndexSet)

    Objective-C

    - (void)insertSections:(NSIndexSet *)sections

    Parameters

    sections

    An index set containing the indexes of the sections you want to insert. This parameter must not be nil.

    Discussion

    Use this method to insert one or more sections into the collection view. This method adds the sections, and it is up to your data source to report the number of items in each section when asked for the information. The collection view then uses that information to get updated layout attributes for the newly inserted sections and items. If the insertions cause a change in the collection view’s visible content, those changes are animated into place.

    You can also call this method from a block passed to the performBatchUpdates:completion: method when you want to animate multiple separate changes into place at the same time. See the description of that method for more information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Moves a section from one location to another in the collection view.

    Declaration

    Swift

    func moveSection(_ section: Int, toSection newSection: Int)

    Objective-C

    - (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection

    Parameters

    section

    The index path of the section you want to move. This parameter must not be nil.

    newSection

    The index path of the section’s new location. This parameter must not be nil.

    Discussion

    Use this method to reorganize existing sections and their contained items. You might do this when you rearrange sections within your data source object or in response to user interactions with the collection view. The collection view updates the layout as needed to account for the move, animating new views into position as needed.

    You can also call this method from a block passed to the performBatchUpdates:completion: method when you want to animate multiple separate changes into place at the same time. See the description of that method for more information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Deletes the sections at the specified indexes.

    Declaration

    Swift

    func deleteSections(_ sections: NSIndexSet)

    Objective-C

    - (void)deleteSections:(NSIndexSet *)sections

    Parameters

    sections

    The indexes of the sections you want to delete. This parameter must not be nil.

    Discussion

    Use this method to remove the sections and their items from the collection view. You might do this when you remove the sections from your data source object or in response to user interactions with the collection view. The collection view updates the layout of the remaining sections and items to account for the deletions, animating the remaining items into position as needed.

    You can also call this method from a block passed to the performBatchUpdates:completion: method when you want to animate multiple separate changes into place at the same time. See the description of that method for more information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • A Boolean value that indicates whether users can select items in the collection view.

    Declaration

    Swift

    var allowsSelection: Bool

    Objective-C

    @property(nonatomic) BOOL allowsSelection

    Discussion

    If the value of this property is YEStrue (the default), users can select items. If you want more fine-grained control over the selection of items, you must provide a delegate object and implement the appropriate methods of the UICollectionViewDelegate protocol.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • A Boolean value that determines whether users can select more than one item in the collection view.

    Declaration

    Swift

    var allowsMultipleSelection: Bool

    Objective-C

    @property(nonatomic) BOOL allowsMultipleSelection

    Discussion

    This property controls whether multiple items can be selected simultaneously. The default value of this property is NOfalse.

    When the value of this property is YEStrue, tapping a cell adds it to the current selection (assuming the delegate permits the cell to be selected). Tapping the cell again removes it from the selection.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

    See Also

    allowsSelection

  • Returns the index paths for the selected items.

    Declaration

    Swift

    func indexPathsForSelectedItems() -> [AnyObject]

    Objective-C

    - (NSArray *)indexPathsForSelectedItems

    Return Value

    An array of NSIndexPath objects, each of which corresponds to a single selected item. If there are no selected items, this method returns an empty array.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Selects the item at the specified index path and optionally scrolls it into view.

    Declaration

    Swift

    func selectItemAtIndexPath(_ indexPath: NSIndexPath?, animated animated: Bool, scrollPosition scrollPosition: UICollectionViewScrollPosition)

    Objective-C

    - (void)selectItemAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated scrollPosition:(UICollectionViewScrollPosition)scrollPosition

    Parameters

    indexPath

    The index path of the item to select. Specifying nil for this parameter clears the current selection.

    animated

    Specify YEStrue to animate the change in the selection or NOfalse to make the change without animating it.

    scrollPosition

    An option that specifies where the item should be positioned when scrolling finishes. For a list of possible values, see “UICollectionViewScrollPosition”.

    Discussion

    If the allowsSelection property is NOfalse, calling this method has no effect. If there is an existing selection with a different index path and the allowsMultipleSelection property is NOfalse, calling this method replaces the previous selection.

    This method does not cause any selection-related delegate methods to be called.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Deselects the item at the specified index.

    Declaration

    Swift

    func deselectItemAtIndexPath(_ indexPath: NSIndexPath?, animated animated: Bool)

    Objective-C

    - (void)deselectItemAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated

    Parameters

    indexPath

    The index path of the item to select. Specifying nil results in no change to the current selection.

    animated

    Specify YEStrue to animate the change in the selection or NOfalse to make the change without animating it.

    Discussion

    If the allowsSelection property is NOfalse, calling this method has no effect.

    This method does not cause any selection-related delegate methods to be called.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns the index path of the item at the specified point in the collection view.

    Declaration

    Swift

    func indexPathForItemAtPoint(_ point: CGPoint) -> NSIndexPath?

    Objective-C

    - (NSIndexPath *)indexPathForItemAtPoint:(CGPoint)point

    Parameters

    point

    A point in the collection view’s coordinate system.

    Return Value

    The index path of the item at the specified point or nil if no item was found at the specified point.

    Discussion

    This method relies on the layout information provided by the associated layout object to determine which item contains the point.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns an array of the visible items in the collection view.

    Declaration

    Swift

    func indexPathsForVisibleItems() -> [AnyObject]

    Objective-C

    - (NSArray *)indexPathsForVisibleItems

    Return Value

    An array of NSIndexPath objects, each of which corresponds to a visible cell in the collection view. This array does not include any supplementary views that are currently visible. If there are no visible items, this method returns an empty array.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns the index path of the specified cell.

    Declaration

    Swift

    func indexPathForCell(_ cell: UICollectionViewCell) -> NSIndexPath?

    Objective-C

    - (NSIndexPath *)indexPathForCell:(UICollectionViewCell *)cell

    Parameters

    cell

    The cell object whose index path you want.

    Return Value

    The index path of the cell or nil if the specified cell is not in the collection view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns the visible cell object at the specified index path.

    Declaration

    Swift

    func cellForItemAtIndexPath(_ indexPath: NSIndexPath) -> UICollectionViewCell?

    Objective-C

    - (UICollectionViewCell *)cellForItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    indexPath

    The index path that specifies the section and item number of the cell.

    Return Value

    The cell object at the corresponding index path or nil if the cell is not visible or indexPath is out of range.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns the layout information for the item at the specified index path.

    Declaration

    Swift

    func layoutAttributesForItemAtIndexPath(_ indexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (UICollectionViewLayoutAttributes *)layoutAttributesForItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    indexPath

    The index path of the item.

    Return Value

    The layout attributes for the item or nil if no item exists at the specified path.

    Discussion

    Use this method to retrieve the layout information for a particular item. You should always use this method instead of querying the layout object directly.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Returns the layout information for the specified supplementary view.

    Declaration

    Swift

    func layoutAttributesForSupplementaryElementOfKind(_ kind: String, atIndexPath indexPath: NSIndexPath) -> UICollectionViewLayoutAttributes?

    Objective-C

    - (UICollectionViewLayoutAttributes *)layoutAttributesForSupplementaryElementOfKind:(NSString *)kind atIndexPath:(NSIndexPath *)indexPath

    Parameters

    kind

    A string specifying the kind of supplementary view whose layout attributes you want. Layout classes are responsible for defining the kinds of supplementary views they support.

    indexPath

    The index path of the supplementary view. The interpretation of this value depends on how the layout implements the view. For example, a view associated with a section might contain just a section value.

    Return Value

    The layout attributes of the supplementary view or nil if the specified supplementary view does not exist.

    Discussion

    Use this method to retrieve the layout information for a particular supplementary view. You should always use this method instead of querying the layout object directly.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Scrolls the collection view contents until the specified item is visible.

    Declaration

    Swift

    func scrollToItemAtIndexPath(_ indexPath: NSIndexPath, atScrollPosition scrollPosition: UICollectionViewScrollPosition, animated animated: Bool)

    Objective-C

    - (void)scrollToItemAtIndexPath:(NSIndexPath *)indexPath atScrollPosition:(UICollectionViewScrollPosition)scrollPosition animated:(BOOL)animated

    Parameters

    indexPath

    The index path of the item to scroll into view.

    scrollPosition

    An option that specifies where the item should be positioned when scrolling finishes. For a list of possible values, see “UICollectionViewScrollPosition”.

    animated

    Specify YEStrue to animate the scrolling behavior or NOfalse to adjust the scroll view’s visible content immediately.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

  • Animates multiple insert, delete, reload, and move operations as a group.

    Declaration

    Swift

    func performBatchUpdates(_ updates: (() -> Void)?, completion completion: ((Bool) -> Void)?)

    Objective-C

    - (void)performBatchUpdates:(void (^)(void))updates completion:(void (^)(BOOL finished))completion

    Parameters

    updates

    The block that performs the relevant insert, delete, reload, or move operations.

    completion

    A completion handler block to execute when all of the operations are finished. This block takes a single Boolean parameter that contains the value YEStrue if all of the related animations completed successfully or NOfalse if they were interrupted. This parameter may be nil.

    Discussion

    You can use this method in cases where you want to make multiple changes to the collection view in one single animated operation, as opposed to in several separate animations. You might use this method to insert, delete, reload, or move cells or use it to change the layout parameters associated with one or more cells. Use the blocked passed in the updates parameter to specify all of the operations you want to perform.

    Deletes are processed before inserts in batch operations. This means the indexes for the deletions are processed relative to the indexes of the collection view’s state before the batch operation, and the indexes for the insertions are processed relative to the indexes of the state after all the deletions in the batch operation.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later

Data Types

  • The completion block called at the end of an interactive transition for a collection view.

    Declaration

    Swift

    typealias UICollectionViewLayoutInteractiveTransitionCompletion = (Bool, Bool) -> Void

    Objective-C

    typedef void(^UICollectionViewLayoutInteractiveTransitionCompletion)(BOOL completed, BOOL finish);

    Discussion

    This completion block takes the following parameters:

    completed

    A Boolean indicating whether the animations ran to completion.

    finish

    A Boolean indicating whether the transition finished or was canceled. This parameter is YEStrue if the transition ran to completion and the new layout is installed. It is NOfalse if the user canceled the transition and the old layout is installed.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later

  • Constants that indicate how to scroll an item into the visible portion of the collection view.

    Declaration

    Swift

    struct UICollectionViewScrollPosition : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var None: UICollectionViewScrollPosition { get } static var Top: UICollectionViewScrollPosition { get } static var CenteredVertically: UICollectionViewScrollPosition { get } static var Bottom: UICollectionViewScrollPosition { get } static var Left: UICollectionViewScrollPosition { get } static var CenteredHorizontally: UICollectionViewScrollPosition { get } static var Right: UICollectionViewScrollPosition { get } }

    Objective-C

    enum { UICollectionViewScrollPositionNone = 0, UICollectionViewScrollPositionTop = 1 << 0, UICollectionViewScrollPositionCenteredVertically = 1 << 1, UICollectionViewScrollPositionBottom = 1 << 2, UICollectionViewScrollPositionLeft = 1 << 3, UICollectionViewScrollPositionCenteredHorizontally = 1 << 4, UICollectionViewScrollPositionRight = 1 << 5 }; typedef NSUInteger UICollectionViewScrollPosition;

    Constants

    • None

      UICollectionViewScrollPositionNone

      Do not scroll the item into view.

      Available in iOS 6.0 and later

    • Top

      UICollectionViewScrollPositionTop

      Scroll so that the item is positioned at the top of the collection view’s bounds. This option is mutually exclusive with the UICollectionViewScrollPositionCenteredVertically and UICollectionViewScrollPositionBottom options.

      Available in iOS 6.0 and later

    • CenteredVertically

      UICollectionViewScrollPositionCenteredVertically

      Scroll so that the item is centered vertically in the collection view. This option is mutually exclusive with the UICollectionViewScrollPositionTop and UICollectionViewScrollPositionBottom options.

      Available in iOS 6.0 and later

    • Bottom

      UICollectionViewScrollPositionBottom

      Scroll so that the item is positioned at the bottom of the collection view’s bounds. This option is mutually exclusive with the UICollectionViewScrollPositionTop and UICollectionViewScrollPositionCenteredVertically options.

      Available in iOS 6.0 and later

    • Left

      UICollectionViewScrollPositionLeft

      Scroll so that the item is positioned at the left edge of the collection view’s bounds. This option is mutually exclusive with the UICollectionViewScrollPositionCenteredHorizontally and UICollectionViewScrollPositionRight options.

      Available in iOS 6.0 and later

    • CenteredHorizontally

      UICollectionViewScrollPositionCenteredHorizontally

      Scroll so that the item is centered horizontally in the collection view. This option is mutually exclusive with the UICollectionViewScrollPositionLeft and UICollectionViewScrollPositionRight options.

      Available in iOS 6.0 and later

    • Right

      UICollectionViewScrollPositionRight

      Scroll so that the item is positioned at the right edge of the collection view’s bounds. This option is mutually exclusive with the UICollectionViewScrollPositionLeft and UICollectionViewScrollPositionCenteredHorizontally options.

      Available in iOS 6.0 and later

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later