componentes / pagination

Pagination

Navega entre páginas de resultados; o pai guarda a página e busca os dados.

Como usar

Um componente controlado: passe `page` (começando em 1), `pageCount` e `onPageChange`. Com muitas páginas mostra a primeira, a última, a atual e `siblingCount` vizinhas com reticências, mantendo a barra com a mesma largura. Todo texto embutido pode ser trocado (`previousLabel`, `nextLabel`, `pageLabel`, `aria-label`). Se cada página tem sua URL, prefira links reais.

preview

Pagination.tsx

import { Pagination } from "vaiperui";
 
const [page, setPage] = useState(1);
 
<Pagination
  page={page}
  pageCount={20}
  onPageChange={setPage}
  previousLabel="Página anterior"
  nextLabel="Próxima página"
  pageLabel={(n) => `Página ${n}`}
/>

Cores

preview

primary

success

warning

danger

cores.tsx

<Pagination page={page} pageCount={20} onPageChange={setPage} variantColor="primary" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} variantColor="success" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} variantColor="warning" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} variantColor="danger" />

Tamanhos

preview

tamanhos.tsx

<Pagination page={page} pageCount={20} onPageChange={setPage} size="sm" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} size="md" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} size="lg" />

Raio

preview

none

full

raio.tsx

<Pagination page={page} pageCount={20} onPageChange={setPage} radius="none" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} radius="sm" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} radius="md" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} radius="lg" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} radius="full" />

Cor personalizada

preview

Laranja

Violeta

cor-personalizada.tsx

<Pagination page={page} pageCount={20} onPageChange={setPage} customColor="#f97316" />
 
<Pagination page={page} pageCount={20} onPageChange={setPage} customColor="#8b5cf6" />

Vizinhas

preview

siblingCount={2}

vizinhas.tsx

<Pagination page={page} pageCount={30} siblingCount={2} onPageChange={setPage} />

Props

Prop	Valores	Padrão	Descrição
page	number	obrigatório	Página atual, começando em 1
pageCount	number	obrigatório	Número total de páginas
onPageChange	(page: number) => void	obrigatório	Chamado com a página escolhida
siblingCount	number	1	Páginas exibidas de cada lado da atual
previousLabel	string	Previous page	Nome acessível do botão anterior
nextLabel	string	Next page	Nome acessível do botão próximo
pageLabel	(page: number) => string	Page n	Nome acessível de um botão de página
aria-label	string	Pagination	Nome da navegação
disabled	boolean	false	Desabilita todos os botões
variantColor	primary \| success \| warning \| danger	primary	Cor de destaque do estado ativo e do anel de foco
customColor	string \| { light, dark }	nenhum	Qualquer cor CSS (ou um par por tema). Substitui o variantColor
size	sm \| md \| lg	md	Tamanho do controle e do texto
radius	none \| sm \| md \| lg \| full	md	Arredondamento dos cantos
animation	none \| smooth \| fast \| bounce	smooth	Transição entre estados

Acessibilidade

Renderiza um `<nav>` com `aria-label` (padrão "Pagination") contendo uma lista (`<ul>`/`<li>`) de botões nativos.
O botão da página atual tem `aria-current="page"` e não faz nada ao ser clicado.
Cada botão tem um `aria-label` vindo de `previousLabel`, `nextLabel` e `pageLabel(n)`; os ícones de seta são `aria-hidden`.
Anterior fica desabilitado na primeira página e próximo na última; `disabled` desabilita todos os botões.
As reticências "…" são `aria-hidden` e não focáveis.

Teclado

Tecla	Ação
Tab / Shift+Tab	Percorre os botões habilitados em ordem.
Enter / Space	Ativa o botão focado (comportamento nativo).

Tenha em mente

Traduza `previousLabel`, `nextLabel`, `pageLabel` e `aria-label`; os padrões estão em inglês.
Trocar de página não move o foco nem anuncia nada; trate isso em `onPageChange` se necessário.