Heimerle + Meule Logo
Heimerle + Meule

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

paginationStatePaginationState-Current pagination information used to generate navigation controls.
searchParamsRecord<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.
classNamestring-Additional classes applied to the paginator container.

Pagination

Property

Type

Default

Description

classNamestring-Additional classes applied to the navigation container.
childrenReactNode-Pagination content rendered within the navigation element.

PaginationContent

Property

Type

Default

Description

classNamestring-Additional classes applied to the list container.
childrenReactNode-Pagination items rendered within the component.

PaginationItem

Property

Type

Default

Description

classNamestring-Additional classes applied to the list item.
childrenReactNode-Pagination content rendered within the item.

PaginationLink

Property

Type

Default

Description

isActivebooleanfalseMarks the link as the currently active page.
size"sm" | "default" | "lg" | "icon""icon"Controls the size of the pagination link.
hrefstring-Destination URL for the page link.
childrenReactNode-Content displayed within the page link.

PaginationPrevious

Property

Type

Default

Description

hrefstring-Destination URL for the previous page.

PaginationNext

Property

Type

Default

Description

hrefstring-Destination URL for the next page.

PaginationEllipsis

Property

Type

Default

Description

classNamestring-Additional classes applied to the ellipsis element.

Visual Reference

Configuration

Preview

Default Paginator
Client-side Pagination
Custom Pagination