# Pagination Navigate pages with buttons, links, or your router. ```tsx title="basic.tsx" import { Pagination, PaginationEllipsis, PaginationItem, PaginationLink, PaginationList, PaginationNext, PaginationPrevious, } from "@ui-sdk/solid/pagination" import { For } from "solid-js" import { useLog } from "./log" function Example() { const log = useLog() return ( log(`Page ${page} (${details.reason})`)} > {({ items }) => ( <> Previous {(item) => ( {typeof item === "number" ? ( ) : ( )} )} Next )} ) } export { Example } ``` Choose a page, or use Previous and Next. The console logs each page and its reason, and the step at either end stays focusable as a button. ## Installation ```bash npm install @ui-sdk/solid @ui-sdk/core ``` ## Composition Use the following composition to build a `Pagination`: ```text Pagination └── PaginationList ├── PaginationItem │ └── PaginationPrevious ├── PaginationItem │ └── PaginationLink ├── PaginationItem │ └── PaginationEllipsis ├── PaginationItem │ └── PaginationLink └── PaginationItem └── PaginationNext ``` Name the navigation with `aria-label`, then put the page links and steps in a list. `items` contains page numbers and the strings `"ellipsis-start"` and `"ellipsis-end"`. Render a link for each number and an ellipsis for each gap. Key entries by the item itself so a page link keeps its element as the range moves. `PaginationLink` shows its page number unless you supply children. The current link gets `aria-current="page"` and `data-current`. `PaginationEllipsis` shows “…” and is hidden from screen readers. Give Previous, Next, First, and Last text or an `aria-label`. At an end, a step gets `aria-disabled="true"` and `data-disabled` and stops changing the page. As a button, it stays in the tab order. ## Usage Import the parts and put them together: ```tsx import { Pagination, PaginationEllipsis, PaginationItem, PaginationLink, PaginationList, PaginationNext, PaginationPrevious, } from "@ui-sdk/solid/pagination" import { For } from "solid-js" function PageNavigation() { return ( {({ items }) => ( <> Previous {(item) => ( {typeof item === "number" ? ( ) : ( )} )} Next )} ) } export { PageNavigation } ``` ## Total and Page Size Instead of `pageCount`, pass `total`, how many items there are, and `pageSize`, how many fit on a page (10 by default). Pagination calculates the page count, with a minimum of one. This example resets to page 1 when the page size changes. A page past the end, like after the count shrinks, reads as the last page. ```tsx title="total.tsx" import { Pagination, PaginationEllipsis, PaginationItem, PaginationLink, PaginationList, PaginationNext, PaginationPrevious, } from "@ui-sdk/solid/pagination" import { createSignal, For } from "solid-js" import { useLog } from "./log" function Example() { const log = useLog() const [page, setPage] = createSignal(2) const [pageSize, setPageSize] = createSignal(20) const total = 95 return (

Showing {(page() - 1) * pageSize() + 1}– {Math.min(page() * pageSize(), total)} of {total}

{ setPage(next) log(`Page ${next}`) }} > {({ items }) => ( <> Previous {(item) => ( {typeof item === "number" ? ( ) : ( )} )} Next )}
) } export { Example } ``` Choose a page, then change Rows per page. The console logs each change, and a new size starts again at page 1. ## Simple With only a few pages, the range has no gaps, so you can write the links out and leave the steps off. ```tsx {(page) => ( )} ``` ## Links Pass `getHref` to map each page to a URL. Page links and steps then render as anchors. ```tsx `/posts?page=${page}`} > ... ``` Server-rendered anchors work before JavaScript loads. A normal click changes the page and follows the URL. Modifier clicks and middle clicks leave pagination state alone so the browser can open the link elsewhere. A step at its end loses its `href` and leaves the tab order, but keeps focus if it already had it. During navigation, its original `href` stays in place so Next cannot accidentally follow the next page's URL. ## Router Links Render your router's link to page on the client. Pass it to `render`, like `render={(props) => }`; it receives the part's props, with the `href` from [`getHref`](#links). The pagination's click handler runs first: when a change is canceled or a step is at its end, it calls `preventDefault()`, and the router leaves the link alone. Read the page from the URL, like your router's search params, so the route [controls](#controlled) the pagination. ```tsx const [searchParams] = useSearchParams() const page = () => Number(searchParams.page ?? 1) `?page=${page}`}> {({ items }) => ( {(item) => ( {typeof item === "number" ? ( } /> ) : ( )} )} )} ``` ## Controlled Pass `page` and `onPageChange` to control the pagination. ```tsx const [page, setPage] = createSignal(1) setPage(next)}> ... ``` Every change carries a [reason](#reasons): `item-press` for a page, `previous-press`, `next-press`, `first-press` or `last-press` for a step, and `imperative` from a [controller](#controller). Call `details.cancel()` to keep the page, like while a form has unsaved changes. A canceled change also stops a link from navigating. ## Default Page `defaultPage` is the page it starts on, when uncontrolled. It's 1 by default. ```tsx ... ``` ## Siblings `siblings` is how many pages show on each side of the current one, 1 by default. Near an end, the window slides over instead of shrinking, keeping the range length stable. A gap of one page shows that page instead of an ellipsis. ```tsx ... ``` ## Boundaries `boundaries` is how many pages always show at each end, 1 by default. ```tsx ... ``` ## Paging from Anywhere A [controller](#controller), from `createPaginationController()`, pages the pagination from anywhere, like buttons elsewhere on the page or a keyboard shortcut, without controlling it. Pass it as `controller`. ```tsx const pagination = createPaginationController() ... ``` ## Your Own Markup `paginationRange({ page, pageCount, siblings, boundaries })` is the range the parts use, as a pure function. It runs anywhere, like on the server, in an email or for a UI that isn't a list of pages. Import it from `@ui-sdk/core/pagination`. Here it keeps a strip of slide dots the same length however many slides there are. ```tsx import { paginationRange } from "@ui-sdk/core/pagination" const items = () => paginationRange({ page: slide(), pageCount: 20, siblings: 2, boundaries: 1 })
{(item) => typeof item === "number" ? (
``` ## Custom Rendering Every part takes `render`, a function that receives the props to spread and the part's state. `class`, `style` and `children` can be functions of the same state: whether a link is `current`, and for a step, the `page` it goes to and whether it's `disabled`. ```tsx title="render.tsx" import { Pagination, PaginationEllipsis, PaginationItem, PaginationLink, PaginationList, PaginationNext, PaginationPrevious, } from "@ui-sdk/solid/pagination" import { For } from "solid-js" function Example() { return ( {({ items }) => ( <> (