<!--
{
  "availability" : [
    "iOS: 6.0.0 -",
    "iPadOS: 6.0.0 -",
    "macCatalyst: 13.1.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UICollectionViewLayout",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:objc(cs)UICollectionViewLayout"
  },
  "title" : "UICollectionViewLayout"
}
-->

# UICollectionViewLayout

An abstract base class for generating layout information for a collection view.

```
@MainActor class UICollectionViewLayout
```

## Overview

A layout object determines the placement of cells, supplementary views, and decoration views inside the collection view’s bounds and reports that information to the collection view. The collection view then applies the provided layout information to the corresponding views so that they can be presented onscreen.

You must subclass [`UICollectionViewLayout`](/documentation/UIKit/UICollectionViewLayout) in order to use it. Before you consider subclassing, however, consider whether you can adapt [`UICollectionViewCompositionalLayout`](/documentation/UIKit/UICollectionViewCompositionalLayout) to your layout needs.

### Subclassing notes

The layout object defines the position, size, and visual state of items in the collection view, based on the design of the layout. The views for the layout are created by the collection view’s data source.

You lay out three types of visual elements in a collection view:

- *Cells* are the main elements positioned by the layout. Each cell represents a single data item in the collection. You can make cells interactive so that a user can perform actions like selecting, dragging, and reordering the cells. A collection view can have a single group of cells, or you can divide those cells into multiple sections. The layout object arranges the cells in the collection view’s content area.
- *Supplementary views* present data but can’t be selected by the user. You use supplementary views to implement things like header and footer views for a given section or for the entire collection view. Supplementary views are optional and their use and placement is defined by the layout object.
- *Decoration views* are visual adornments, like badges, that can’t be selected and aren’t inherently tied to the data of the collection view. Decoration views are another type of supplementary view. Like supplementary views, they’re optional and their use and placement is defined by the layout object.

The collection view asks its layout object to provide layout information for these elements at many different times. Every cell and view that appears on screen is positioned using information from the layout object. Similarly, every time items are inserted into or deleted from the collection view, an additional layout pass occurs for the items being added or removed. However, the collection view always limits layout to the objects that are visible onscreen.

#### Methods to override

Every layout object should implement the following methods:

