Pagination

The Pagination component provides page navigation controls with previous/next buttons, numbered page links, and ellipsis for truncated ranges. It uses the buttonVariants from the Button component for consistent styling and supports active page highlighting.

Preview

Installation

npx novaui-cli add pagination

Dependencies

• lucide-react-native >= 0.300
• Requires the Button component (for buttonVariants)

Import

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
  PaginationEllipsis,
} from 'novaui-components'

Basic Usage

The Pagination is a compound component with these parts:

• Pagination - Root nav container with accessibility role
• PaginationContent - Horizontal list of pagination items
• PaginationItem - Wrapper for each page element
• PaginationLink - Numbered page button (supports isActive)
• PaginationPrevious - Previous page button with chevron icon
• PaginationNext - Next page button with chevron icon
• PaginationEllipsis - Dots indicating truncated page range

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
} from 'novaui-components'

export function BasicPagination() {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious onPress={() => {}} />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink isActive>1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink>2</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink>3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationNext onPress={() => {}} />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}

With Ellipsis

Show ellipsis when there are many pages:

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious onPress={() => {}} />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink>1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink isActive>3</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink>10</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext onPress={() => {}} />
    </PaginationItem>
  </PaginationContent>
</Pagination>

Controlled Pagination

Build a fully controlled pagination with state:

import { useState } from 'react'

export function ControlledPagination() {
  const [currentPage, setCurrentPage] = useState(1)
  const totalPages = 10

  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious
            onPress={() => setCurrentPage((p) => Math.max(1, p - 1))}
          />
        </PaginationItem>
        {[1, 2, 3].map((page) => (
          <PaginationItem key={page}>
            <PaginationLink
              isActive={currentPage === page}
              onPress={() => setCurrentPage(page)}
            >
              {page}
            </PaginationLink>
          </PaginationItem>
        ))}
        {currentPage < totalPages - 2 && (
          <PaginationItem>
            <PaginationEllipsis />
          </PaginationItem>
        )}
        <PaginationItem>
          <PaginationLink
            isActive={currentPage === totalPages}
            onPress={() => setCurrentPage(totalPages)}
          >
            {totalPages}
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationNext
            onPress={() => setCurrentPage((p) => Math.min(totalPages, p + 1))}
          />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}

Props API

Pagination Props

Extends React.ComponentPropsWithoutRef<typeof View>:

Root has role="navigation" and aria-label="pagination".

PaginationContent Props

Extends React.ComponentPropsWithoutRef<typeof View>:

PaginationItem Props

Extends React.ComponentPropsWithoutRef<typeof View>:

PaginationLink Props

Extends React.ComponentPropsWithoutRef<typeof Pressable> and Pick<ButtonProps, 'size'>:

Active links use variant="outline", inactive use variant="ghost".

PaginationPrevious Props

Extends PaginationLink props:

Renders a ChevronLeft icon with "Previous" label. Uses size="default".

PaginationNext Props

Extends PaginationLink props:

Renders "Next" label with a ChevronRight icon. Uses size="default".

PaginationEllipsis Props

Extends React.ComponentPropsWithoutRef<typeof View>:

Best Practices

1. Show context: Always indicate the active page with isActive so users know where they are

2. Truncate large ranges: Use PaginationEllipsis when there are more than 5-7 pages to keep the UI compact

3. Disable at bounds: Disable or hide PaginationPrevious on page 1 and PaginationNext on the last page

4. Pair with tables: Place pagination below Table components for paginated data sets

5. Consistent placement: Always position pagination at the bottom of the content it controls

Related Components

• Use below Table for paginated data
• Combine with Card for a contained data view
• Use Button variants for custom page navigation controls