---
title: "PagerState"
description: "The state that can be used to control [VerticalPager] and [HorizontalPager]"
type: "class"
---

<div class='type'>Class</div>


<a id='references'></a>

<div class='sourceset sourceset-common'>Common</div>


```kotlin
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

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


#### Parameters

| | |
| --- | --- |
| currentPage | The initial page to be displayed |
| currentPageOffsetFraction | The offset of the initial page with respect to the start of the layout. |



## Properties

<div class='sourceset sourceset-common'>Common</div>


```kotlin
abstract val pageCount: Int
```


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



<div class='sourceset sourceset-common'>Common</div>


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



<div class='sourceset sourceset-common'>Common</div>


```kotlin
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`.



<div class='sourceset sourceset-common'>Common</div>


```kotlin
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.



<div class='sourceset sourceset-common'>Common</div>


```kotlin
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.



<div class='sourceset sourceset-common'>Common</div>


```kotlin
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.



<div class='sourceset sourceset-common'>Common</div>


```kotlin
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

```kotlin
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

| | |
| --- | --- |
| page | The destination page to scroll to |
| pageOffsetFraction | A fraction of the page size that indicates the offset the destination page will be offset from its snapped position. |



```kotlin
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

| | |
| --- | --- |
| page | The destination page to scroll to |
| pageOffsetFraction | A fraction of the page size that indicates the offset the destination page will be offset from its snapped position. |



```kotlin
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.


```kotlin
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

| | |
| --- | --- |
| page | the index to which to scroll. Must be non-negative. |
| pageOffsetFraction | the offset fraction that the page should end up after the scroll. |



```kotlin
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

| | |
| --- | --- |
| page | The destination page to scroll to |
| pageOffsetFraction | A fraction of the page size that indicates the offset the destination page will be offset from its snapped position. |
| animationSpec | An `AnimationSpec` to move between pages. We'll use a `spring` as the default animation. |



```kotlin
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

| | |
| --- | --- |
| page | The page to calculate the offset from. This should be between 0 and `pageCount`. |


#### Returns

| | |
| --- | --- |
|  | The offset of `page` with respect to `currentPage`. |