# Jetpack Compose: Understanding Pager

> How Pager actually lays out and snaps pages, and the state you need to read to build custom page transitions.

**Date:** 2026-10-30T00:00:00.000Z
**Tags:** Pager, Layout

## What Pager actually is

`HorizontalPager` and `VerticalPager` are the composables behind a
swipeable, snapping sequence of full-size pages: onboarding screens,
image carousels, and tab content that slides instead of cutting between
screens. Each page is its own composable; the pager lays them out side
by side and handles the drag/fling gesture that moves between them.

`rememberPagerState(pageCount = { ... })` creates the `PagerState` that
drives it. That state reports back *where the user is*, not just *which
page*, and that distinction, not the layout itself, is what the rest of
this post is about.

## The intuition

Treat `Pager` like a `Tab` row and you'll assume it only tells you *which*
page is selected. `TabRow`'s `selectedTabIndex` works that way: just an
integer that jumps from `0` to `1`. Build a page transition on that same
assumption and it snaps instead of gliding, because you're throwing away
the one piece of state that makes a smooth transition possible.

* `pagerState.currentPage` is already the nearest page to wherever the
  pager currently sits, mid-drag included. It flips the instant you cross
  the halfway point between two pages, not when the drag or fling
  actually ends.
* `pagerState.currentPageOffsetFraction` is the part `currentPage` throws
  away: a continuous float, roughly `-0.5` to `0.5`, saying how far you've
  moved past `currentPage` toward the previous (`<0`) or next (`>0`) page.
* Every frame of a drag reports a different offset fraction. That's the
  signal you read to scale a card, fade a neighbor, or morph an indicator
  in step with the user's finger, not `currentPage` alone, which has no
  "how far" in it.

`Pager` also makes layout decisions from that same state: `pageSize`
controls how much of each page is visible, `pageSpacing` sets the gap
between pages, and `contentPadding` controls how much of a neighbor peeks
in from the edge. All three are measured once per page and don't change
with scroll position. Only the offset fraction updates every frame.

## Concrete example: reading the offset to scale a card

```kotlin
val pagerState = rememberPagerState(pageCount = { 6 })

HorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxWidth(),
    contentPadding = PaddingValues(horizontal = 64.dp),
) { page ->
    Card(
        modifier = Modifier
            .graphicsLayer {
                // Signed distance, in page-widths, from this page to
                // currentPage's settled slot. 0f exactly when this page
                // is the one settled there, growing toward ±1f as a
                // neighbor is still a full page-width away from it.
                val pageOffset =
                    (pagerState.currentPage - page + pagerState.currentPageOffsetFraction)
                        .absoluteValue
                val scale = lerp(0.7f, 1f, 1 - pageOffset.coerceIn(0f, 1f))
                scaleX = scale
                scaleY = scale
            }
            .fillMaxWidth()
            .height(240.dp)
    ) { /* ... */ }
}
```

`currentPage - page` gives each page's integer distance from
`currentPage`'s settled slot. Adding `currentPageOffsetFraction` turns
that into a continuous signed distance, updating every frame of the drag
instead of only when a page settles. `pageOffset == 0f` means "this page
is the one settled into that slot right now," `±1f` means "a full
page-width away from it." The slot only *looks* centered here because of
the symmetric `contentPadding`; the fraction itself has no idea where on
screen that slot sits.

That continuous value is what
`lerp` (Blending between a start and an end value by how far along you are: 0 gives the start value, 1 gives the end value, and every point between is some mix of the two.)
needs. Feed it `currentPage` alone instead, and the scale jumps in steps
rather than tracking the finger.

Try it: drag the cards below and watch `currentPage` and the offset update
in real time, including the snap back on release.

*\[Interactive demo: PagerOffsetDemo — view this post in a browser for the live version.]*

[Video](/posts/understanding-pager/demo.mp4)

*Dragging the pager on a real device, with each neighboring card scaling up as it approaches currentPage's settled slot and shrinking as it slides away, in sync with the finger. The debug readout below it shows currentPage, settledPage, targetPage, currentPageOffsetFraction, and isScrollInProgress updating live.*

## More cases: the same offset, read differently

