## Overview [#overview] The **Pagination** component provides navigation controls for browsing through large sets of data or content, with support for page links, previous/next buttons, ellipsis for truncated ranges, and active state indicators. ## Usage [#usage] ```tsx import { Pagination, PaginationRoot, PaginationContent, PaginationLink, } from "@tilt-legal/cubitt-components/primitives"; ``` ### Basic Pagination [#basic-pagination] ```tsx {/* Pagination items will be automatically rendered */} ``` ### URL State Management [#url-state-management] Using Cubitt's URL-state hooks, you can sync the pagination state with the URL, provide a `paramName`: ```tsx // Current page synced with ?page=3 {/* Pagination automatically handles URL sync */} // Advanced options: console.log('Page changed:', page)} maxVisiblePages={5} showFirstLast={true} showPrevNext={true} > {/* Enhanced pagination with all features */} ``` ## Examples [#examples] ### URL State [#url-state] ## Props [#props] ### PaginationRoot [#paginationroot] | Prop | Type | Description | | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------- | | `currentPage` | `number` | The current active page number. | | `totalPages` | `number` | The total number of pages. | | `onPageChange` | `(page: number) => void` | Event handler called when the page changes. | | `paramName` | `string` | URL parameter name for syncing state with URL. When provided, enables URL state management. | | `onUrlValueChange` | `(page: number) => void` | Callback when URL parameter value changes. | | `paramClearOnDefault` | `boolean` | Remove URL param when page equals 1. Defaults to `true`. | | `paramDebounce` | `number` | Debounce URL updates in milliseconds. | | `paramThrottle` | `number` | Throttle URL updates in milliseconds. | | `showPrevNext` | `boolean` | Whether to show previous/next buttons. Defaults to `true`. | | `showFirstLast` | `boolean` | Whether to show first/last page buttons. Defaults to `false`. | | `maxVisiblePages` | `number` | Maximum number of page buttons to show. Defaults to `5`. | | `className` | `string` | Additional CSS classes to apply. | ### Pagination [#pagination] | Prop | Type | Description | | ----------- | -------------------------------------- | -------------------------------- | | `className` | `string` | Additional CSS classes to apply. | | `...props` | `React.HTMLAttributes` | All other div element props. | ### PaginationContent [#paginationcontent] | Prop | Type | Description | | ----------- | ---------------------------------------- | -------------------------------- | | `className` | `string` | Additional CSS classes to apply. | | `...props` | `React.HTMLAttributes` | All other ul element props. | ### PaginationLink [#paginationlink] | Prop | Type | Description | | ----------- | ------------------------------------- | --------------------------------- | | `isActive` | `boolean` | Whether this page link is active. | | `size` | `"default" \| "sm" \| "lg" \| "icon"` | The size variant of the link. | | `className` | `string` | Additional CSS classes to apply. | | `...props` | `React.ComponentProps` | All other link component props. |