{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

PagerKt

public final class PagerKt


Summary

Public methods

static final void
@Composable
@ExperimentalFoundationApi
HorizontalPager(
    @NonNull PagerState state,
    @NonNull Modifier modifier,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Vertical verticalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

A Pager that scrolls horizontally.

static final void
@Composable
@ExperimentalFoundationApi
HorizontalPager(
    int pageCount,
    @NonNull Modifier modifier,
    @NonNull PagerState state,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Vertical verticalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

This method is deprecated. Please use the overload without pageCount. pageCount should be provided through PagerState.

static final void
@Composable
@ExperimentalFoundationApi
VerticalPager(
    @NonNull PagerState state,
    @NonNull Modifier modifier,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Horizontal horizontalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

A Pager that scrolls vertically.

static final void
@Composable
@ExperimentalFoundationApi
VerticalPager(
    int pageCount,
    @NonNull Modifier modifier,
    @NonNull PagerState state,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Horizontal horizontalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

This method is deprecated. Please use the overload without pageCount. pageCount should be provided through PagerState.

Public methods

HorizontalPager

@Composable
@ExperimentalFoundationApi
public static final void HorizontalPager(
    @NonNull PagerState state,
    @NonNull Modifier modifier,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Vertical verticalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

A Pager that scrolls horizontally. Pages are lazily placed in accordance to the available viewport size. By definition, pages in a Pager have the same size, defined by pageSize and use a snap animation (provided by flingBehavior to scroll pages into a specific position). You can use beyondBoundsPageCount to place more pages before and after the visible pages.

If you need snapping with pages of different size, you can use a SnapFlingBehavior with a SnapLayoutInfoProvider adapted to a LazyList.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.pager.HorizontalPager
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// Creates a 1-pager/viewport horizontal pager with single page snapping
val state = rememberPagerState { 10 }
HorizontalPager(
    state = state,
    modifier = Modifier.fillMaxSize(),
) { page ->
    Box(
        modifier = Modifier
            .padding(10.dp)
            .background(Color.Blue)
            .fillMaxWidth()
            .aspectRatio(1f),
        contentAlignment = Alignment.Center
    ) {
        Text(text = page.toString(), fontSize = 32.sp)
    }
}
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.offset
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.pager.HorizontalPager
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.Text
import androidx.compose.material.TopAppBar
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.input.nestedscroll.NestedScrollConnection
import androidx.compose.ui.input.nestedscroll.NestedScrollSource
import androidx.compose.ui.input.nestedscroll.nestedScroll
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.Density
import androidx.compose.ui.unit.IntOffset
import androidx.compose.ui.unit.dp

// This is a sample using NestedScroll and Pager.
// We use the toolbar offset changing example from
// androidx.compose.ui.samples.NestedScrollConnectionSample

val pagerState = rememberPagerState { 10 }

val toolbarHeight = 48.dp
val toolbarHeightPx = with(LocalDensity.current) { toolbarHeight.roundToPx().toFloat() }
val toolbarOffsetHeightPx = remember { mutableStateOf(0f) }
val nestedScrollConnection = remember {
    object : NestedScrollConnection {
        override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
            val delta = available.y
            val newOffset = toolbarOffsetHeightPx.value + delta
            toolbarOffsetHeightPx.value = newOffset.coerceIn(-toolbarHeightPx, 0f)
            return Offset.Zero
        }
    }
}

Box(
    modifier = Modifier
        .fillMaxSize()
        .nestedScroll(nestedScrollConnection)
) {
    TopAppBar(
        modifier = Modifier
            .height(toolbarHeight)
            .offset { IntOffset(x = 0, y = toolbarOffsetHeightPx.value.roundToInt()) },
        title = { Text("Toolbar offset is ${toolbarOffsetHeightPx.value}") }
    )

    val paddingOffset =
        toolbarHeight + with(LocalDensity.current) { toolbarOffsetHeightPx.value.toDp() }

    HorizontalPager(
        modifier = Modifier.fillMaxSize(),
        state = pagerState,
        contentPadding = PaddingValues(top = paddingOffset)
    ) {
        Column(
            modifier = Modifier
                .fillMaxWidth()
                .verticalScroll(rememberScrollState())
        ) {
            repeat(20) {
                Box(
                    modifier = Modifier
                        .fillMaxWidth()
                        .height(64.dp)
                        .padding(4.dp)
                        .background(if (it % 2 == 0) Color.Black else Color.Yellow),
                    contentAlignment = Alignment.Center
                ) {
                    Text(
                        text = it.toString(),
                        color = if (it % 2 != 0) Color.Black else Color.Yellow
                    )
                }
            }
        }
    }
}
Parameters
@NonNull PagerState state

The state to control this pager

@NonNull Modifier modifier

A modifier instance to be applied to this Pager outer layout

@NonNull PaddingValues contentPadding

a padding around the whole content. This will add padding for the content after it has been clipped, which is not possible via modifier param. You can use it to add a padding before the first page or after the last one. Use pageSpacing to add spacing between the pages.

@NonNull PageSize pageSize

Use this to change how the pages will look like inside this pager.

int beyondBoundsPageCount

Pages to load before and after the list of visible pages. Note: Be aware that using a large value for beyondBoundsPageCount will cause a lot of pages to be composed, measured and placed which will defeat the purpose of using lazy loading. This should be used as an optimization to pre-load a couple of pages before and after the visible ones.

@NonNull Dp pageSpacing

The amount of space to be used to separate the pages in this Pager

@NonNull Alignment.Vertical verticalAlignment

How pages are aligned vertically in this Pager.

@NonNull SnapFlingBehavior flingBehavior

The FlingBehavior to be used for post scroll gestures.

boolean userScrollEnabled

whether the scrolling via the user gestures or accessibility actions is allowed. You can still scroll programmatically using PagerState.scroll even when it is disabled.

boolean reverseLayout

reverse the direction of scrolling and layout.

Function1<@NonNull Integer, @NonNull Object> key

a stable and unique key representing the item. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

@NonNull NestedScrollConnection pageNestedScrollConnection

A NestedScrollConnection that dictates how this Pager behaves with nested lists. The default behavior will see Pager to consume all nested deltas.

@Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent

This Pager's page Composable.

See also
SnapLayoutInfoProvider

for the implementation of a SnapLayoutInfoProvider that uses androidx.compose.foundation.lazy.LazyListState.

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

HorizontalPager

@Composable
@ExperimentalFoundationApi
public static final void HorizontalPager(
    int pageCount,
    @NonNull Modifier modifier,
    @NonNull PagerState state,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Vertical verticalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

A Pager that scrolls horizontally. Pages are lazily placed in accordance to the available viewport size. By definition, pages in a Pager have the same size, defined by pageSize and use a snap animation (provided by flingBehavior to scroll pages into a specific position). You can use beyondBoundsPageCount to place more pages before and after the visible pages.

If you need snapping with pages of different size, you can use a SnapFlingBehavior with a SnapLayoutInfoProvider adapted to a LazyList.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.pager.HorizontalPager
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// Creates a 1-pager/viewport horizontal pager with single page snapping
val state = rememberPagerState { 10 }
HorizontalPager(
    state = state,
    modifier = Modifier.fillMaxSize(),
) { page ->
    Box(
        modifier = Modifier
            .padding(10.dp)
            .background(Color.Blue)
            .fillMaxWidth()
            .aspectRatio(1f),
        contentAlignment = Alignment.Center
    ) {
        Text(text = page.toString(), fontSize = 32.sp)
    }
}
Parameters
int pageCount

The number of pages this Pager will contain

@NonNull Modifier modifier

A modifier instance to be applied to this Pager outer layout

@NonNull PagerState state

The state to control this pager

@NonNull PaddingValues contentPadding

a padding around the whole content. This will add padding for the content after it has been clipped, which is not possible via modifier param. You can use it to add a padding before the first page or after the last one. Use pageSpacing to add spacing between the pages.

@NonNull PageSize pageSize

Use this to change how the pages will look like inside this pager.

int beyondBoundsPageCount

Pages to load before and after the list of visible pages. Note: Be aware that using a large value for beyondBoundsPageCount will cause a lot of pages to be composed, measured and placed which will defeat the purpose of using lazy loading. This should be used as an optimization to pre-load a couple of pages before and after the visible ones.

@NonNull Dp pageSpacing

The amount of space to be used to separate the pages in this Pager

@NonNull Alignment.Vertical verticalAlignment

How pages are aligned vertically in this Pager.

@NonNull SnapFlingBehavior flingBehavior

The FlingBehavior to be used for post scroll gestures.

boolean userScrollEnabled

whether the scrolling via the user gestures or accessibility actions is allowed. You can still scroll programmatically using PagerState.scroll even when it is disabled.

boolean reverseLayout

reverse the direction of scrolling and layout.

Function1<@NonNull Integer, @NonNull Object> key

a stable and unique key representing the page. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove pages before the current visible page the page with the given key will be kept as the first visible one.

@NonNull NestedScrollConnection pageNestedScrollConnection

A NestedScrollConnection that dictates how this Pager behaves with nested lists. The default behavior will see Pager to consume all nested deltas.

@Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent

This Pager's page Composable.

See also
SnapLayoutInfoProvider

for the implementation of a SnapLayoutInfoProvider that uses androidx.compose.foundation.lazy.LazyListState.

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

VerticalPager

@Composable
@ExperimentalFoundationApi
public static final void VerticalPager(
    @NonNull PagerState state,
    @NonNull Modifier modifier,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Horizontal horizontalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

A Pager that scrolls vertically. Pages are lazily placed in accordance to the available viewport size. By definition, pages in a Pager have the same size, defined by pageSize and use a snap animation (provided by flingBehavior to scroll pages into a specific position). You can use beyondBoundsPageCount to place more pages before and after the visible pages.

If you need snapping with pages of different size, you can use a SnapFlingBehavior with a SnapLayoutInfoProvider adapted to a LazyList.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.pager.VerticalPager
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// Creates a 1-pager/viewport vertical pager with single page snapping
val state = rememberPagerState { 10 }
VerticalPager(
    state = state,
    modifier = Modifier.fillMaxSize()
) { page ->
    Box(
        modifier = Modifier
            .padding(10.dp)
            .background(Color.Blue)
            .fillMaxWidth()
            .aspectRatio(1f),
        contentAlignment = Alignment.Center
    ) {
        Text(text = page.toString(), fontSize = 32.sp)
    }
}
Parameters
@NonNull PagerState state

The state to control this pager

@NonNull Modifier modifier

A modifier instance to be apply to this Pager outer layout

@NonNull PaddingValues contentPadding

a padding around the whole content. This will add padding for the content after it has been clipped, which is not possible via modifier param. You can use it to add a padding before the first page or after the last one. Use pageSpacing to add spacing between the pages.

@NonNull PageSize pageSize

Use this to change how the pages will look like inside this pager.

int beyondBoundsPageCount

Pages to load before and after the list of visible pages. Note: Be aware that using a large value for beyondBoundsPageCount will cause a lot of pages to be composed, measured and placed which will defeat the purpose of using lazy loading. This should be used as an optimization to pre-load a couple of pages before and after the visible ones.

@NonNull Dp pageSpacing

The amount of space to be used to separate the pages in this Pager

@NonNull Alignment.Horizontal horizontalAlignment

How pages are aligned horizontally in this Pager.

@NonNull SnapFlingBehavior flingBehavior

The FlingBehavior to be used for post scroll gestures.

boolean userScrollEnabled

whether the scrolling via the user gestures or accessibility actions is allowed. You can still scroll programmatically using PagerState.scroll even when it is disabled.

boolean reverseLayout

reverse the direction of scrolling and layout.

Function1<@NonNull Integer, @NonNull Object> key

a stable and unique key representing the item. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one.

@NonNull NestedScrollConnection pageNestedScrollConnection

A NestedScrollConnection that dictates how this Pager behaves with nested lists. The default behavior will see Pager to consume all nested deltas.

@Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent

This Pager's page Composable.

See also
SnapLayoutInfoProvider

for the implementation of a SnapLayoutInfoProvider that uses androidx.compose.foundation.lazy.LazyListState.

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

VerticalPager

@Composable
@ExperimentalFoundationApi
public static final void VerticalPager(
    int pageCount,
    @NonNull Modifier modifier,
    @NonNull PagerState state,
    @NonNull PaddingValues contentPadding,
    @NonNull PageSize pageSize,
    int beyondBoundsPageCount,
    @NonNull Dp pageSpacing,
    @NonNull Alignment.Horizontal horizontalAlignment,
    @NonNull SnapFlingBehavior flingBehavior,
    boolean userScrollEnabled,
    boolean reverseLayout,
    Function1<@NonNull Integer, @NonNull Object> key,
    @NonNull NestedScrollConnection pageNestedScrollConnection,
    @Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent
)

A Pager that scrolls vertically. Pages are lazily placed in accordance to the available viewport size. By definition, pages in a Pager have the same size, defined by pageSize and use a snap animation (provided by flingBehavior to scroll pages into a specific position). You can use beyondBoundsPageCount to place more pages before and after the visible pages.

If you need snapping with pages of different size, you can use a SnapFlingBehavior with a SnapLayoutInfoProvider adapted to a LazyList.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.aspectRatio
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.pager.VerticalPager
import androidx.compose.foundation.pager.rememberPagerState
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp

// Creates a 1-pager/viewport vertical pager with single page snapping
val state = rememberPagerState { 10 }
VerticalPager(
    state = state,
    modifier = Modifier.fillMaxSize()
) { page ->
    Box(
        modifier = Modifier
            .padding(10.dp)
            .background(Color.Blue)
            .fillMaxWidth()
            .aspectRatio(1f),
        contentAlignment = Alignment.Center
    ) {
        Text(text = page.toString(), fontSize = 32.sp)
    }
}
Parameters
int pageCount

The number of pages this Pager will contain

@NonNull Modifier modifier

A modifier instance to be apply to this Pager outer layout

@NonNull PagerState state

The state to control this pager

@NonNull PaddingValues contentPadding

a padding around the whole content. This will add padding for the content after it has been clipped, which is not possible via modifier param. You can use it to add a padding before the first page or after the last one. Use pageSpacing to add spacing between the pages.

@NonNull PageSize pageSize

Use this to change how the pages will look like inside this pager.

int beyondBoundsPageCount

Pages to load before and after the list of visible pages. Note: Be aware that using a large value for beyondBoundsPageCount will cause a lot of pages to be composed, measured and placed which will defeat the purpose of using lazy loading. This should be used as an optimization to pre-load a couple of pages before and after the visible ones.

@NonNull Dp pageSpacing

The amount of space to be used to separate the pages in this Pager

@NonNull Alignment.Horizontal horizontalAlignment

How pages are aligned horizontally in this Pager.

@NonNull SnapFlingBehavior flingBehavior

The FlingBehavior to be used for post scroll gestures.

boolean userScrollEnabled

whether the scrolling via the user gestures or accessibility actions is allowed. You can still scroll programmatically using PagerState.scroll even when it is disabled.

boolean reverseLayout

reverse the direction of scrolling and layout.

Function1<@NonNull Integer, @NonNull Object> key

a stable and unique key representing the page. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove pages before the current visible page the page with the given key will be kept as the first visible one.

@NonNull NestedScrollConnection pageNestedScrollConnection

A NestedScrollConnection that dictates how this Pager behaves with nested lists. The default behavior will see Pager to consume all nested deltas.

@Composable @ExtensionFunctionType @NonNull Function2<@NonNull PagerScope, @NonNull IntegerUnit> pageContent

This Pager's page Composable.

See also
SnapLayoutInfoProvider

for the implementation of a SnapLayoutInfoProvider that uses androidx.compose.foundation.lazy.LazyListState.

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