[ [UI.21] Navigation ] Pagination

Pagination

> Navigation for paginated content with numbered pages and next/previous controls.

Import

[ [0x5B] IMPORT ]

1import {
2  Pagination,
3  PaginationContent,
4  PaginationItem,
5  PaginationLink,
6  PaginationNext,
7  PaginationPrevious,
8} from "@/components/ui/pagination"

Preview

[ [0x00] PAGINATION ]

1import {
2  Pagination,
3  PaginationContent,
4  PaginationItem,
5  PaginationLink,
6  PaginationNext,
7  PaginationPrevious,
8} from "@/components/ui/pagination";
9
10<Pagination>
11  <PaginationContent>
12    <PaginationItem>
13      <PaginationPrevious href="#" />
14    </PaginationItem>
15    <PaginationItem>
16      <PaginationLink href="#" isActive>1</PaginationLink>
17    </PaginationItem>
18    <PaginationItem>
19      <PaginationLink href="#">2</PaginationLink>
20    </PaginationItem>
21    <PaginationItem>
22      <PaginationLink href="#">3</PaginationLink>
23    </PaginationItem>
24    <PaginationItem>
25      <PaginationNext href="#" />
26    </PaginationItem>
27  </PaginationContent>
28</Pagination>

Variants

[ [0x00] WITH ELLIPSIS ]

1<Pagination>
2  <PaginationContent>
3    <PaginationItem>
4      <PaginationPrevious href="#" />
5    </PaginationItem>
6    <PaginationItem>
7      <PaginationLink href="#">1</PaginationLink>
8    </PaginationItem>
9    <PaginationItem>
10      <PaginationLink href="#" isActive>2</PaginationLink>
11    </PaginationItem>
12    <PaginationItem>
13      <PaginationLink href="#">3</PaginationLink>
14    </PaginationItem>
15    <PaginationItem>
16      <PaginationEllipsis />
17    </PaginationItem>
18    <PaginationItem>
19      <PaginationLink href="#">10</PaginationLink>
20    </PaginationItem>
21    <PaginationItem>
22      <PaginationNext href="#" />
23    </PaginationItem>
24  </PaginationContent>
25</Pagination>

[ [0x00] WITH FIRST AND LAST ]

1import { PaginationFirst, PaginationLast } from "@/components/ui/pagination";
2
3<Pagination>
4  <PaginationContent>
5    <PaginationItem>
6      <PaginationFirst href="#" />
7    </PaginationItem>
8    <PaginationItem>
9      <PaginationPrevious href="#" />
10    </PaginationItem>
11    <PaginationItem>
12      <PaginationLink href="#">1</PaginationLink>
13    </PaginationItem>
14    <PaginationItem>
15      <PaginationLink href="#" isActive>2</PaginationLink>
16    </PaginationItem>
17    <PaginationItem>
18      <PaginationLink href="#">3</PaginationLink>
19    </PaginationItem>
20    <PaginationItem>
21      <PaginationNext href="#" />
22    </PaginationItem>
23    <PaginationItem>
24      <PaginationLast href="#" />
25    </PaginationItem>
26  </PaginationContent>
27</Pagination>

[ [0x00] MINIMAL ]

1<Pagination>
2  <PaginationContent>
3    <PaginationItem>
4      <PaginationPrevious href="#" />
5    </PaginationItem>
6    <PaginationItem>
7      <span className="text-sm text-muted-foreground px-4">
8        Page 2 of 10
9      </span>
10    </PaginationItem>
11    <PaginationItem>
12      <PaginationNext href="#" />
13    </PaginationItem>
14  </PaginationContent>
15</Pagination>

[ [0x00] COMPACT (ICON ONLY) ]

1<Pagination>
2  <PaginationContent>
3    <PaginationItem>
4      <PaginationLink href="#" size="icon" aria-label="Page 1">
5        1
6      </PaginationLink>
7    </PaginationItem>
8    <PaginationItem>
9      <PaginationLink href="#" size="icon" isActive aria-label="Page 2, current page">
10        2
11      </PaginationLink>
12    </PaginationItem>
13    <PaginationItem>
14      <PaginationLink href="#" size="icon" aria-label="Page 3">
15        3
16      </PaginationLink>
17    </PaginationItem>
18    <PaginationItem>
19      <PaginationLink href="#" size="icon" aria-label="Page 4">
20        4
21      </PaginationLink>
22    </PaginationItem>
23    <PaginationItem>
24      <PaginationLink href="#" size="icon" aria-label="Page 5">
25        5
26      </PaginationLink>
27    </PaginationItem>
28  </PaginationContent>
29</Pagination>

API Reference

[ [0x00] API REFERENCE ]

Prop	Type	Default	Description
isActive	`boolean`	`false`	For PaginationLink - marks the current active page
size	`"default" \| "icon"`	`"icon"`	For PaginationLink - controls the button size
href	`string`	-	The URL to navigate to when the link is clicked

Accessibility

[ [0x58] A11Y ]

Uses semantic nav element with aria-label='pagination'
Active page is marked with aria-current='page'
Previous/Next buttons have descriptive aria-labels
First/Last buttons have descriptive aria-labels
Ellipsis is hidden from screen readers with aria-hidden
Keyboard navigable with Tab key

When to Use

[ [0xE9] USAGE GUIDANCE ]

✓ Use Pagination when:

