--- name: pagination-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Pagination for link-based paginated navigation with Zag.js pagination, getPageUrl, LinkButton, NextLink adapters, compact mode, variants, and sizes. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux framework-consumer-integration app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "https://zagjs.com/components/react/pagination" contributor_sources: "libs/ui/src/molecules/pagination.tsx libs/ui/src/tokens/components/molecules/_pagination.css libs/ui/stories/molecules/pagination.stories.tsx libs/ui/src/molecules/pagination.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Pagination Usage Canonical `sm` / `md` / `lg` sizes use the same control heights and interactive text scale as Button, Menu and Tabs, including compact page summaries. Use Pagination for page-based navigation. Do not use it for infinite scroll or stepper/wizard progress. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Pagination`. **Use it when** - Page-based navigation of results where position matters and users return to it (admin tables, search results). **Use something else when** | Need | Use instead | | --- | --- | | Steps of a task | Steps | | Browsing a small set | show everything | | Feed-like storefront browsing | a `Load more` Button with the count (`Show 24 more`) | **Do** - Show the range and total (`1–25 of 1,204`), formatted with the app locale. - Keep page size options few (25, 50, 100) and remember the choice. - Reflect the page in the URL so back/refresh keep the position. - Scroll to the top of the list (not the page) after changing pages. **Don't** - Reset filters when the page changes. - Show page numbers beyond what fits — use ellipsis. **Copy and states** - Controls `Previous page`, `Next page`, `Page 3`; current page marked with `aria-current`. **Behaviour (from the UX spec)** - The current page always matches the data shown; when a filter shrinks the range, move to an existing page instead of an empty one. - Never split one form or linear process into pages (use Steps). - Cross-page selection, if any, has its own scoped control outside Pagination. **Figma → code** | Figma | Code | | --- | --- | | `appearance=solid\|outline\|ghost`, `size=sm…lg` | `appearance="solid" | "outline" | "ghost"`, `size` | | — | `compact`, `siblingCount`, `boundaryCount`, `showPrevNext` (not in Figma) | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Pagination → UX guidelines*. ## Setup ```tsx import NextLink from "next/link" import { Pagination, createPaginationGetPageUrl } from "@techsio/ui-kit/molecules/pagination" ``` Supported props: ```text count: total items, pageSize, page/defaultPage getPageUrl: required link generator linkAs, linkProps for framework adapters appearance: solid | outline | ghost size: sm | md | lg compact, compactLabel, showPrevNext, siblingCount, boundaryCount onChange/onPageChange, translations ``` ## Core Patterns ### Always provide getPageUrl Pagination is link-based. Use `createPaginationGetPageUrl` to preserve query params and avoid ad hoc URL string handling. ### Use NextLink in Next apps Pass `linkAs={NextLink}`; do not wrap individual page links. ### Use compact for constrained surfaces Compact mode displays text instead of every page item. ## Common Mistakes ### HIGH Button-only pagination Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/molecules/pagination.tsx ### HIGH Missing getPageUrl Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/molecules/pagination.tsx ### HIGH Inline page button styling Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/tokens/components/molecules/_pagination.css ## Validation Commands ```sh rg -P -n "]*getPageUrl=)|]*className=.*(gap-|text-|bg-|border-|p-)" apps rg -P -n "]*linkAs=\\{?NextLink)" apps rg -n "createPaginationGetPageUrl|compactLabel|siblingCount|boundaryCount" apps ``` ## Unavailable destinations and small screens Unavailable previous/next destinations render a span with role=link, aria-disabled=true and tabindex=-1, without href. They are not buttons and cannot navigate or invoke the page callback. Navigable pages keep real href values. The sm/md/lg scale uses shared field heights, default md; the list may wrap on narrow surfaces. Prefer compact mode where horizontal space is very limited. Controlled page usage must update page in onPageChange; examples suppress browser navigation while updating local page state. ## Bounds and native link activation Zero results display no numbered pages (compact shows `0 of 0`); both directions are noninteractive placeholders without hrefs or tab stops. Count reductions clamp an uncontrolled page and notify callbacks once. A controlled invalid page requests a correction once per invalid-input/bounds pair and shows a pending status without destinations/current-page claims until the owner accepts it. Keep result data, page and URL aligned. An invalid uncontrolled page resets to 1 on pageSize changes. Modified, auxiliary or new-context link activation preserves native navigation without changing the original paginator; ordinary primary click/Enter activation changes it. RTL swaps only arrow glyphs, not arithmetic. Minimal selection has a persistent underline separate from keyboard focus.