## Overview [#overview] `Pagination` provides composable pagination primitives plus `PaginationRoot`, a managed pagination renderer with controlled and URL-state modes. Generated `PaginationRoot` controls render as real buttons. If you provide `href` to an individual `PaginationLink`, that link renders as an anchor while keeping Cubitt button styling. ## Usage [#usage] ```tsx import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, PaginationRoot, } from "@tilt-legal/cubitt-components/pagination"; ``` ```tsx setPage(page)} totalPages={20} /> ``` ```tsx 2 ``` ## Examples [#examples] ### Basic [#basic] ```tsx import { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious, } from "@tilt-legal/cubitt-components/pagination"; 1 2 3 ; ``` ### URL State [#url-state] ```tsx import { PaginationRoot } from "@tilt-legal/cubitt-components/pagination"; ; ``` ## API Reference [#api-reference] ### PaginationRoot [#paginationroot] | Prop | Type | Default | Description | | --------------------- | -------------------------------- | ---------------- | -------------------------------------------------------------------------- | | `currentPage` | `number` | URL value or `1` | Controlled active page. | | `totalPages` | `number` | – | Total number of pages. | | `onPageChange` | `(page: number) => void` | – | Called when a generated page control is clicked. | | `showPrevNext` | `boolean` | `true` | Show previous and next controls. | | `showFirstLast` | `boolean` | `true` | Show first and last page controls when they are outside the visible range. | | `maxVisiblePages` | `number` | `5` | Maximum number of page number controls in the main range. | | `paramName` | `string` | – | URL search parameter name for URL-state mode. | | `paramValue` | `number` | – | External URL-state value override. | | `onUrlValueChange` | `(page: number \| null) => void` | – | Called when URL state changes. | | `paramClearOnDefault` | `boolean` | – | Remove the URL param when page equals the default value. | | `paramDebounce` | `number` | – | Debounce URL updates in milliseconds. | | `paramThrottle` | `number` | – | Throttle URL updates in milliseconds. | | `className` | `string` | – | Additional classes for the pagination root. | ### Pagination [#pagination] | Prop | Type | Default | Description | | ----------- | -------- | ------- | --------------------------------- | | `className` | `string` | – | Additional classes for the `nav`. | ### PaginationContent [#paginationcontent] | Prop | Type | Default | Description | | ----------- | -------- | ------- | -------------------------------- | | `className` | `string` | – | Additional classes for the list. | ### PaginationLink [#paginationlink] Uses Button styling internally. Active links use the `secondary` button variant; inactive links use `ghost`. | Prop | Type | Default | Description | | ----------- | ---------------------- | -------- | ---------------------------------------------- | | `isActive` | `boolean` | `false` | Marks the link as the current page. | | `href` | `string` | – | When provided, renders as an anchor. | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Button size. | | `mode` | `"icon" \| "input"` | `"icon"` | Button mode. | | `disabled` | `boolean` | `false` | Disable the control when rendered as a button. | | `className` | `string` | – | Additional classes for the control. | ### PaginationPrevious / PaginationNext [#paginationprevious--paginationnext] Convenience wrappers around `PaginationLink` with directional icons and accessible labels. | Prop | Type | Default | Description | | ----------- | --------- | ------- | ------------------------------------- | | `href` | `string` | – | When provided, renders as an anchor. | | `disabled` | `boolean` | `false` | Disable the generated button control. | | `className` | `string` | – | Additional classes for the control. | ### PaginationEllipsis [#paginationellipsis] | Prop | Type | Default | Description | | ----------- | -------- | ------- | ----------------------------------------- | | `className` | `string` | – | Additional classes for the ellipsis item. |