Pagination
Controle de navegação entre páginas de um dataset. Indica a posição atual e permite ir para páginas anterior, seguinte ou específicas.Navigation control for moving between pages of a dataset. Indicates the current position and lets users go to the previous, next, or a specific page.
Quando usarWhen to use
Use pagination quandoUse pagination when
Listas ou tabelas com muitos itens, resultados de busca paginados ou qualquer dataset onde o usuário precisa navegar entre subconjuntos discretos de conteúdo.Lists or tables with many items, paginated search results, or any dataset where users need to move between discrete content subsets.
Não use pagination quandoDon't use pagination when
A navegação é hierárquica (use Breadcrumb), alterna seções (use Tabs), segue um fluxo sequencial (use stepper) ou o dataset é pequeno demais para paginar.Navigation is hierarchical (use Breadcrumb), switches sections (use Tabs), follows a sequential flow (use a stepper), or the dataset is too small to paginate.
AnatomiaAnatomy
1
2
3 Prev/Next — Button Ghost Icon Only.Prev/Next — Ghost Icon Only Button.
4
5
6
<nav aria-label="Pagination"> — landmark de navegação.<nav aria-label="Pagination"> — navigation landmark.2
.ds-pagination__list — lista <ul> de controles..ds-pagination__list — <ul> list of controls.3 Prev/Next — Button Ghost Icon Only.Prev/Next — Ghost Icon Only Button.
4
.ds-pagination__page — link para página numerada..ds-pagination__page — link to a numbered page.5
.ds-pagination__page--current — página ativa com aria-current="page"..ds-pagination__page--current — active page with aria-current="page".6
.ds-pagination__ellipsis — indicador não interativo..ds-pagination__ellipsis — non-interactive indicator.
PadrãoDefault
10 páginas com ellipsis e página 5 ativa. Prev/Next sempre visíveis; desabilitados nos limites.10 pages with ellipsis and page 5 active. Prev/Next always visible; disabled at boundaries.
<nav class="ds-pagination" aria-label="Pagination">
<ul class="ds-pagination__list">...</ul>
</nav>TamanhosSizes
Small — primeira página
Prev desabilitado na página 1.Prev disabled on page 1.
<nav class="ds-pagination ds-pagination--sm">...</nav>Medium — padrão
<nav class="ds-pagination">...</nav>Large — última página
Next desabilitado na última página.Next disabled on the last page.
<nav class="ds-pagination ds-pagination--lg">...</nav>| Size | Height | Token |
|---|---|---|
Small (--sm) | 32px | component.pagination.item.height.sm |
| Medium (default) | 40px | component.pagination.item.height.md |
Large (--lg) | 48px | component.pagination.item.height.lg |
API no FigmaFigma API
O component set Pagination Item expõe Size e Page Number. O composto Pagination agrupa prev/next (Button Ghost Icon Only) e itens numerados.The Pagination Item component set exposes Size and Page Number. The Pagination composite groups prev/next (Button Ghost Icon Only) and numbered items.
| PropriedadeProperty | TipoType | Equivalente no repoRepo equivalent |
|---|---|---|
Size | VARIANT | ds-pagination--sm / --md / --lg |
Page Number | TEXT | .ds-pagination__page (link ou span com aria-current="page") |
Boas práticasBest practices
Faça
Mantenha Prev/Next sempre visíveis; desabilite nos limites em vez de ocultar.Keep Prev/Next always visible; disable at boundaries instead of hiding.
Não faça
Não liste todas as páginas quando há muitas — use ellipsis.Don't list every page when there are many — use ellipsis.
Diretrizes de conteúdoContent guidelines
| RegraRule | ExemploExample |
|---|---|
| Labels de página com númeroPage labels use numbers | aria-label="Page 5" — not "Fifth page" |
| Prev/Next descritivos em icon-onlyDescriptive Prev/Next for icon-only | aria-label="Previous page" / "Next page" |
| Ellipsis não interativoEllipsis is non-interactive | aria-hidden="true" no ellipsis — não use link |
Mapeamento de tokensToken mapping
| PropriedadeProperty | Token | Variável CSSCSS variable |
|---|---|---|
| gap | component.pagination.gap.default | --ds-pagination-gap-default |
| item height | component.pagination.item.height.{sm|md|lg} | --ds-pagination-item-height-* |
| item min-width | component.pagination.item.min-width.* | --ds-pagination-item-min-width-* |
| item radius | component.pagination.item.radius.default | --ds-pagination-item-radius-default |
| item bg default/hover/current/disabled | component.pagination.item.bg.* | --ds-pagination-item-bg-* |
| item content color | component.pagination.item.content.color.* | --ds-pagination-item-content-color-* |
| item typography | component.pagination.item.font-* / line-height.* | --ds-pagination-item-* |
| ellipsis icon | component.pagination.icon.* | --ds-pagination-icon-* |
| focus ring | component.pagination.focus-ring.radius.default + component.focus-ring.* | --ds-pagination-focus-ring-radius-default, --ds-focus-ring-* |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-pagination | Container (<nav>); size md por padrãoContainer (<nav>); md size by default |
ds-pagination--sm / --lg | Escala 32px / 48px32px / 48px scale |
ds-pagination__list | Lista <ul> de itens<ul> list of items |
ds-pagination__page | Link ou texto de página numeradaNumbered page link or text |
ds-pagination__page--current | Página ativa (brand fill, bold)Active page (brand fill, bold) |
ds-pagination__ellipsis | Ellipsis não interativoNon-interactive ellipsis |
Interação por tecladoKeyboard interaction
| TeclaKey | AçãoAction |
|---|---|
Tab | Move o foco entre Prev, links de página e NextMoves focus between Prev, page links, and Next |
Enter / Space | Ativa o controle focadoActivates the focused control |
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 1.3.1 Info and Relationships (A) | <nav aria-label="Pagination"> + lista <ul>/<li> | ✓ |
| 2.4.4 Link Purpose (A) | aria-label descritivo em cada página e em Prev/Next icon-only | ✓ |
| 4.1.2 Name, Role, Value (A) | aria-current="page" na página ativa; disabled nos limites | ✓ |