- [`collectionViewContentSize`](/documentation/UIKit/UICollectionViewLayout/collectionViewContentSize)
- [`layoutAttributesForElements(in:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForElements(in:))
- [`layoutAttributesForItem(at:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForItem(at:))
- [`layoutAttributesForSupplementaryView(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForSupplementaryView(ofKind:at:)) (if your layout supports supplementary views)
- [`layoutAttributesForDecorationView(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForDecorationView(ofKind:at:)) (if your layout supports decoration views)
- [`shouldInvalidateLayout(forBoundsChange:)`](/documentation/UIKit/UICollectionViewLayout/shouldInvalidateLayout(forBoundsChange:))

These methods provide the fundamental layout information that the collection view needs to place contents on the screen. If your layout doesn’t support supplementary or decoration views, don’t implement the corresponding methods.

When the data in the collection view changes and items are to be inserted or deleted, the collection view asks its layout object to update the layout information. Specifically, any item that’s moved, added, or deleted must have its layout information updated to reflect its new location. For moved items, the collection view uses the standard methods to retrieve the item’s updated layout attributes. For items being inserted or deleted, the collection view calls some different methods, which you should override to provide the appropriate layout information:

- [`initialLayoutAttributesForAppearingItem(at:)`](/documentation/UIKit/UICollectionViewLayout/initialLayoutAttributesForAppearingItem(at:))
- [`initialLayoutAttributesForAppearingSupplementaryElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/initialLayoutAttributesForAppearingSupplementaryElement(ofKind:at:))
- [`initialLayoutAttributesForAppearingDecorationElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/initialLayoutAttributesForAppearingDecorationElement(ofKind:at:))
- [`finalLayoutAttributesForDisappearingItem(at:)`](/documentation/UIKit/UICollectionViewLayout/finalLayoutAttributesForDisappearingItem(at:))
- [`finalLayoutAttributesForDisappearingSupplementaryElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/finalLayoutAttributesForDisappearingSupplementaryElement(ofKind:at:))
- [`finalLayoutAttributesForDisappearingDecorationElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/finalLayoutAttributesForDisappearingDecorationElement(ofKind:at:))

In addition to these methods, you can also override the [`prepare(forCollectionViewUpdates:)`](/documentation/UIKit/UICollectionViewLayout/prepare(forCollectionViewUpdates:)) to handle any layout-related preparation. You can also override the [`finalizeCollectionViewUpdates()`](/documentation/UIKit/UICollectionViewLayout/finalizeCollectionViewUpdates()) method and use it to add animations to the overall animation block or to implement any final layout-related tasks.

#### Optimizing layout performance using invalidation contexts

When designing your custom layouts, you can improve performance by invalidating only those parts of your layout that actually changed. When you change items, calling the [`invalidateLayout()`](/documentation/UIKit/UICollectionViewLayout/invalidateLayout()) method forces the collection view to recompute all of its layout information and reapply it. A better solution is to recompute only the layout information that changed, which is exactly what invalidation contexts allow you to do. An invalidation context lets you specify which parts of the layout changed. The layout object can then use that information to minimize the amount of data it recomputes.

To define a custom invalidation context for your layout, subclass the [`UICollectionViewLayoutInvalidationContext`](/documentation/UIKit/UICollectionViewLayoutInvalidationContext) class. In your subclass, define custom properties that represent the parts of your layout data that can be recomputed independently. When you need to invalidate your layout at runtime, create an instance of your invalidation context subclass, configure the custom properties based on what layout information changed, and pass that object to your layout’s [`invalidateLayout(with:)`](/documentation/UIKit/UICollectionViewLayout/invalidateLayout(with:)) method. Your custom implementation of that method can use the information in the invalidation context to recompute only the portions of your layout that changed.

If you define a custom invalidation context class for your layout object, you should also override the [`invalidationContextClass`](/documentation/UIKit/UICollectionViewLayout/invalidationContextClass) method and return your custom class. The collection view always creates an instance of the class you specify when it needs an invalidation context. Returning your custom subclass from this method ensures that your layout object always has the invalidation context it expects.

## Topics

### Creating the collection view layout

[`init()`](/documentation/UIKit/UICollectionViewLayout/init())

Creates a collection view layout object.

[`init(coder:)`](/documentation/UIKit/UICollectionViewLayout/init(coder:))

Creates a collection view layout object from data in a given unarchiver.

### Getting the collection view information

[`collectionView`](/documentation/UIKit/UICollectionViewLayout/collectionView)

The collection view object currently using this layout object.

[`collectionViewContentSize`](/documentation/UIKit/UICollectionViewLayout/collectionViewContentSize)

The width and height of the collection view’s contents.

### Providing layout attributes

[`layoutAttributesClass`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesClass)

The class to use when creating layout attributes objects.

[`prepare()`](/documentation/UIKit/UICollectionViewLayout/prepare())

Tells the layout object to update the current layout.

[`layoutAttributesForElements(in:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForElements(in:))

Retrieves the layout attributes for all of the cells and views in the specified rectangle.

[`layoutAttributesForItem(at:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForItem(at:))

Retrieves layout information for an item at the specified index path with a corresponding cell.

[`layoutAttributesForInteractivelyMovingItem(at:withTargetPosition:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForInteractivelyMovingItem(at:withTargetPosition:))

Retrieves the layout attributes of an item when it is being moved interactively by the user.

[`layoutAttributesForSupplementaryView(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForSupplementaryView(ofKind:at:))

Retrieves the layout attributes for the specified supplementary view.

[`layoutAttributesForDecorationView(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/layoutAttributesForDecorationView(ofKind:at:))

Retrieves the layout attributes for the specified decoration view.

[`targetContentOffset(forProposedContentOffset:)`](/documentation/UIKit/UICollectionViewLayout/targetContentOffset(forProposedContentOffset:))

Retrieves the content offset to use after an animated layout update or change.

[`targetContentOffset(forProposedContentOffset:withScrollingVelocity:)`](/documentation/UIKit/UICollectionViewLayout/targetContentOffset(forProposedContentOffset:withScrollingVelocity:))

Retrieves the point at which to stop scrolling.

### Responding to collection view updates

[`prepare(forCollectionViewUpdates:)`](/documentation/UIKit/UICollectionViewLayout/prepare(forCollectionViewUpdates:))

Notifies the layout object that the contents of the collection view are about to change.

[`finalizeCollectionViewUpdates()`](/documentation/UIKit/UICollectionViewLayout/finalizeCollectionViewUpdates())

Performs any additional animations or clean up needed during a collection view update.

[`indexPathsToInsertForSupplementaryView(ofKind:)`](/documentation/UIKit/UICollectionViewLayout/indexPathsToInsertForSupplementaryView(ofKind:))

Retrieves an array of index paths for the supplementary views you want to add to the layout.

[`indexPathsToInsertForDecorationView(ofKind:)`](/documentation/UIKit/UICollectionViewLayout/indexPathsToInsertForDecorationView(ofKind:))

Retrieves an array of index paths representing the decoration views to add.

[`initialLayoutAttributesForAppearingItem(at:)`](/documentation/UIKit/UICollectionViewLayout/initialLayoutAttributesForAppearingItem(at:))

Retrieves the starting layout information for an item being inserted into the collection view.

[`initialLayoutAttributesForAppearingSupplementaryElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/initialLayoutAttributesForAppearingSupplementaryElement(ofKind:at:))

Retrieves the starting layout information for a supplementary view being inserted into the collection view.

[`initialLayoutAttributesForAppearingDecorationElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/initialLayoutAttributesForAppearingDecorationElement(ofKind:at:))

Retrieves the starting layout information for a decoration view being inserted into the collection view.

[`indexPathsToDeleteForSupplementaryView(ofKind:)`](/documentation/UIKit/UICollectionViewLayout/indexPathsToDeleteForSupplementaryView(ofKind:))

Retrieves an array of index paths representing the supplementary views to remove.

[`indexPathsToDeleteForDecorationView(ofKind:)`](/documentation/UIKit/UICollectionViewLayout/indexPathsToDeleteForDecorationView(ofKind:))

Retrieves an array of index paths representing the decoration views to remove.

[`finalLayoutAttributesForDisappearingItem(at:)`](/documentation/UIKit/UICollectionViewLayout/finalLayoutAttributesForDisappearingItem(at:))

Retrieves the final layout information for an item that is about to be removed from the collection view.

[`finalLayoutAttributesForDisappearingSupplementaryElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/finalLayoutAttributesForDisappearingSupplementaryElement(ofKind:at:))

Retrieves the final layout information for a supplementary view that is about to be removed from the collection view.

[`finalLayoutAttributesForDisappearingDecorationElement(ofKind:at:)`](/documentation/UIKit/UICollectionViewLayout/finalLayoutAttributesForDisappearingDecorationElement(ofKind:at:))

Retrieves the final layout information for a decoration view that is about to be removed from the collection view.

[`targetIndexPath(forInteractivelyMovingItem:withPosition:)`](/documentation/UIKit/UICollectionViewLayout/targetIndexPath(forInteractivelyMovingItem:withPosition:))

Retrieves the index path to for an item when it is at the specified location in the collection view’s bounds.

### Invalidating the layout

[`invalidateLayout()`](/documentation/UIKit/UICollectionViewLayout/invalidateLayout())

Invalidates the current layout and triggers a layout update.

[`invalidateLayout(with:)`](/documentation/UIKit/UICollectionViewLayout/invalidateLayout(with:))

Invalidates the current layout using the information in the provided context object.

[`invalidationContextClass`](/documentation/UIKit/UICollectionViewLayout/invalidationContextClass)

Returns the class to use when creating an invalidation context for the layout.

[`shouldInvalidateLayout(forBoundsChange:)`](/documentation/UIKit/UICollectionViewLayout/shouldInvalidateLayout(forBoundsChange:))

Asks the layout object if the new bounds require a layout update.

[`invalidationContext(forBoundsChange:)`](/documentation/UIKit/UICollectionViewLayout/invalidationContext(forBoundsChange:))

Retrieves a context object that defines the portions of the layout that should change when a bounds change occurs.

[`shouldInvalidateLayout(forPreferredLayoutAttributes:withOriginalAttributes:)`](/documentation/UIKit/UICollectionViewLayout/shouldInvalidateLayout(forPreferredLayoutAttributes:withOriginalAttributes:))

Asks the layout object if changes to a self-sizing cell require a layout update.

[`invalidationContext(forPreferredLayoutAttributes:withOriginalAttributes:)`](/documentation/UIKit/UICollectionViewLayout/invalidationContext(forPreferredLayoutAttributes:withOriginalAttributes:))

Retrieves a context object that identifies the portions of the layout that should change in response to dynamic cell changes.

[`invalidationContext(forInteractivelyMovingItems:withTargetPosition:previousIndexPaths:previousPosition:)`](/documentation/UIKit/UICollectionViewLayout/invalidationContext(forInteractivelyMovingItems:withTargetPosition:previousIndexPaths:previousPosition:))

Retrieves a context object that identifies the items that are being interactively moved in the layout.

[`invalidationContextForEndingInteractiveMovementOfItems(toFinalIndexPaths:previousIndexPaths:movementCancelled:)`](/documentation/UIKit/UICollectionViewLayout/invalidationContextForEndingInteractiveMovementOfItems(toFinalIndexPaths:previousIndexPaths:movementCancelled:))

Retrieves a context object that identifies the items that were moved

### Coordinating animated changes

[`prepare(forAnimatedBoundsChange:)`](/documentation/UIKit/UICollectionViewLayout/prepare(forAnimatedBoundsChange:))

Prepares the layout object for animated changes to the view’s bounds or the insertion or deletion of items.

[`finalizeAnimatedBoundsChange()`](/documentation/UIKit/UICollectionViewLayout/finalizeAnimatedBoundsChange())

Cleans up after any animated changes to the view’s bounds or after the insertion or deletion of items.

### Transitioning between layouts

[`prepareForTransition(from:)`](/documentation/UIKit/UICollectionViewLayout/prepareForTransition(from:))

Tells the layout object to prepare to be installed as the layout for the collection view.

[`prepareForTransition(to:)`](/documentation/UIKit/UICollectionViewLayout/prepareForTransition(to:))

Tells the layout object that it is about to be removed as the layout for the collection view.

[`finalizeLayoutTransition()`](/documentation/UIKit/UICollectionViewLayout/finalizeLayoutTransition())

Tells the layout object to perform any final steps before the transition animations occur.

### Registering decoration views

[`register(_:forDecorationViewOfKind:)`](/documentation/UIKit/UICollectionViewLayout/register(_:forDecorationViewOfKind:)-361k6)

Registers a class for use in creating decoration views for a collection view.

[`register(_:forDecorationViewOfKind:)`](/documentation/UIKit/UICollectionViewLayout/register(_:forDecorationViewOfKind:)-35jf9)

Registers a nib file for use in creating decoration views for a collection view.

### Supporting right-to-left layouts

[`developmentLayoutDirection`](/documentation/UIKit/UICollectionViewLayout/developmentLayoutDirection)

The direction of the language you used when designing your custom layout.

[`flipsHorizontallyInOppositeLayoutDirection`](/documentation/UIKit/UICollectionViewLayout/flipsHorizontallyInOppositeLayoutDirection)

A Boolean value that indicates whether the horizontal coordinate system is automatically flipped at appropriate times.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)