Skip to content

Pagination

Get Ritla UI

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

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add pagination

    Also works with shadcn: npx shadcn@latest add @ritla/pagination

  2. Dependencies it brings

    @base-ui/react@phosphor-icons/react

  3. Or 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

pagination.tsx
import { Pagination } from "@/components/ui/pagination";<Pagination pageCount={20} page={page} onPageChange={setPage} />

Examples

Minimal

The arrows and where you are ("Page 1 of 20"), for narrow spaces.

EnglishMirroredArabic
LTR →

Load more

The count and a "Load more" button for feeds; the button shows its spinner and turns off on the last page.

EnglishMirroredArabic
LTR →

Slide dots

PaginationDots: dot or line, two sizes, on a blurred pill over images. With onCurrentChange each dot is a button.

EnglishMirroredArabic
LTR →

API reference

Pagination

PropTypeDefaultDescription
variant"numbers" | "minimal" | "load-more""numbers"Figma's Style (style is reserved in React).
pageCountnumberNoneHow many pages there are.
page / defaultPagenumber1The current page, from 1.
onPageChange(page: number) => voidNoneCalled with the chosen page.
hrefPatternstringNonePages as links, like "/orders?page={page}".
onLoadMore / loading() => void / booleanNoneFor the load-more style.
numerals"latn" | "arab"NoneNumeral system; defaults to RitlaProvider's.

PaginationDots

PropTypeDefaultDescription
count / currentnumberNoneHow many slides, and the current one (from 0).
onCurrentChange(index: number) => voidNoneMakes each dot a button that moves to its slide.
variant"dot" | "line""dot"Figma's Style.
size"md" | "lg""md"Figma's Size.
framedbooleanfalseFigma'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.

StyleUse
Page numbersDesktop tables and search results where people jump to a page or return to one.
MinimalNarrow spaces and phones: previous, next and “Page 1 of 20”.
Auto loadFeeds and activity lists read top to bottom; Load more adds the next page below.
Dot groupCarousels 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.

Do: RTL variantPage 1 is on the right and Next points left, toward the higher pages.
Don't: English pagination on an Arabic screenNext points right, back toward page 1 for an Arabic reader.

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.

KeyAction
TabThrough the arrows, the page numbers and the more-pages button.
EnterSpaceGoes to the page, or opens the menu of hidden pages.

ARIA

  • A nav named "Pagination" in the page language; the current page has aria-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 (0123456789 or ٠١٢٣٤٥٦٧٨٩).
Arabic typography
body-14 Medium.

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.

  • R012Untranslated attribute text (placeholder, alt, title, aria-label, button value)
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space
  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R061Arabic-Indic and Western digits mixed in the same context
  • R081flex row-reverse faking RTL instead of dir (tab order fights visual order)