Pagination
Pagination with page navigation, next and previous links.
Installation
Install the following dependencies:
Set up the token layer and the StyleX compiler, if you have not already. See
Installation. Pagination also needs the
Button, which it imports buttonStyles from, and
interop.css, which sizes the chevrons and the ellipsis icon.
Copy and paste the following code into your project.
Update the import paths to match your project setup.
Usage
Composition
Simple
Page numbers only. Pass isActive to the current page.
Icons only
Use PaginationPrevious and PaginationNext without page numbers, next to a
rows-per-page control.
Pagination fills the width of its container and centres the links. Beside
another control, set width: "auto" through xstyle so the nav shrinks to
its content.
Link component
Pass a router link through render on PaginationLink. PaginationLink then
applies the button styles and the props to your component instead of an a.
Do not render a PaginationLink from Button. Base UI's Button puts
role="button" on the element it renders, which takes the link role away.
Middle click and open-in-new-tab stop working, and a screen reader announces a
button. PaginationLink is an a styled with buttonStyles for this reason.
API reference
Pass render to replace a part's element or compose it with another component.
Every part takes xstyle and className.
Pagination
The nav landmark. It renders aria-label="pagination"; pass your own when
a page has more than one.
PaginationLink
Renders an a and accepts its props. The current page takes the outline
button variant and aria-current="page"; every other page is ghost.
| Prop | Type | Default |
|---|---|---|
isActive | boolean | false |
size | "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | "icon" |
render | React.ReactElement | <a /> |
PaginationPrevious and PaginationNext
A PaginationLink with a chevron and a word. The word is hidden below 40rem,
and the aria-label reads "Go to previous page" or "Go to next page" whatever
text says.
| Prop | Type | Default |
|---|---|---|
text | string | "Previous" / "Next" |
size | "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | "default" |
PaginationEllipsis
Renders a span marked aria-hidden. It is the size of an icon link, so
the row keeps its rhythm.
paginationStyles
The style map behind the component. Spread it onto any element. A link's styles
are buttonStyles from the Button page.
| Key | Description |
|---|---|
nav | The landmark, full width, its links centred |
content | The list row and the gap between links |
ellipsis | The ellipsis box and its icon size |
text | The word beside a chevron, hidden below 40rem |
Data attributes
| Attribute | On | Effect |
|---|---|---|
data-slot="pagination" | the nav | Targets the landmark from a parent |
data-slot="pagination-content" | the list | Targets the row |
data-slot="pagination-item" | an item | Targets one list item |
data-slot="pagination-link" | a link | Present on whatever render produces |
data-active | the current link | Set when isActive is true |
data-variant, data-size | a link | outline or ghost, and the size prop |
data-slot="pagination-previous-text" | the word | The text inside PaginationPrevious |
data-slot="pagination-next-text" | the word | The text inside PaginationNext |
data-slot="pagination-ellipsis" | the ellipsis | Also aria-hidden |
A link, the previous and next controls and the ellipsis carry the
carbon-icons class and set --carbon-icon-size. interop.css reads both to
size the icon inside each.