Navigation/Pagination

Pagination

Pagination with page navigation, next and previous links.

Themed

When to Use

Use Pagination when you need to:

  • Split large datasets across multiple pages (tables, lists, search results)
  • Allow users to navigate sequentially or jump to specific pages
  • Show the user their current position within a large collection
  • Reduce initial page load time by loading content incrementally
  • Provide a predictable URL structure for bookmarkable pages

When Not to Use

  • Infinite scroll or lazy-loading content -- use a "Load More" pattern instead
  • Navigating between steps in a wizard -- use Tabs or a stepper
  • Switching between views or content sections -- use Tabs
  • Navigating a site hierarchy -- use Breadcrumb

Default

Pagination with numbered pages, ellipsis, and previous/next navigation.

Simple

Basic pagination without ellipsis, suitable for small page counts.

With Ellipsis

Pagination with ellipsis indicators for large page ranges, showing a window around the active page.

Compact

Minimal pagination with just previous/next controls and a page indicator. Ideal for mobile or constrained layouts.

UX & Design Guidelines

Page Window Strategy

For large page counts, show a window of 3-5 pages around the current page with ellipsis to indicate truncated ranges. Always display the first and last page for orientation. For fewer than 7 total pages, show all page numbers without ellipsis.

Spacing & Layout

The component uses gap-1 between items by default. Place pagination centered below its associated content with mt-4 or mt-6 spacing. In tables, position pagination in the table footer or directly below the table body.

Responsive Behavior

On small screens, Previous/Next labels collapse to icon-only (the text is hidden with hidden sm:block). Consider switching to the compact variant on mobile to save horizontal space. For very narrow containers, a simple "Page X of Y" indicator with arrow buttons may be the best approach.

Color & Contrast

The active page uses variant="outline" with border-input to distinguish it from inactive pages that use variant="ghost". Both states meet WCAG 2.1 AA contrast requirements. Hover states use bg-accent for clear interactive feedback.

Accessibility

Keyboard Navigation

  • Tab -- Move focus between pagination links
  • Shift + Tab -- Move focus backward through pagination links
  • Enter -- Activate the focused page link

Semantic Structure

  • Renders a <nav> element with role="navigation" and aria-label="pagination"
  • Page links are contained in a semantic <ul> / <li> structure
  • The ellipsis element is aria-hidden with a sr-only span reading "More pages"

Screen Reader Support

  • Active page is indicated with aria-current="page"
  • Previous link has built-in aria-label="Go to previous page"
  • Next link has built-in aria-label="Go to next page"
  • Page numbers announce their numeric content naturally

Touch Targets

Page links use size="icon" (36x36px) by default, meeting minimum touch target recommendations. Previous/Next links use size="default" with additional padding for a wider hit area.

ARIA Attributes

{/* Pagination nav with accessible label */}
<Pagination>
  {/* nav role="navigation" aria-label="pagination" is built-in */}
  <PaginationContent>
    <PaginationItem>
      {/* aria-label="Go to previous page" is built-in */}
      <PaginationPrevious href="/page/1" />
    </PaginationItem>
    <PaginationItem>
      {/* isActive adds aria-current="page" */}
      <PaginationLink href="/page/2" isActive>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      {/* Ellipsis is aria-hidden with sr-only "More pages" */}
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      {/* aria-label="Go to next page" is built-in */}
      <PaginationNext href="/page/3" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

Related Components

Breadcrumb

Displays the path to the current resource using a hierarchy of links.

Table

A responsive table component commonly paired with pagination for large datasets.

Data Table

Powerful table with built-in sorting, filtering, and pagination controls.

Tabs

Layered sections of content displayed one at a time, for view-based navigation.

API Reference

The Pagination component is composed of several sub-components. Each accepts standard HTML attributes in addition to the props listed below.

Pagination

Root nav container with role="navigation" and aria-label="pagination".

PropTypeDefaultDescription
classNamestring—Additional CSS classes for the root nav element.

PaginationContent

Flex container (<ul>) for pagination items.

PropTypeDefaultDescription
classNamestring—Additional CSS classes for the list container.

PaginationLink

Individual page number link rendered as an anchor element.

PropTypeDefaultDescription
hrefstring—The URL to navigate to when clicked.
isActivebooleanfalseWhether this is the currently active page. Applies outline variant and aria-current="page".
size"default" | "icon""icon"Size variant for the link. Defaults to icon for square page numbers.
classNamestring—Additional CSS classes.

PaginationPrevious / PaginationNext

Navigation links with built-in chevron icons and accessible labels.

PropTypeDefaultDescription
hrefstring—The URL to navigate to.
classNamestring—Additional CSS classes.

PaginationEllipsis

More-pages indicator. Renders aria-hidden with sr-only fallback text.

PropTypeDefaultDescription
classNamestring—Additional CSS classes for the ellipsis span.