PagerState

abstract class PagerState
internal constructor(
    currentPage: Int = 0,
    @FloatRange(from = -0.5, to = 0.5) currentPageOffsetFraction: Float = 0f,
    prefetchScheduler: PrefetchScheduler? = null,
) : ScrollableState

The state that can be used to control VerticalPager and HorizontalPager

Secondary Constructors

constructor(
    currentPage: Int = 0,
    @FloatRange(from = -0.5, to = 0.5) currentPageOffsetFraction: Float = 0f,
) : this(currentPage, currentPageOffsetFraction, null)

Parameters

Properties

abstract val pageCount: Int

The total amount of pages present in this pager. The source of this data should be observable.

val layoutInfo: PagerLayoutInfo

A PagerLayoutInfo that contains useful information about the Pager's last layout pass. For instance, you can query which pages are currently visible in the layout.

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":

val interactionSource: InteractionSource

InteractionSource that will be used to dispatch drag events when this list is being dragged. If you want to know whether the fling (or animated scroll) is in progress, use isScrollInProgress.

val currentPage: Int

The page that sits closest to the snapped position. This is an observable value and will change as the pager scrolls either by gesture or animation.

Please refer to the sample to learn how to use this API.

val settledPage

The page that is currently "settled". This is an animation/gesture unaware page in the sense that it will not be updated while the pages are being scrolled, but rather when the animation/scroll settles.

Please refer to the sample to learn how to use this API.

val targetPage: Int

The page this Pager intends to settle to. During fling or animated scroll (from animateScrollToPage this will represent the page this pager intends to settle to. When no scroll is ongoing, this will be equal to currentPage.

Please refer to the sample to learn how to use this API.

val currentPageOffsetFraction: Float

Indicates how far the current page is to the snapped position, this will vary from -0.5 (page is offset towards the start of the layout) to 0.5 (page is offset towards the end of the layout). This is 0.0 if the currentPage is in the snapped position. The value will flip once the current page changes.

This property is observable and shouldn't be used as is in a composable function due to potential performance issues. To use it in the composition, please consider using a derived state (e.g derivedStateOf) to only have recompositions when the derived value changes.

Please refer to the sample to learn how to use this API.

Functions

suspend fun scrollToPage(
        page: Int,
        @FloatRange(from = -0.5, to = 0.5) pageOffsetFraction: Float = 0f,
    ) = scroll {
        debugLog { "Scroll from page=$currentPage to page=$page" }
        awaitScrollDependencies()
        requirePrecondition(pageOffsetFraction in -0.5..0.5) {
            "pageOffsetFraction $pageOffsetFraction is not within the range -0.5 to 0.5"
        }
        val targetPage = page.coerceInPageRange()
        snapToItem(targetPage, pageOffsetFraction, forceRemeasure = true)
    }

Scroll (jump immediately) to a given page.

Please refer to the sample to learn how to use this API.

Parameters

fun ScrollScope.updateCurrentPage(
        page: Int,
        @FloatRange(from = -0.5, to = 0.5) pageOffsetFraction: Float = 0.0f,
    )

Jump immediately to a given page with a given pageOffsetFraction inside a ScrollScope. Use this method to create custom animated scrolling experiences. This will update the value of currentPage and currentPageOffsetFraction immediately, but can only be used inside a ScrollScope, use scroll to gain access to a ScrollScope.

Please refer to the sample to learn how to use this API.

Parameters

fun ScrollScope.updateTargetPage(targetPage: Int)

Used to update targetPage during a programmatic scroll operation. This can only be called inside a ScrollScope and should be called anytime a custom scroll (through scroll) is executed in order to correctly update targetPage. This will not move the pages and it's still the responsibility of the caller to call ScrollScope.scrollBy in order to actually get to targetPage. By the end of the scroll block, when the Pager is no longer scrolling targetPage will assume the value of currentPage.

Please refer to the sample to learn how to use this API.

fun requestScrollToPage(
        @AndroidXIntRange(from = 0) page: Int,
        @FloatRange(from = -0.5, to = 0.5) pageOffsetFraction: Float = 0.0f,
    )

Requests the page to be at the snapped position during the next remeasure, offset by pageOffsetFraction, and schedules a remeasure.

The scroll position will be updated to the requested position rather than maintain the index based on the current page 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

suspend fun animateScrollToPage(
        page: Int,
        @FloatRange(from = -0.5, to = 0.5) pageOffsetFraction: Float = 0f,
        animationSpec: AnimationSpec<Float> = spring(),
    )

Scroll animate to a given page's closest snap position. If the page is too far away from currentPage we will not compose all pages in the way. We will pre-jump to a nearer page, compose and animate the rest of the pages until page.

Please refer to the sample to learn how to use this API.

Parameters

fun getOffsetDistanceInPages(page: Int): Float

An utility function to help to calculate a given page's offset. This is an offset that represents how far page is from the settled position (represented by currentPage offset). The difference here is that currentPageOffsetFraction is a value between -0.5 and 0.5 and the value calculated by this function can be larger than these numbers if page is different than currentPage.

For instance, if currentPage=0 and we call getOffsetDistanceInPages for page 3, the result will be 3, meaning the given page is 3 pages away from the current page (the sign represent the direction of the offset, positive is forward, negative is backwards). Another example is if currentPage=3 and we call getOffsetDistanceInPages for page 1, the result would be -2, meaning we're 2 pages away (moving backwards) to the current page.

This offset also works in conjunction with currentPageOffsetFraction, so if currentPage is out of its snapped position (i.e. currentPageOffsetFraction!=0) then the calculated value will still represent the offset in number of pages (in this case, not whole pages). For instance, if currentPage=1 and we're slightly offset, currentPageOffsetFraction=0.2, if we call this to page 2, the result would be 0.8, that is 0.8 page away from current page (moving forward).

Parameters

Returns