Pagination

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

import {
  Pagination,
  PaginationRoot,
  PaginationContent,
  PaginationLink,
} from "@tilt-legal/cubitt-components/primitives";

Basic Pagination

<PaginationRoot currentPage={1} totalPages={10}>
  {/* Pagination items will be automatically rendered */}
</PaginationRoot>

URL State Management

Using Cubitt's URL-state hooks, you can sync the pagination state with the URL, provide a paramName:

// Current page synced with ?page=3
<PaginationRoot
  currentPage={1}
  totalPages={20}
  paramName="page"
>
  {/* Pagination automatically handles URL sync */}
</PaginationRoot>

// Advanced options:
<PaginationRoot
  currentPage={1}
  totalPages={50}
  paramName="p"
  paramClearOnDefault={true}    // Remove param when page equals 1
  paramDebounce={200}           // Debounce URL updates
  onUrlValueChange={(page) => console.log('Page changed:', page)}
  maxVisiblePages={5}
  showFirstLast={true}
  showPrevNext={true}
>
  {/* Enhanced pagination with all features */}
</PaginationRoot>

Examples

URL State

Props

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

Prop	Type	Description
`className`	`string`	Additional CSS classes to apply.
`...props`	`React.HTMLAttributes<HTMLDivElement>`	All other div element props.

PaginationContent

Prop	Type	Description
`className`	`string`	Additional CSS classes to apply.
`...props`	`React.HTMLAttributes<HTMLUListElement>`	All other ul element props.

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<typeof Link>`	All other link component props.

Pagination

On this page