Root Props
| Prop | Type | Default |
|---|---|---|
active | number | — |
| Controlled active index. | ||
defaultActive | number | 0 |
| Uncontrolled initial active index. | ||
onChangeActive | (value: number) => void | — |
| Callback that is triggered when the user selects a different page. Receives the new index as a number. | ||
ref | Ref<HTMLUListElement> | — |
Ref forwarded to the underlying <ul> element. | ||
size | PageControlSize | 'md' |
| Defines the size of the page control items. | ||
Also accepts all <ul> attributes.
Child Parts
PageControlItem: standard dot item.PageControlProgress: progress-style animated item.
PageControlItem
| Prop | Type | Default |
|---|---|---|
indexrequired | number | — |
| Index of the page item (zero-based). Used to identify and compare with the active index from context. | ||
ref | Ref<HTMLButtonElement> | — |
| Ref forwarded to the underlying button element. | ||
current | boolean | — |
Forces this item to be marked as active, regardless of the context. If not provided, active state is determined by comparing index with the active index from context. | ||
size | PageControlSize | — |
| Defines the size of the page control items. | ||
Also accepts all <button> attributes.
PageControlProgress
| Prop | Type | Default |
|---|---|---|
indexrequired | number | — |
| Index of the page item (zero-based). Used to determine whether this item is currently active. | ||
duration | number | 5000 |
| Duration of the progress animation in milliseconds. Controls how long the visual fill takes to complete. Defaults to 5000ms if not provided. | ||
ref | Ref<HTMLButtonElement> | — |
| Ref forwarded to the underlying button element. | ||
current | boolean | — |
| Whether this page item is currently active. If not provided, active state is inferred from context. | ||
size | PageControlSize | — |
| Defines the size of the page control items. | ||
Also accepts all <button> attributes.
Types
PageControlPropsPageControlItemPropsPageControlProgressProps
State Model
- The root supports controlled and uncontrolled active state.
- Arrow keys change active item left/right.
- Pointer dragging on touch and pen can sweep across items.