HorizontalPageIndicator

Component in Wear Material 3 Compose

Horizontal page indicator for use with [HorizontalPager], representing the currently active page and the total number of pages. Pages are indicated as a Circle shape. The indicator shows up to six pages individually - if there are more than six pages, [HorizontalPageIndicator] shows a half-size indicator to the left or right to indicate that more are available.

Here's how different positions 0..10 might be visually represented: "X" is selected item, "O" and "o" full and half size items respectively.

O X O O O o - 2nd position out of 10. There are no more items on the left but more on the right o O O O X o - current page could be 6, 7 or 8 out of 10, as there are more possible items on the left and on the right o O O O X O - current page is 9 out of 10, as there're no more items on the right

[HorizontalPageIndicator] can be linear or curved, depending on the screen shape of the device - for circular screens it will be curved, whilst for square screens it will be linear.

Last updated: 2024-09-07 14:23

Installation

dependencies {
   implementation("androidx.wear.compose:compose-material3:1.0.0-alpha24")
}

Overloads

@Composable
fun HorizontalPageIndicator(
    pageCount: Int,
    currentPage: Int,
    currentPageOffsetFraction: () -> Float,
    modifier: Modifier = Modifier,
    selectedColor: Color = MaterialTheme.colorScheme.onBackground,
    unselectedColor: Color = selectedColor.copy(alpha = 0.3f),
    indicatorSize: Dp = 6.dp,
    spacing: Dp = 4.dp
)

Parameters

name	description
pageCount	Total number of pages
currentPage	The currently selected page index
currentPageOffsetFraction	The offset fraction of the currently selected page. Represents the offset as a fraction of the transition from the selected page to the next or previous page. Can be positive or negative.
modifier	Modifier to be applied to the [HorizontalPageIndicator]
selectedColor	The color of the selected [HorizontalPageIndicator] item
unselectedColor	The color of unselected [HorizontalPageIndicator] items. Defaults to [selectedColor] with 30% alpha
indicatorSize	The size of each [HorizontalPageIndicator] item in [Dp]
spacing	The spacing between indicator items in [Dp]

Code Examples

HorizontalPageIndicatorSample

@OptIn(ExperimentalWearMaterial3Api::class)
@Composable
fun HorizontalPageIndicatorSample() {
    val pageCount = 9
    var selectedPage by remember { mutableStateOf(0) }

    val animatedSelectedPage by
        animateFloatAsState(
            targetValue = selectedPage.toFloat(),
            label = "animateSelectedPage",
        )

    Box(modifier = Modifier.fillMaxSize()) {
        InlineSlider(
            modifier = Modifier.align(Alignment.Center),
            value = selectedPage,
            increaseIcon = { Icon(InlineSliderDefaults.Increase, "Increase") },
            decreaseIcon = { Icon(InlineSliderDefaults.Decrease, "Decrease") },
            valueProgression = 0 until pageCount,
            onValueChange = { selectedPage = it }
        )
        HorizontalPageIndicator(
            pageCount = pageCount,
            currentPage = selectedPage,
            currentPageOffsetFraction = { animatedSelectedPage - selectedPage },
        )
    }
}

HorizontalPageIndicatorWithPagerSample

@Composable
fun HorizontalPageIndicatorWithPagerSample(swipeState: SwipeToDismissBoxState) {
    val pageCount = 9
    val pagerState = rememberPagerState { pageCount }

    Box {
        HorizontalPager(
            modifier = Modifier.fillMaxSize().edgeSwipeToDismiss(swipeState),
            state = pagerState,
        ) { page ->
            Box(modifier = Modifier.fillMaxSize()) {
                Text(modifier = Modifier.align(Alignment.Center), text = "Page #$page")
            }
        }
        HorizontalPageIndicator(
            pageCount = pageCount,
            currentPage = pagerState.currentPage,
            currentPageOffsetFraction = { pagerState.currentPageOffsetFraction },
        )
    }
}