Pagination
Splits long lists and tables into pages, and marks the slide showing in carousels and onboarding.
Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned
Preview
Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.
Installation
Add the component
npx ritla add paginationAlso works with shadcn:
npx shadcn@latest add @ritla/paginationDependencies it brings
@base-ui/react@phosphor-icons/reactOr copy by hand
Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.
Usage
import { Pagination } from "@/components/ui/pagination";<Pagination pageCount={20} page={page} onPageChange={setPage} />Examples
Pages as links
hrefPattern makes every page a real link (?page={page}), so server pages paginate without client code.
Minimal
The arrows and where you are ("Page 1 of 20"), for narrow spaces.
Load more
The count and a "Load more" button for feeds; the button shows its spinner and turns off on the last page.
Slide dots
PaginationDots: dot or line, two sizes, on a blurred pill over images. With onCurrentChange each dot is a button.
API reference
Pagination
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "numbers" | "minimal" | "load-more" | "numbers" | Figma's Style (style is reserved in React). |
pageCount | number | None | How many pages there are. |
page / defaultPage | number | 1 | The current page, from 1. |
onPageChange | (page: number) => void | None | Called with the chosen page. |
hrefPattern | string | None | Pages as links, like "/orders?page={page}". |
onLoadMore / loading | () => void / boolean | None | For the load-more style. |
numerals | "latn" | "arab" | None | Numeral system; defaults to RitlaProvider's. |
PaginationDots
| Prop | Type | Default | Description |
|---|---|---|---|
count / current | number | None | How many slides, and the current one (from 0). |
onCurrentChange | (index: number) => void | None | Makes each dot a button that moves to its slide. |
variant | "dot" | "line" | "dot" | Figma's Style. |
size | "md" | "lg" | "md" | Figma's Size. |
framed | boolean | false | Figma's Framed: a blurred pill for use over images. |
Usage guidelines
Pagination splits a long list into pages and moves between them. Which style, how to show page numbers, where to put it and what to keep, carousels and dots, how it runs from the right in Arabic, and the checks before handoff.
1. Which style
Pick by the kind of list and the space around it. Page numbers let people jump; Minimal and Auto load save space; dots belong to carousels, not lists.
| Style | Use |
|---|---|
| Page numbers | Desktop tables and search results where people jump to a page or return to one. |
| Minimal | Narrow spaces and phones: previous, next and “Page 1 of 20”. |
| Auto load | Feeds and activity lists read top to bottom; Load more adds the next page below. |
| Dot group | Carousels and onboarding with 3 to 7 slides. |
Do
- Use Page numbers for tables people search through.
- Use Minimal on phones and in narrow panels.
- Use Auto load for feeds read in order.
Don't
- Paginate a list that fits on one screen.
- Mix pagination and infinite scroll on one list.
- Use dots for more than about seven items.
2. Page numbers
Keep the first and last pages reachable, show the pages around the current one, and collapse the rest into “…”, which opens a menu of hidden pages. The current page is clearly marked. Previous and Next sit at the ends and are disabled on the first and last page.
Do
- Show first, last and the pages around the current one.
- Collapse the rest behind “…”.
- Disable Previous on the first page and Next on the last.
- Show the result count nearby: Showing 21 to 40 of 348.
Don't
- Show every page number in a long list.
- Hide the last page, so people can't tell how long the list is.
- Remove Previous or Next instead of disabling them.
3. Placement and what to keep
Put pagination under the list, aligned with it, and keep the page in the URL so back and sharing work. When the page changes, move to the top of the list, not the top of the window. Keep filters and sorting when people change pages.
Do
- Place pagination below the list it controls.
- Keep the page number in the URL.
- Scroll to the top of the list on page change.
- Keep filters, sorting and page size across pages.
Don't
- Put pagination far from the list, in the page footer.
- Reset filters when people change pages.
- Leave people at the bottom of a new page.
4. Carousels and dots
Dots show how many slides there are and which one is showing. Pair them with previous and next arrows on desktop; on touch screens people also swipe. Don't autoplay, or give a visible pause control when you must.
Do
- Use dots for 3 to 7 slides, with arrows on desktop.
- Let people swipe on touch screens.
- Show a pause control if slides move on their own.
Don't
- Autoplay without a way to stop it.
- Use dots as the only way to reach content people need.
5. Arabic and RTL
The RTL variants run the page numbers from the right: page 1 is on the right and Next points left, toward the higher pages. Minimal writes “Page 1 of 20” in Arabic, with the numerals setting. Dots start on the right, and the first slide is the rightmost dot.
Next points toward the next page
Page numbers under an Arabic table.
Before handoff
- The style fits the list: Page numbers, Minimal, Auto load or dots.
- Disabled ends, the ellipsis and the result count are designed.
- Page, filters and sorting are kept in the URL.
- Arabic screens use RTL variants, with Next pointing left.
Accessibility
Keyboard
Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.
| Key | Action |
|---|---|
| Tab | Through the arrows, the page numbers and the more-pages button. |
| EnterSpace | Goes to the page, or opens the menu of hidden pages. |
ARIA
- A
navnamed "Pagination" in the page language; the current page hasaria-current="page". - The arrows are named "Previous page" and "Next page" and turn off at the ends.
- Decorative dots come with hidden text "Slide 1 of 3"; dots as buttons are named "Go to slide 2".
Do
- Put
aria-current="page"on the current page. - Name the arrows in the page language: Previous page and Next page.
- Name the “…” button More pages.
- 48 px touch targets on phones.
Don't
- Arrows alone, with no accessible name.
- Move focus to the top of the page when the list changes; move it to the list.
Arabic and RTL notes
Mirrors
- Page 1 sits on the right, and Next is on the left, pointing left.
- The first dot sits on the right.
Does not mirror
- The digits inside a number (18 stays 18).
- Numerals
- Page numbers and "Page 3 of 20" follow the numerals setting (
0123456789or٠١٢٣٤٥٦٧٨٩). - Arabic typography
body-14Medium.
Do
- The RTL variants: page 1 on the right, and Next pointing left.
- Page labels in Arabic, with the numerals setting.
- Carousel dots start on the right.
Don't
- Keep a right-pointing Next arrow on Arabic screens.
- Reverse the numbers by hand in the English variant.
Checks it passes
The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.
- Untranslated attribute text (placeholder, alt, title, aria-label, button value)
- Clipped text: content wider than its box with overflow hidden and no ellipsis
- Fixed-pixel-width container whose Arabic text exceeds the space
- Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
- letter-spacing applied to Arabic text (breaks the connected script)
- Arabic-Indic and Western digits mixed in the same context
- flex row-reverse faking RTL instead of dir (tab order fights visual order)