Page Control
A row of dots, one for each page, the current one solid, that shows where a person is in a flat list of pages and moves between them, as the iOS 26 page control does.
import { PageControl } from "@plexui/ui/components/PageControl";A page control shows the position of the current page in an ordered list of peer pages, such as a carousel or onboarding, and moves between them. Center it below the pages. More than about ten dots are hard to count at a glance; for longer lists, prefer a grid. It follows the iOS 26 kit Page control on every screen: 8px dots 8px apart in a 24px capsule, with a 44px target on a phone.
Examples
Overview
Many pages
Background
API
| Prop | Type | Default | Description |
|---|---|---|---|
count | number | — | Number of pages |
value | number | — | Controlled index of the current page, from 0 |
defaultValue | number | 0 | Initial page (uncontrolled) |
onChange | (index: number, details: { scrubbing: boolean }) => void | — | Called with the index of the next page; scrubbing is true while a drag scrubs |
background | "automatic" | "prominent" | "minimal" | "automatic" | When the capsule behind the dots shows; minimal also turns off scrubbing |
valueText | (index: number, count: number) => string | Page 2 of 5 | Text assistive technology reads for the current page |
aria-label | string | "Pages" | Name of the page control, when no visible label names it |
aria-labelledby | string | — | The id of the visible label of the page control |
aria-controls | string | — | The id of the element that shows the pages |
id | string | — | The id of the page control |
onFocus | FocusEventHandler<HTMLDivElement> | — | Called when the page control gains focus |
onBlur | FocusEventHandler<HTMLDivElement> | — | Called when the page control loses focus |
className | string | — | CSS classes applied to the page control |
The page control is a slider whose value is the page, read as Page 2 of 5, as VoiceOver reads the native control as adjustable. With the keyboard, Left and Right (mirrored in a right-to-left layout) or Up and Down move one page, Home and End go to the first and last page. The dots are presentation only.
Styling
PageControl reads these component tokens. Override them at any scope to restyle it:
--page-control-height,--page-control-padding-inline: the capsule (default24px,12px)--page-control-gap: space between dots (default8px)--page-control-dot-size,--page-control-dot-size-small,--page-control-dot-size-smaller: the full dot and the two shrinking ones (default8px,6px,4px)--page-control-dot-color,--page-control-dot-color-current: the dots (defaultvar(--alpha-30),var(--color-text); the other dots in the tertiary label,--mobile-label-tertiary, on a phone withtouch.css)--page-control-background: the capsule fill withautomaticandprominent(defaultvar(--alpha-08))--page-control-target-size: height of the touch target (44pxat 767px and below)--page-control-transition-duration: how fast dots change (default200ms, none with reduced motion)