• Large data sets with 50+ items (search results, product catalogs, user lists)
• User needs to browse through multiple pages of content systematically
• Table or grid with many rows that would cause excessive scrolling
• Performance benefits from loading data in chunks (API pagination)
• User needs to reference specific page numbers or bookmark pages

✗ Don't use when:

• Less than 50 items total (just show all or use "Load More" button)
• Infinite scroll is more appropriate (social media feeds, timelines)
• Real-time data that constantly updates (use live updating list instead)
• Single page of content (no pagination needed)
• User experience benefits from continuous scrolling over page breaks

Best Practices:

• Show total item count ("Showing 1-20 of 150 results")
• Previous/Next buttons always visible (disable when on first/last page)
• Use ellipsis (...) for long page ranges, showing 5-7 visible page numbers
• Consider mobile-friendly compact version (just Prev/Next + current page)
• Highlight current page clearly with isActive prop
• Preserve filters/search when navigating between pages (URL query params)
• Add First/Last buttons for very long lists (100+ pages)

Preview

[ [0x00] PAGINATION ]

1import {
2  Pagination,
3  PaginationContent,
4  PaginationItem,
5  PaginationLink,
6  PaginationNext,
7  PaginationPrevious,
8} from "@/components/ui/pagination";
9
10<Pagination>
11  <PaginationContent>
12    <PaginationItem>
13      <PaginationPrevious href="#" />
14    </PaginationItem>
15    <PaginationItem>
16      <PaginationLink href="#" isActive>1</PaginationLink>
17    </PaginationItem>
18    <PaginationItem>
19      <PaginationLink href="#">2</PaginationLink>
20    </PaginationItem>
21    <PaginationItem>
22      <PaginationLink href="#">3</PaginationLink>
23    </PaginationItem>
24    <PaginationItem>
25      <PaginationNext href="#" />
26    </PaginationItem>
27  </PaginationContent>
28</Pagination>

Variants

[ [0x00] WITH ELLIPSIS ]

1<Pagination>
2  <PaginationContent>
3    <PaginationItem>
4      <PaginationPrevious href="#" />
5    </PaginationItem>
6    <PaginationItem>
7      <PaginationLink href="#">1</PaginationLink>
8    </PaginationItem>
9    <PaginationItem>
10      <PaginationLink href="#" isActive>2</PaginationLink>
11    </PaginationItem>
12    <PaginationItem>
13      <PaginationLink href="#">3</PaginationLink>
14    </PaginationItem>
15    <PaginationItem>
16      <PaginationEllipsis />
17    </PaginationItem>
18    <PaginationItem>
19      <PaginationLink href="#">10</PaginationLink>
20    </PaginationItem>
21    <PaginationItem>
22      <PaginationNext href="#" />
23    </PaginationItem>
24  </PaginationContent>
25</Pagination>

[ [0x00] WITH FIRST AND LAST ]

1import { PaginationFirst, PaginationLast } from "@/components/ui/pagination";
2
3<Pagination>
4  <PaginationContent>
5    <PaginationItem>
6      <PaginationFirst href="#" />
7    </PaginationItem>
8    <PaginationItem>
9      <PaginationPrevious href="#" />
10    </PaginationItem>
11    <PaginationItem>
12      <PaginationLink href="#">1</PaginationLink>
13    </PaginationItem>
14    <PaginationItem>
15      <PaginationLink href="#" isActive>2</PaginationLink>
16    </PaginationItem>
17    <PaginationItem>
18      <PaginationLink href="#">3</PaginationLink>
19    </PaginationItem>
20    <PaginationItem>
21      <PaginationNext href="#" />
22    </PaginationItem>
23    <PaginationItem>
24      <PaginationLast href="#" />
25    </PaginationItem>
26  </PaginationContent>
27</Pagination>

[ [0x00] MINIMAL ]

1<Pagination>
2  <PaginationContent>
3    <PaginationItem>
4      <PaginationPrevious href="#" />
5    </PaginationItem>
6    <PaginationItem>
7      <span className="text-sm text-muted-foreground px-4">
8        Page 2 of 10
9      </span>
10    </PaginationItem>
11    <PaginationItem>
12      <PaginationNext href="#" />
13    </PaginationItem>
14  </PaginationContent>
15</Pagination>

[ [0x00] COMPACT (ICON ONLY) ]

1<Pagination>
2  <PaginationContent>
3    <PaginationItem>
4      <PaginationLink href="#" size="icon" aria-label="Page 1">
5        1
6      </PaginationLink>
7    </PaginationItem>
8    <PaginationItem>
9      <PaginationLink href="#" size="icon" isActive aria-label="Page 2, current page">
10        2
11      </PaginationLink>
12    </PaginationItem>
13    <PaginationItem>
14      <PaginationLink href="#" size="icon" aria-label="Page 3">
15        3
16      </PaginationLink>
17    </PaginationItem>
18    <PaginationItem>
19      <PaginationLink href="#" size="icon" aria-label="Page 4">
20        4
21      </PaginationLink>
22    </PaginationItem>
23    <PaginationItem>
24      <PaginationLink href="#" size="icon" aria-label="Page 5">
25        5
26      </PaginationLink>
27    </PaginationItem>
28  </PaginationContent>
29</Pagination>

Prop

Type

Default

Description

isActive

boolean

false

For PaginationLink - marks the current active page

size

"default" | "icon"

"icon"

For PaginationLink - controls the button size

href

string

The URL to navigate to when the link is clicked