pagination
Pagination with page navigation, next and previous links.
Philosophy
Pagination is a navigation pattern, not a data-fetching pattern. We provide the visual components (page buttons, next/previous, ellipsis) and let you wire them to your data layer. This separation means the same pagination UI works whether you're paginating a client-side array, an API, or a database cursor. Under the hood, this component composes @gentleduck/primitives/pagination for semantic structure and direction-aware behavior.
Installation
npx @gentleduck/cli add pagination
npx @gentleduck/cli add pagination
Usage
import {
Pagination,
PaginationContent,
PaginationEllipsis,
PaginationItem,
PaginationLink,
PaginationNext,
PaginationPrevious,
} from "@/components/ui/pagination"import {
Pagination,
PaginationContent,
PaginationEllipsis,
PaginationItem,
PaginationLink,
PaginationNext,
PaginationPrevious,
} from "@/components/ui/pagination"<Pagination>
<PaginationContent>
<PaginationItem>
<PaginationPrevious href="#" />
</PaginationItem>
<PaginationItem>
<PaginationLink href="#">1</PaginationLink>
</PaginationItem>
<PaginationItem>
<PaginationEllipsis />
</PaginationItem>
<PaginationItem>
<PaginationNext href="#" />
</PaginationItem>
</PaginationContent>
</Pagination><Pagination>
<PaginationContent>
<PaginationItem>
<PaginationPrevious href="#" />
</PaginationItem>
<PaginationItem>
<PaginationLink href="#">1</PaginationLink>
</PaginationItem>
<PaginationItem>
<PaginationEllipsis />
</PaginationItem>
<PaginationItem>
<PaginationNext href="#" />
</PaginationItem>
</PaginationContent>
</Pagination>Next.js
By default the <PaginationLink /> component will render an <a /> tag.
To use the Next.js <Link /> component, make the following updates to pagination.tsx.
+ import Link from "next/link"
- type PaginationLinkProps = ... & React.ComponentPropsWithoutRef<"a">
+ type PaginationLinkProps = ... & React.ComponentProps<typeof Link>
const PaginationLink = ({...props }: ) => (
<PaginationItem>
- <a>
+ <Link>
// ...
- </a>
+ </Link>
</PaginationItem>
)
+ import Link from "next/link"
- type PaginationLinkProps = ... & React.ComponentPropsWithoutRef<"a">
+ type PaginationLinkProps = ... & React.ComponentProps<typeof Link>
const PaginationLink = ({...props }: ) => (
<PaginationItem>
- <a>
+ <Link>
// ...
- </a>
+ </Link>
</PaginationItem>
)
Note: We are making updates to the cli to automatically do this for you.
Component Composition
API Reference
Pagination
| Prop | Type | Default | Description |
|---|---|---|---|
dir | 'ltr' | 'rtl' | -- | Text direction override. Resolved via useDirection (dir prop -> DirectionProvider -> 'ltr'). |
className | string | -- | Additional CSS classes for the nav element |
...props | React.ComponentPropsWithoutRef<'nav'> | -- | Additional props to spread to the nav element |
PaginationContent
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | -- | Additional CSS classes for the ul element |
...props | React.ComponentPropsWithoutRef<'ul'> | -- | Additional props to spread to the ul element |
PaginationItem
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | -- | Additional CSS classes for the li element |
...props | React.ComponentPropsWithoutRef<'li'> | -- | Additional props to spread to the li element |
PaginationLink
| Prop | Type | Default | Description |
|---|---|---|---|
isActive | boolean | -- | Marks the link as active/current page (adds aria-current="page" and styles) |
size | 'icon' | 'default' | 'sm' | 'icon' | Size variant for the button style |
...props | React.ComponentPropsWithoutRef<'a'> | -- | Additional props to spread to the a element |
PaginationPrevious
Extends PaginationLink with aria-label="Go to previous page", left arrow icon, and text "Previous". Uses 'default' size.
| Prop | Type | Default | Description |
|---|---|---|---|
text | string | 'Previous' | Visible label text. Override for i18n / RTL support. |
className | string | -- | Additional CSS classes for the previous link |
...props | React.ComponentPropsWithoutRef<typeof PaginationLink> | -- | Additional props inherited from PaginationLink. |
PaginationNext
Extends PaginationLink with aria-label="Go to next page", text "Next", and right arrow icon. Uses 'default' size.
| Prop | Type | Default | Description |
|---|---|---|---|
text | string | 'Next' | Visible label text. Override for i18n / RTL support. |
className | string | -- | Additional CSS classes for the next link |
...props | React.ComponentPropsWithoutRef<typeof PaginationLink> | -- | Additional props inherited from PaginationLink. |
PaginationEllipsis
| Prop | Type | Default | Description |
|---|---|---|---|
text | string | 'More pages' | Screen-reader label text. Override for i18n / RTL support. |
className | string | -- | Additional CSS classes for the ellipsis element |
...props | React.ComponentPropsWithoutRef<'span'> | -- | Additional props to spread to the span element |
PaginationWrapper
| Prop | Type | Default | Description |
|---|---|---|---|
wrapper | React.ComponentPropsWithoutRef<typeof Pagination> | -- | Props for the pagination container |
content | React.ComponentPropsWithoutRef<typeof PaginationContent> | -- | Props for the content list |
item | React.ComponentPropsWithoutRef<typeof PaginationItem> | -- | Props for each pagination item |
right | React.ComponentPropsWithoutRef<typeof Button> | -- | Props for the "Next" button |
maxRight | React.ComponentPropsWithoutRef<typeof Button> | -- | Props for the "Last" button |
left | React.ComponentPropsWithoutRef<typeof Button> | -- | Props for the "Previous" button |
maxLeft | React.ComponentPropsWithoutRef<typeof Button> | -- | Props for the "First" button |
You can pass dir: 'rtl' through wrapper to make wrapper controls direction-aware:
<PaginationWrapper wrapper={{ dir: 'rtl' }} /><PaginationWrapper wrapper={{ dir: 'rtl' }} />RTL Support
Use the text prop on PaginationPrevious, PaginationNext, and PaginationEllipsis to provide translated labels. Set dir="rtl" on Pagination for a local override, or set DirectionProvider once at app/root level for global direction. Keep markup in logical order (Previous, pages, Next): visual mirroring is handled automatically.