Capítulo 76 de 108

Pagination

Core Idea

Composable pagination UI (page links, prev/next, ellipsis) built from plain anchor-based components — no built-in page-state logic, you wire href/isActive/handlers yourself.

Key Concepts

  • Pagination: root <nav> wrapper.
  • PaginationContent: <ul> list wrapper for items.
  • PaginationItem: <li> wrapper.
  • PaginationLink: renders an <a> by default; accepts isActive to mark current page.
  • PaginationPrevious / PaginationNext: pre-built links with chevron icon + text (text prop overrides label, added for RTL/i18n support).
  • PaginationEllipsis: visual ... for truncated page ranges.

Code Examples

<Pagination>
  <PaginationContent>
    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
    <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
    <PaginationItem><PaginationLink href="#" isActive>2</PaginationLink></PaginationItem>
    <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
    <PaginationItem><PaginationEllipsis /></PaginationItem>
    <PaginationItem><PaginationNext href="#" /></PaginationItem>
  </PaginationContent>
</Pagination>
  • O que demonstra: Estrutura padrão com página ativa e reticências para range truncado.
<Pagination className="mx-0 w-auto">
  <PaginationContent>
    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
    <PaginationItem><PaginationNext href="#" /></PaginationItem>
  </PaginationContent>
</Pagination>
  • O que demonstra: Variante "icons only" (sem números de página), comum em data tables com seletor de linhas por página.

Composition

Pagination
└── PaginationContent
    ├── PaginationItem → PaginationPrevious
    ├── PaginationItem → PaginationLink
    ├── PaginationItem → PaginationEllipsis
    └── PaginationItem → PaginationNext

Anti-patterns

  • Usar <a href="#"> em app Next.js sem trocar por Link: substitua o tipo de PaginationLinkProps para React.ComponentProps<typeof Link> e troque <a> por <Link> dentro de pagination.tsx manualmente (o CLI ainda não faz isso automaticamente).

Key Takeaways

  1. Não há gestão de estado embutida: página ativa é controlada manualmente via isActive em cada PaginationLink.
  2. Para Next.js, edite components/ui/pagination.tsx trocando <a> por next/link's <Link>.
  3. text prop em PaginationPrevious/PaginationNext (mudança de changelog) permite localizar o rótulo "Previous"/"Next" para RTL/i18n.
  4. Variante "icons only" combina bem com Select de rows-per-page em tabelas.

Connects To

  • RTL: usa dir prop no Pagination e text customizado nos botões prev/next.
  • Select: par comum para "rows per page" ao lado da paginação.
AnteriorToggle GroupPróximoDirection