CollectionViewChatLayout

@MainActor
open class CollectionViewChatLayout : UICollectionViewLayout

A custom collection view layout designed to present items in a grid-like format, similar to UITableView, while aligning content to either the leading or trailing edge of the UICollectionView. This layout supports chat-style interfaces by preserving a consistent content offset from the bottom. It also accommodates self-sizing cells and supplementary views, ensuring dynamic and responsive content presentation.

Custom Properties:

CollectionViewChatLayout.delegate

CollectionViewChatLayout.settings

CollectionViewChatLayout.keepContentOffsetAtBottomOnBatchUpdates

CollectionViewChatLayout.processOnlyVisibleItemsOnAnimatedBatchUpdates

CollectionViewChatLayout.keepContentAtBottomOfVisibleArea

CollectionViewChatLayout.visibleBounds

CollectionViewChatLayout.layoutFrame

Custom Methods:

CollectionViewChatLayout.getContentOffsetSnapshot(...)

CollectionViewChatLayout.restoreContentOffset(...)

CollectionViewChatLayout.reconfigureItems(...)

CollectionViewChatLayout.indexPathForItePinnedAt(...)

Custom Properties

  • CollectionViewChatLayout delegate.

    Declaration

    Swift

    @MainActor
open weak var delegate: ChatLayoutDelegate?

  • Additional settings for CollectionViewChatLayout.

    Declaration

    Swift

    @MainActor
public var settings: ChatLayoutSettings { get set }

  • By default, UIScrollView maintains a constant content offset relative to the top edge. When this flag is set to true, CollectionViewChatLayout will attempt to adjust for batch updates in order to keep the currently visible content anchored to the bottom of the UICollectionView.

    NB: If the content inset changes during the batch update—for example, due to keyboard frame adjustments - CollectionViewChatLayout typically receives this information after the animation begins and may not be able to account for it automatically. In such cases, manual compensation is required.

    Declaration

    Swift

    @MainActor
public var keepContentOffsetAtBottomOnBatchUpdates: Bool

  • By default, UICollectionView positions its cells at the top of the visible area when the content size is smaller than the viewport. Enabling this flag reverses that behavior, allowing cells to align with the bottom edge of the UICollectionView - similar to the behavior seen in applications like Telegram.

    Declaration

    Swift

    @MainActor
public var keepContentAtBottomOfVisibleArea: Bool

  • Sometimes UIScrollView can behave weirdly if there are too many corrections in it’s contentOffset during the animation. Especially when content size of the UIScrollView is getting smaller first and then expands again as the newly appearing cells sizes are being calculated. That is why CollectionViewChatLayout tries to process only the elements that are currently visible on the screen. But often it is not needed. This flag allows you to have fine control over this behaviour. It set to true by default to keep the compatibility with the older versions of the library.

    NB: This flag is only to provide fine control over the batch updates. If in doubts - keep it true.

    Declaration

    Swift

    @MainActor
public var processOnlyVisibleItemsOnAnimatedBatchUpdates: Bool

  • Enables a mode for automatic self-sizing invalidation in response to Auto Layout changes. While this can be useful in certain scenarios, it is generally recommended to continue using explicit reload/reconfigure methods - particularly when multiple changes occur simultaneously with animation. This ensures that CollectionViewChatLayout can manage layout updates while preserving content offset consistency.

    NB: This is an experimental feature and should be used only when no more reliable alternatives are available.

    Declaration

    Swift

    @available(iOS 16.0, *)
@MainActor
public var supportSelfSizingInvalidation: Bool { get set }

  • Represent the currently visible rectangle.

    Declaration

    Swift

    @MainActor
open var visibleBounds: CGRect { get }

  • Represent the rectangle where all the items are aligned.

    Declaration

    Swift

    @MainActor
open var layoutFrame: CGRect { get }

Inherited Properties

  • The direction of the language you used when designing CollectionViewChatLayout layout.

    Declaration

    Swift

    @MainActor
open override var developmentLayoutDirection: UIUserInterfaceLayoutDirection { get }

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

    Declaration

    Swift

    @MainActor
open override var flipsHorizontallyInOppositeLayoutDirection: Bool { get }

  • Custom layoutAttributesClass is ChatLayoutAttributes.

    Declaration

    Swift

    @MainActor
public override class var layoutAttributesClass: AnyClass { get }

  • Custom invalidationContextClass is ChatLayoutInvalidationContext.

    Declaration

    Swift

    @MainActor
public override class var invalidationContextClass: AnyClass { get }

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

    Declaration

    Swift

    @MainActor
