Page Indicator
Show which page of a carousel or a short sequence is current, as dots or line segments, and go to another page.
Invite your team
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/page-indicatorComplete the one-time setup first. Registry JSON lists source files and dependencies.
Usage
import { useState } from "react";
import { PageIndicator } from "@/siteplane/components/page-indicator";
export function Slides() {
const [page, setPage] = useState(1);
return <PageIndicator count={3} onPageChange={setPage} page={page} />;
}Pages
count sets the number of pages, one mark each, and page the current one, counted from 1. A click on another mark calls onPageChange with its page. Keep the page in state and change the slide or the content there; PageIndicator moves no content by itself.
Dots and lines
variant="dot", the default, draws a row of dots that is as wide as its dots. variant="line" draws a line of segments that takes the width of its container and shares it between the pages, so put the line in a container of the width you want, such as the width of the slides.
Sizes
size="md", the default, draws 8 px dots 12 px apart, or 6 px segments 8 px apart. size="lg" draws 10 px dots 16 px apart, or 8 px segments 12 px apart. A mark responds to clicks a little beyond its edge: up to 8 px above and below it at md and 12 px at lg, and halfway to its neighbor on each side. On a touch screen it responds up to 44 px high.
Framed
framed sets the marks on a translucent pill with a blur behind it, so they stay readable on an image.
Accessibility
PageIndicator is a group named “Pages”, and each mark is a button named “Page 1”, “Page 2” and so on. The current page carries aria-current="page". Tab moves through the pages, and Enter or Space goes to one; keyboard focus draws an outline around the mark. Name the group after its content with aria-label, such as “Customer stories”, and pass the names in another language with labels.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
Page | number | required | The number of pages, one mark each. |
Page | number | required | The current page, counted from 1. A page outside 1 to count marks none. |
Page | (page: number) => void | unset | Called with the page a person picks. A click on the current page calls nothing. |
Page | "dot" | "line" | "dot" | dot draws a row of dots, line a line of segments that shares the width of its container. |
Page | "md" | "lg" | "md" | md draws 8 px dots 12 px apart or 6 px segments 8 px apart, lg 10 px dots 16 px apart or 8 px segments 12 px apart. |
Page | boolean | false | Sets the marks on a translucent pill, for an indicator on an image. |
Page | Partial<PageIndicatorLabels> | English | Replaces the names, each one on its own: group ("Pages") and page, a function of the page number ("Page 1"). Pass their translation when the application is in another language. |
Page | string | labels.group | The name of the group, in place of labels.group. |
PageIndicatorProps extends the props of a div, except children, and
accepts a ref. The root carries data-variant, data-size and data-framed,
and the button of the current page data-current. The types
PageIndicatorVariant, PageIndicatorSize and PageIndicatorLabels are
exported.
Usage notes
PageIndicator shows one mark per page and suits a handful of pages. Use Pagination for a long list or a table with numbered pages, and Stepper for the steps of a task that people complete in order.
The md dots sit 20 px apart, closer than the 24 px target spacing that WCAG 2.2 asks for. Use size="lg" where people tap the dots, such as on a phone.