Pagination
Pagination components for navigating paged content. Use Paginator for most scenarios or Pagination primitives for custom layouts.
Quick Start
Use Paginator to automatically generate pagination controls from a pagination state object.
1import { Paginator } from "@ecos/ui" 2 3<Paginator 4 paginationState={{ 5 page: 5, 6 totalPages: 9, 7 hasPreviousPage: true, 8 hasNextPage: true, 9 }} 10/>
URL-Driven Pagination
By default, the paginator generates links and preserves existing query parameters.
1<Paginator 2 paginationState={{ 3 page: 3, 4 totalPages: 10, 5 hasPreviousPage: true, 6 hasNextPage: true, 7 }} 8 searchParams={searchParams} 9/>
Client-Side Pagination
Provide an onPageChange callback to handle pagination entirely in client state.
1const [page, setPage] = useState(1); 2 3<Paginator 4 paginationState={{ 5 page, 6 totalPages: 20, 7 hasPreviousPage: page > 1, 8 hasNextPage: page < 20, 9 }} 10 onPageChange={setPage} 11/>
Automatic Ellipsis
The paginator automatically collapses large page ranges.
1<Paginator 2 paginationState={{ 3 page: 10, 4 totalPages: 50, 5 hasPreviousPage: true, 6 hasNextPage: true, 7 }} 8/>
Navigation Controls
Paginator automatically renders:
- First page
- Previous page
- Page numbers
- Ellipsis indicators
- Next page
- Last page
1<Paginator 2 paginationState={{ 3 page: 5, 4 totalPages: 20, 5 hasPreviousPage: true, 6 hasNextPage: true, 7 }} 8/>
Custom Styling
Apply additional classes using className.
1<Paginator 2 paginationState={{ 3 page: 5, 4 totalPages: 20, 5 hasPreviousPage: true, 6 hasNextPage: true, 7 }} 8 className="justify-end" 9/>
Advanced Usage
Use the lower-level Pagination primitives when you need complete control over layout and navigation behaviour.
1<Pagination> 2 <PaginationContent> 3 <PaginationItem> 4 <PaginationLink href="#">1</PaginationLink> 5 </PaginationItem> 6 7 <PaginationItem> 8 <PaginationLink href="#">2</PaginationLink> 9 </PaginationItem> 10 11 <PaginationItem> 12 <PaginationLink href="#">3</PaginationLink> 13 </PaginationItem> 14 </PaginationContent> 15</Pagination>
Large Page Sets
Use PaginationEllipsis to collapse large ranges when building custom pagination layouts.
1<Pagination> 2 <PaginationContent> 3 <PaginationItem> 4 <PaginationLink href="#">1</PaginationLink> 5 </PaginationItem> 6 7 <PaginationItem> 8 <PaginationEllipsis /> 9 </PaginationItem> 10 11 <PaginationItem> 12 <PaginationLink href="#">9</PaginationLink> 13 </PaginationItem> 14 15 <PaginationItem> 16 <PaginationLink href="#">10</PaginationLink> 17 </PaginationItem> 18 19 <PaginationItem> 20 <PaginationLink href="#">11</PaginationLink> 21 </PaginationItem> 22 23 <PaginationItem> 24 <PaginationEllipsis /> 25 </PaginationItem> 26 27 <PaginationItem> 28 <PaginationLink href="#">20</PaginationLink> 29 </PaginationItem> 30 </PaginationContent> 31</Pagination>
API Reference
Paginator
Property | Type | Default | Description |
|---|---|---|---|
| paginationState | PaginationState | - | Current pagination information used to generate navigation controls. |
| searchParams | Record<string, string | string[] | undefined> | - | Query parameters preserved when generating pagination links. |
| onPageChange | (page: number) => void | - | Enables client-side pagination. Controls render as buttons instead of links. |
| className | string | - | Additional classes applied to the paginator container. |
Pagination
Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional classes applied to the navigation container. |
| children | ReactNode | - | Pagination content rendered within the navigation element. |
PaginationContent
Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional classes applied to the list container. |
| children | ReactNode | - | Pagination items rendered within the component. |
PaginationItem
Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional classes applied to the list item. |
| children | ReactNode | - | Pagination content rendered within the item. |
PaginationLink
Property | Type | Default | Description |
|---|---|---|---|
| isActive | boolean | false | Marks the link as the currently active page. |
| size | "sm" | "default" | "lg" | "icon" | "icon" | Controls the size of the pagination link. |
| href | string | - | Destination URL for the page link. |
| children | ReactNode | - | Content displayed within the page link. |
PaginationPrevious
Property | Type | Default | Description |
|---|---|---|---|
| href | string | - | Destination URL for the previous page. |
PaginationNext
Property | Type | Default | Description |
|---|---|---|---|
| href | string | - | Destination URL for the next page. |
PaginationEllipsis
Property | Type | Default | Description |
|---|---|---|---|
| className | string | - | Additional classes applied to the ellipsis element. |
Visual Reference
Configuration | Preview |
|---|---|
| Default Paginator | |
| Client-side Pagination | |
| Custom Pagination |