Pagination

Moves through the pages of a list.

Source
$npx @dinachi/cli@latest add pagination
  • #4801Kenji Watanabe£42.00
  • #4800Priya Raman£83.95
  • #4799Olu Adeyemi£116.00
  • #4798Amara Diallo£153.00
variant
size
count
disabled

Usage

import { useState } from "react"
import { Pagination } from "@/components/ui/pagination"

export function Orders() {
  const [page, setPage] = useState(1)
  return <Pagination aria-label="Orders" count={25} page={page} onPageChange={setPage} />
}

Examples

  • #4791Lukas Berg£56.95
  • #4790Tomás Herrera£89.00
  • #4789Kenji Watanabe£126.00
  • #4788Priya Raman£167.95
  • #4787Olu Adeyemi£200.00
  • #4786Amara Diallo£57.00
31–36 of 150
Page numbers under a list, with the range beside them. Either gap opens a go-to-page field.
import { useState } from 'react';
import { Pagination } from '@/components/ui/pagination';

export function Example() {
  const [page, setPage] = useState(6);
  return (
    <div className="flex items-center justify-between">
      <span className="text-sm tabular-nums text-muted-foreground">
        {(page - 1) * 6 + 1}–{page * 6} of 150
      </span>
      <Pagination aria-label="Orders" count={25} page={page} onPageChange={setPage} />
    </div>
  );
}

Notes

A bar that holds still

Past seven pages the bar always has seven slots, each as wide as the widest page number, so the arrows stay under the pointer as you page. pageItems(page, count) returns those slots, with "gap" where pages are skipped, for a bar of your own.

Jumping

A gap opens a field for any page. Enter goes, Esc puts the gap back, and leaving the field goes too. Numbers past either end go to the first or last page.

Links

With getHref, pages are links, and opening one in a new tab leaves this page alone. A jump or an agent's change loads the page's URL. Call details.cancel() in onPageChange to route the change yourself; the browser then stays where it is.

Phone and desktop

Below 768px use variant="compact" and size="lg": one line, 44px targets, and the page number to tap for the jump field.

API

count
agent
number
How many pages there are.
page
agent
number
Controlled page, from 1.
defaultPagenumber = 1
Starting page when uncontrolled.
onPageChange
agent
(page, details) => void
Runs on every change, for people and agents. details.cancel() refuses it.
getHref(page: number) => string
Each page's URL. Pages and arrows then render as links.
variant"full" | "compact" = "full"
compact reads Page 6 of 25, with the number as the jump field.
size"default" | "lg" = "default"
lg makes every target 44px, for touch.
disabled
agent
boolean = false
Blocks people and agents.
aria-labelstring = "Pagination"
Names the nav. Say what it pages, such as Orders, when a screen has more than one.

Agent

Inside an AgentProvider, it appears in agent.snapshot() as number.

Reads

label

The aria-label, "Pagination" by default.

value

The current page.

min, max

1 and the page count.

Actions

setValue(12)

Goes to a page.

increment(1)

Goes forward a page, or as many as given.

decrement(1)

Goes back a page, or as many as given.

An agent's change runs through onPageChange like anyone's. isAgentChange(details) is true for it; details.cancel() refuses it. A page past either end is refused with the range, and a value or step that is not a whole number is refused too.

await agent.act({
  steps: [{ ref: "Orders", action: "setValue", args: [12] }],
})

Accessibility

  • A <nav> landmark, named "Pagination" unless you name it.
  • The current page has aria-current="page", and every page is named, such as Page 6.
  • The arrows are named Previous page and Next page, and are disabled at either end.
  • A jump returns focus to the new current page, and Esc to the gap it came from.
  • An arrow that disables at the first or last page hands focus to that page.