TransformingLazyColumnState

public class TransformingLazyColumnState(
    initialAnchorItemIndex: Int = -1,
    initialAnchorItemScrollOffset: Int = 0,
) : ScrollableState

A state object that can be hoisted to control and observe scrolling in a TransformingLazyColumn.

Parameters

Properties

layoutInfo

public val layoutInfo: TransformingLazyColumnLayoutInfo

The object of LazyColumnLayoutInfo calculated during the last layout pass. For example, you can use it to calculate what items are currently visible. Note that this property is observable and is updated after every scroll or remeasure. If you use it in the composable function it will be recomposed on every change causing potential performance issues including infinity recomposition loop. Therefore, avoid using it in the composition. If you want to run some side effects like sending an analytics event or updating a state based on this value consider using "snapshotFlow":

anchorItemIndex

public var anchorItemIndex: Int

The index of the item that is used in scrolling. For the most cases that is the item closest to the center of viewport from TransformingLazyColumnLayoutInfo.visibleItems, however it might change during scroll.

Note that this property is observable and if you use it in the composable function it will be recomposed on every change causing potential performance issues.

If you need to use it in the composition then consider wrapping the calculation into a derived state in order to only have recompositions when the derived value changes:

anchorItemScrollOffset

public var anchorItemScrollOffset: Int

The scroll offset of the anchor item. Scrolling forward is positive - i.e., the amount that the item is offset backwards.

Note that this property is observable and if you use it in the composable function it will be recomposed on every scroll causing potential performance issues.

Functions

requestAnchorItem

public fun requestAnchorItem(key: Any?, anchorType: TransformingLazyColumnAnchorType)

Requests a specific item (identified by key) to act as the layout anchor for the list.

The layout anchor determines which item remains stationary during a layout pass. TransformingLazyColumn natively measures items outwards from the anchor: items placed above the anchor are measured bottom-up, and items below are measured top-down. Anchoring a specific item using this method provides control over the direction in which it (or surrounding items) expands or shrinks when intrinsic heights change.

For example, a "Show More" button that expands to reveal text below it can be requested with TransformingLazyColumnAnchorType.ItemTop. This keeps its visual top edge anchored and forces the new content to push downwards. For an input text box at the bottom of a list, TransformingLazyColumnAnchorType.ItemBottom can be used so its visual bottom edge is anchored and the text expands upwards.

Call this method immediately before mutating the state that causes the item's size to change. The request will take effect in the very next remeasure pass.

It is highly recommended to assign explicit, stable keys to items in the list (via the key parameter in the item or items DSL) when using this API. If explicit keys are not used, structural changes to the list may cause the anchor request to fail.

Visibility and Lifecycle:

• Not Visible/Not Present: If the provided key is not present in the list or is not currently visible on screen during the layout pass, this request is ignored. The list will fall back to its default anchoring logic (anchoring to the item closest to the viewport center).
• Persistence: The requested anchor persists across multiple frames. This allows it to work seamlessly with Modifier.animateContentSize() as the item smoothly changes height over time.
• Clearing: The request is automatically cleared the moment the user initiates a scroll gesture (when isScrollInProgress becomes true).

Parameters

scrollToItem

public suspend fun scrollToItem(
        @androidx.annotation.IntRange(from = 0) index: Int,
        scrollOffset: Int = 0,
    )

Scrolls the item specified by index to the center of the screen.

The scroll position anchorItemIndex and anchorItemScrollOffset will be updated to take into account the new layout. There is no guarantee that index will become the new anchorItemIndex since requested scrollOffset may position item with another index closer to the anchor point.

This operation happens instantly without animation.

Parameters

requestScrollToItem

public fun requestScrollToItem(
        @androidx.annotation.IntRange(from = 0) index: Int,
        scrollOffset: Int = 0,
    )

Requests the item at index to be at the center of the viewport during the next remeasure, offset by scrollOffset.

The scroll position anchorItemIndex and anchorItemScrollOffset will be updated to take into account the new layout. There is no guarantee that index will become the new anchorItemIndex since requested scrollOffset may position item with another index closer to the anchor point.

The scroll position will be updated to the requested position rather than maintain the index based on the center item key (when a data set change will also be applied during the next remeasure), but only for the next remeasure.

Any scroll in progress will be cancelled.

Parameters

animateScrollToItem

public suspend fun animateScrollToItem(
        @androidx.annotation.IntRange(from = 0) index: Int,
        scrollOffset: Int = 0,
    )

Animate (smooth scroll) to the given item.

The scroll position anchorItemIndex and anchorItemScrollOffset will be updated to take into account the new layout. There is no guarantee that index will become the new anchorItemIndex since requested scrollOffset may position item with another index closer to the anchor point.

Parameters

Companion Object