open override var collectionViewContentSize: CGSize { get }

  • There is an issue in IOS 15.1 that proposed content offset is being ignored by the UICollectionView when user is scrolling. This flag enables a hack to compensate this offset later. You can disable it if necessary. Bug reported: https://feedbackassistant.apple.com/feedback/9727104

    PS: This issue was fixed in 15.2

    Declaration

    Swift

    @MainActor
public var enableIOS15_1Fix: Bool

Constructors

  • Default constructor.

    Declaration

    Swift

    @MainActor
public init(flipsHorizontallyInOppositeLayoutDirection: Bool = true)

    Parameters

    flipsHorizontallyInOppositeLayoutDirection

    Indicates whether the horizontal coordinate system is automatically flipped at appropriate times. In practice, this is used to support right-to-left layout.

  • Returns an object initialized from data in a given unarchiver.

    Declaration

    Swift

    @MainActor
public required init?(coder aDecoder: NSCoder)

Custom Methods

Providing Layout Attributes

  • Tells the layout object to update the current layout.

    Declaration

    Swift

    @MainActor
open override func prepare()

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

    Declaration

    Swift

    @MainActor
open override func layoutAttributesForElements(in rect: CGRect) -> [UICollectionViewLayoutAttributes]?

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

    Declaration

    Swift

    @MainActor
open override func layoutAttributesForItem(at indexPath: IndexPath) -> UICollectionViewLayoutAttributes?

  • Retrieves the layout attributes for the specified supplementary view.

    Declaration

    Swift

    @MainActor
open override func layoutAttributesForSupplementaryView(
    ofKind elementKind: String,
    at indexPath: IndexPath
) -> UICollectionViewLayoutAttributes?

Coordinating Animated Changes

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

    Declaration

    Swift

    @MainActor
open override func prepare(forAnimatedBoundsChange oldBounds: CGRect)

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

    Declaration

    Swift

    @MainActor
open override func finalizeAnimatedBoundsChange()

Context Invalidation

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

    Declaration

    Swift

    @MainActor
open override func shouldInvalidateLayout(
    forPreferredLayoutAttributes preferredAttributes: UICollectionViewLayoutAttributes,
    withOriginalAttributes originalAttributes: UICollectionViewLayoutAttributes
) -> Bool

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

    Declaration

    Swift

    @MainActor
open override func invalidationContext(
    forPreferredLayoutAttributes preferredAttributes: UICollectionViewLayoutAttributes,
    withOriginalAttributes originalAttributes: UICollectionViewLayoutAttributes
) -> UICollectionViewLayoutInvalidationContext

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

    Declaration

    Swift

    @MainActor
open override func shouldInvalidateLayout(forBoundsChange newBounds: CGRect) -> Bool

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

    Declaration

    Swift

    @MainActor
open override func invalidationContext(forBoundsChange newBounds: CGRect) -> UICollectionViewLayoutInvalidationContext

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

    Declaration

    Swift

    @MainActor
open override func invalidateLayout(with context: UICollectionViewLayoutInvalidationContext)

  • Invalidates the current layout and triggers a layout update.

    Declaration

    Swift

    @MainActor
open override func invalidateLayout()

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

    Declaration

    Swift

    @MainActor
open override func targetContentOffset(forProposedContentOffset proposedContentOffset: CGPoint) -> CGPoint

Responding to Collection View Updates

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

    Declaration

    Swift

    @MainActor
open override func prepare(forCollectionViewUpdates updateItems: [UICollectionViewUpdateItem])

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

    Declaration

    Swift

    @MainActor
open override func finalizeCollectionViewUpdates()

Cell Appearance Animation

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

    Declaration

    Swift

    @MainActor
open override func initialLayoutAttributesForAppearingItem(at itemIndexPath: IndexPath) -> UICollectionViewLayoutAttributes?

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

    Declaration

    Swift

    @MainActor
open override func finalLayoutAttributesForDisappearingItem(at itemIndexPath: IndexPath) -> UICollectionViewLayoutAttributes?

Supplementary View Appearance Animation

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

    Declaration

    Swift

    @MainActor
open override func initialLayoutAttributesForAppearingSupplementaryElement(
    ofKind elementKind: String,
    at elementIndexPath: IndexPath
) -> UICollectionViewLayoutAttributes?

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

    Declaration

    Swift

    @MainActor
open override func finalLayoutAttributesForDisappearingSupplementaryElement(
    ofKind elementKind: String,
    at elementIndexPath: IndexPath
) -> UICollectionViewLayoutAttributes?