Pagination

Moves through the pages of a long list. Shows which items are on screen and the current page.

26–50 of 284

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function Preview() {
  const [page, setPage] = useState(2);

  return <Pagination aria-label="Runs pages" page={page} setPage={setPage} controls="simple" totalCount={284} />;
}

Installation

import { Pagination } from "@etched/reticle/pagination";

Examples

First page

1–25 of 284

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function FirstPage() {
  const [page, setPage] = useState(1);

  return <Pagination aria-label="Runs pages" page={page} setPage={setPage} totalCount={284} />;
}

Middle page

126–150 of 284

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function MiddlePage() {
  const [page, setPage] = useState(6);

  return <Pagination aria-label="Lots pages" page={page} setPage={setPage} totalCount={284} />;
}

Last page

276–284 of 284

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function LastPage() {
  const [page, setPage] = useState(12);

  return <Pagination aria-label="Benches pages" page={page} setPage={setPage} totalCount={284} />;
}

Single page

1–18 of 18

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function SinglePage() {
  const [page, setPage] = useState(1);

  return <Pagination aria-label="Sites pages" page={page} setPage={setPage} totalCount={18} />;
}

No results

0 results

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function NoResults() {
  const [page, setPage] = useState(1);

  return <Pagination aria-label="Alerts pages" page={page} setPage={setPage} totalCount={0} />;
}

Page size

When the page size changes, go back to page 1.

1–25 of 1,284

Per page

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function PageSize() {
  const [page, setPage] = useState(1);
  const [perPage, setPerPage] = useState(25);

  return (
    <Pagination
      aria-label="Chips pages"
      page={page}
      setPage={setPage}
      perPage={perPage}
      totalCount={1284}
      setPerPage={(size) => {
        setPerPage(size);
        setPage(1);
      }}
    />
  );
}

Simple controls

26–50 of 140

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function SimpleControls() {
  const [page, setPage] = useState(2);

  return <Pagination aria-label="Owners pages" page={page} setPage={setPage} controls="simple" totalCount={140} />;
}

Unknown total

When the API gives no total, set hasNextPage. The controls are then always simple.

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function UnknownTotal() {
  const [page, setPage] = useState(1);

  return <Pagination aria-label="Events pages" page={page} setPage={setPage} hasNextPage={page < 3} />;
}

Disabled while loading

51–75 of 284

import { useState } from "react";
import { Pagination } from "@etched/reticle/pagination";

export function DisabledWhileLoading() {
  const [page, setPage] = useState(3);

  return <Pagination aria-label="Probes pages" page={page} setPage={setPage} totalCount={284} disabled />;
}

API reference

Prop	Type	Default	Description
page *	number	–	The current page, from 1.
setPage *	(page: number) => void	–	Called with the page to show.
perPage	number	25	Items on each page.
totalCount	number	–	Items on all pages. When the API does not give a total, leave it out and set `hasNextPage`.
hasNextPage	boolean	false	Whether a next page exists. Used only without `totalCount`.
controls	"full" \| "simple"	"full"	Without `totalCount`, controls are always "simple".
setPerPage	(perPage: number) => void	–	Shows a page size select and is called with the new size. Usually also go back to page 1.
perPageOptions	readonly number[]	[25, 50, 100, 250]	Sizes in the page size select.
info	ReactNode	–	Replaces the "26–50 of 284" text. `null` hides it.
disabled	boolean	–	Disables every control, for example while a page loads.
aria-label	string	"Pagination"	Name of the navigation landmark. Give each one on a screen its own name.
className	string	–	Class on the root, for layout.