Pagination
Page navigation with arrows, numbers, and collapsed ranges.
API Reference
Original primitive API
Behavior, accessibility details, and low-level props are documented by Base UI.
Basic
import { Pagination } from "moduix";export function PaginationDemo() { return <Pagination count={10} defaultPage={1} />;}Full list of component variables available for project-level overrides.
| Property | Default | Description |
|---|---|---|
| --pagination-arrow-padding-inline | 0 | Controls arrow item inline padding. |
| --pagination-disabled-opacity | var(--opacity-disabled) | Controls disabled pagination opacity. |
| --pagination-ellipsis-color | var(--color-muted-foreground) | Controls ellipsis color. |
| --pagination-font-size | var(--text-sm) | Controls pagination font size. |
| --pagination-font-size-xs | var(--text-xs) | Controls pagination font size for xs size. |
| --pagination-font-size-sm | var(--text-xs) | Controls pagination font size for sm size. |
| --pagination-font-size-md | var(--text-sm) | Controls pagination font size for md size. |
| --pagination-font-size-lg | var(--text-md) | Controls pagination font size for lg size. |
| --pagination-font-size-xl | var(--text-lg) | Controls pagination font size for xl size. |
| --pagination-font-weight | var(--weight-medium) | Controls pagination font weight. |
| --pagination-item-bg | var(--color-background) | Controls item background color. |
| --pagination-item-bg-active | var(--color-foreground) | Controls active item background color. |
| --pagination-item-bg-hover | var(--color-accent) | Controls hover item background color. |
| --pagination-item-border-color | var(--color-border) | Controls item border color. |
| --pagination-item-border-color-active | var(--color-foreground) | Controls active item border color. |
| --pagination-item-color | var(--color-foreground) | Controls item text color. |
| --pagination-item-color-active | var(--color-background) | Controls active item text color. |
| --pagination-item-radius | var(--radius-md) | Controls item corner radius. |
| --pagination-item-size | var(--size-lg) | Controls item width and height. |
| --pagination-item-size-xs | var(--size-xs) | Controls item size for xs size. |
| --pagination-item-size-sm | var(--size-sm) | Controls item size for sm size. |
| --pagination-item-size-md | var(--size-lg) | Controls item size for md size. |
| --pagination-item-size-lg | var(--size-xl) | Controls item size for lg size. |
| --pagination-item-size-xl | 3.5rem | Controls item size for xl size. |
| --pagination-line-height | var(--line-height-text-sm) | Controls pagination line height. |
| --pagination-line-height-xs | var(--line-height-text-xs) | Controls pagination line height for xs size. |
| --pagination-line-height-sm | var(--line-height-text-xs) | Controls pagination line height for sm size. |
| --pagination-line-height-md | var(--line-height-text-sm) | Controls pagination line height for md size. |
| --pagination-line-height-lg | var(--line-height-text-md) | Controls pagination line height for lg size. |
| --pagination-line-height-xl | var(--line-height-text-lg) | Controls pagination line height for xl size. |
| --pagination-toolbar-bg | transparent | Controls toolbar background color. |
| --pagination-toolbar-border-color | transparent | Controls toolbar border color. |
| --pagination-toolbar-gap | var(--spacing-1) | Controls gap between items. |
| --pagination-toolbar-padding | 0 | Controls toolbar padding for all variants. |
| --pagination-toolbar-padding-filled | 0.125rem | Controls toolbar padding for default and outline variants. |
Interactive variables scoped for docs preview without changing size scale tokens.
| Property | Value | Default | Description |
|---|---|---|---|
| --pagination-ellipsis-color | var(--color-muted-foreground) | Controls ellipsis color. | |
| --pagination-item-bg | var(--color-background) | Controls item background color. | |
| --pagination-item-bg-active | var(--color-foreground) | Controls active item background color. | |
| --pagination-item-bg-hover | var(--color-accent) | Controls hover item background color. | |
| --pagination-item-border-color | var(--color-border) | Controls item border color. | |
| --pagination-item-border-color-active | var(--color-foreground) | Controls active item border color. | |
| --pagination-item-color-active | var(--color-background) | Controls active item text color. | |
| --pagination-item-radius | var(--radius-md) | Controls item corner radius. | |
| --pagination-item-size | var(--size-lg) | Controls item width and height. | |
| --pagination-toolbar-bg | transparent | Controls toolbar background color. | |
| --pagination-toolbar-border-color | transparent | Controls toolbar border color. | |
| --pagination-toolbar-padding-filled | 0.125rem | Controls filled toolbar padding. |
Anatomy
Pagination is built on top of Toolbar and renders page controls as focusable toolbar items.
It can include arrow controls, page number controls, and non-interactive ellipsis markers.
Pagination
└─ Toolbar
├─ previous control (optional)
├─ page controls (optional)
├─ ellipsis markers (when range is collapsed)
└─ next control (optional)<Pagination count={10} defaultPage={5} />| Part | Role |
|---|---|
Pagination | Root navigation region. Controls current page, range logic, variants, and sizing. |
previous control | Moves to the previous page when arrows are enabled. |
page controls | Select a specific page and expose the current page with aria-current="page". |
ellipsis marker | Indicates hidden pages when the full range is collapsed into the middle window. |
next control | Moves to the next page when arrows are enabled. |
The component has no portal/backdrop service slots. Style it directly with className and CSS variables.
Composition
Use uncontrolled mode with defaultPage for local state. Use controlled mode with page and
onPageChange when pagination must stay in sync with URL state or external filters.
Use getPageHref to map pages to links for any URL scheme, such as /page/7 or ?page=7.
Use showArrows and showPages to keep only the controls you need for the layout.
Examples
Numbers Only
Hide arrow controls when only direct page selection is needed.
import { Pagination } from "moduix";export function PaginationNumbersOnlyDemo() { return <Pagination count={10} defaultPage={5} showArrows={false} />;}Arrows Only
Hide page numbers when the UI needs compact previous/next controls.
import { Pagination } from "moduix";export function PaginationArrowsOnlyDemo() { return <Pagination count={10} defaultPage={5} showPages={false} />;}Controlled With Links
Control the page from React state and provide link URLs for navigation and SEO-friendly anchors.
Current page: 5
import { Pagination } from "moduix";import { useState } from "react";export function PaginationControlledLinksDemo() { const [page, setPage] = useState(5); return ( <Pagination count={10} page={page} onPageChange={setPage} getPageHref={(next) => `?page=${next}`} /> );}Variants
Use toolbar variants to match the surrounding surface.
import { Pagination } from "moduix";export function PaginationVariantsDemo() { return ( <> <Pagination count={10} defaultPage={5} toolbarVariant="default" /> <Pagination count={10} defaultPage={5} toolbarVariant="outline" /> <Pagination count={10} defaultPage={5} toolbarVariant="ghost" /> </> );}Sizes
Use size to fit compact and spacious interfaces.
import { Pagination } from "moduix";export function PaginationSizesDemo() { return ( <> <Pagination count={10} defaultPage={5} size="xs" /> <Pagination count={10} defaultPage={5} size="sm" /> <Pagination count={10} defaultPage={5} size="md" /> <Pagination count={10} defaultPage={5} size="lg" /> <Pagination count={10} defaultPage={5} size="xl" /> </> );}Class Name
Use className to theme active items and container spacing with scoped CSS variables.
import { Pagination } from "moduix";export function PaginationClassNameDemo() { return ( <Pagination count={10} defaultPage={5} toolbarVariant="outline" className={styles.customPagination} /> );}.customPagination { --pagination-toolbar-padding-filled: var(--spacing-1); --pagination-item-radius: var(--radius-sm); --pagination-item-bg-active: var(--color-primary); --pagination-item-color-active: var(--color-primary-foreground); --pagination-item-border-color-active: var(--color-primary);}