The offset fraction shows up anywhere a swipe needs to feel continuous,
not just in this blog's own Draw-series posts:

* A peeking neighbor layout reads `contentPadding` and `pageSpacing` to
  decide how much of the next page shows at rest, then reads
  `currentPageOffsetFraction` to slide/scale that sliver as the user drags.
* A morphing page indicator reads the same fraction to blend one dot's
  shape into the next instead of swapping between two static states.
* An onboarding flow scales and fades the current step's illustration
  down as the next one scales in, off the same fraction, instead of
  crossfading between two static screens.
* A story viewer (Instagram, WhatsApp Status) shrinks and dims the
  outgoing story while the incoming one scales up to full size as you
  swipe, rather than cutting straight from one to the other.
* A photo carousel reuses the exact scale-by-offset formula from the
  concrete example above, just with photos in place of numbered cards.

Different visual, same underlying read: `currentPage`,
`currentPageOffsetFraction`, and the per-page distance that formula above
computes.

> **The fundamental**
>
> This is **continuous scroll progress**: a gesture's state is represented
> as a float that updates every frame the gesture is in flight, not just a
> discrete "before" and "after."
>
> `currentPage` is the anchor. `currentPageOffsetFraction` is the progress
> toward the next anchor. Together, they're a richer signal than either
> one alone.
>
> `pagerState.isScrollInProgress` tells you when that continuous read
> actually matters: true while a drag, fling, or programmatic scroll is
> in progress, false once it settles.

## Elsewhere: same fundamental, different framework

* **Android's View-based `ViewPager`/`ViewPager2`**: the direct ancestor
  of this exact model.
  `onPageScrolled(position, positionOffset, positionOffsetPixels)`
  hands you an integer page and a `[0, 1)` float offset, the same
  two-part shape `currentPage`/`currentPageOffsetFraction` continues in
  Compose.
* **SwiftUI's `scrollTransition`**: inside a page-style `ScrollView` or
  `TabView`, the phase it hands each item is a continuous float as that
  item crosses the viewport, not just a "which page" index. Same
  two-part read as `currentPage`/`currentPageOffsetFraction`, just
  reported per item instead of per pager.
* **CSS scroll-driven animations**: `animation-timeline: scroll()` ties
  an animation's progress directly to scroll position instead of time.
  The animation becomes a continuous function of how far you've
  scrolled, exactly like driving `scaleX`/`scaleY` off
  `currentPageOffsetFraction`.
* **Swiper.js** (the web carousel library): exposes a `progress` value
  per slide, roughly `-1` to `1`, for building exactly this kind of
  scale/parallax effect as slides pass center.

## Edge cases

* **`currentPage` can skip more than one index.** A fast fling can carry
  the pager past several pages before it settles; don't write transition
  code that assumes `currentPage` only ever changes by ±1 between frames.
  Read `pagerState.targetPage` if you need to know where that fling will
  land before it gets there.
* **`currentPage` vs `settledPage`.** `currentPage` updates continuously
  during a drag or fling, including every intermediate page a fast fling
  passes through. `settledPage` only updates once the pager actually
  comes to rest. Read `settledPage` when the question is "did the user
  finish changing pages," and `currentPage` when it's "where is the
  pager right now."
* **`pageSpacing` and `contentPadding` interact.** Padding controls how
  much neighboring pages peek in from the container edges; spacing adds a
  gap between pages on top of that. Setting one without accounting for
  the other is a common source of pages looking closer together or
  further apart than intended.
* **The sign isn't literally "left" and "right."** `currentPageOffsetFraction`
  is negative toward the layout's start and positive toward its end, and
  start/end are logical directions. In a left-to-right layout that does
  mean negative-left, positive-right, but flip to an RTL locale or set
  `reverseLayout = true` and start/end swap sides on screen, so the sign
  swaps with them. Code that hardcodes "positive means card exits left"
  breaks under RTL.

## Mental model to actually use

**Don't ask "which page is selected." Ask "where exactly, as a
continuous value, is the pager right now," and read `currentPage` +
`currentPageOffsetFraction` together to answer it.**


---

Canonical page: https://recomposed.blog/understanding-pager