Pagination

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O componente br-pagination é o controle de navegação paginada do GovBR-DS, desenvolvido para segmentar grandes volumes de dados ou conteúdos extensos em páginas sequenciais numeradas.

Para que serve

• Segmentação de dados volumosos: Divide listas, tabelas e catálogos em blocos gerenciáveis de itens, reduzindo o tempo de carregamento da página e o consumo de memória.
• Navegação direta e sequencial: Oferece botões para avançar, retroceder, ir diretamente a uma página específica e navegar através de atalhos de reticências.
• Variante contextual completa: Permite alterar a quantidade de itens exibidos por página (ex.: 10, 20, 50, 100 itens) e pular diretamente para qualquer página através de campo de digitação integrado.

Quando utilizar

• Utilize quando:
  • O número total de itens for superior ao limite recomendado para visualização em uma única rolagem (geralmente mais de 20 a 50 registros).
  • Integrar com tabelas de dados (br-table) ou grades de cartões (br-card).
• Evite e prefira outro componente quando:
  • O conjunto completo de itens for pequeno (menos de 20 itens) e puder ser visualizado sem perda de performance.
  • A navegação representar etapas interdependentes de um processo sequencial com validação (prefira br-step ou br-wizard).

Estrutura e Slots

O br-pagination disponibiliza slots para complementar a navegação:

• pagination-info: Slot para customização do texto de contagem (ex.: "Exibindo 1-20 de 240 itens").
• loading: Slot para indicador visual exibido durante a troca assíncrona de páginas.

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplos

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Padrão

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Dados remotos

Use brPaginationPageChange e brPaginationPerPageChange para iniciar a consulta. Enquanto ela estiver pendente, defina loading; os controles ficam desabilitados, aria-busy="true" é aplicado e o slot loading pode substituir o indicador padrão.

Para confirmar a navegação somente depois da resposta, use controlled. Nesse modo, o evento contém a página solicitada, mas current permanece inalterado até a aplicação atribuir o novo valor:

pagination.addEventListener('brPaginationPageChange', async ({ detail }) => {
  pagination.loading = true;

try {
    const result = await pageService(detail.page);
    pagination.current = result.page;
  } finally {
    pagination.loading = false;
  }
});

Propriedades

ariaLabel

Atributo	aria-label
Descrição	Define o rótulo acessível usado por tecnologias assistivas. > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam ariaLabel. (obrigatório)
Tipo	string
Valor padrão	---

colorMode

Atributo	color-mode
Descrição	Define se a paginação usará um esquema de cores escuro. Valores inválidos são ignorados. Quando definido como dark, aplica a classe dark-mode ao container principal.
Tipo	"dark"
Valor padrão	---

controlled

Atributo	controlled
Descrição	Mantém current e perPage sob controle da aplicação. Quando ativo, interações apenas emitem a intenção de mudança. A aplicação deve atualizar a propriedade correspondente após concluir seu processamento.
Tipo	boolean
Valor padrão	false

current

Atributo	current
Descrição	Página atual (inteira e 1-indexada). Valores inválidos usam 1; valores fora do intervalo são ajustados.
Tipo	number
Valor padrão	1

currentPage

Atributo	current-page
Descrição	Página atual. Tem precedência sobre current; valores inválidos usam 1.
Tipo	number
Valor padrão	---

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId(). > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam customId.
Tipo	string
Valor padrão	generateUniqueId()

density

Atributo	density
Descrição	Define a densidade visual do componente. - small: Alta densidade (componente menor, mais compacto e com menos espaçamento). - medium: Densidade intermediária, padrão recomendado para a maioria dos casos. - large: Baixa densidade (componente maior, mais espaçamento e altura). > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam density. Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

ellipsisLabel

Atributo	ellipsis-label
Descrição	Rótulo acessível do botão de reticências que abre a lista de páginas ocultas.
Tipo	string
Valor padrão	'Abrir ou fechar a lista de paginação'

goToPageLabel

Atributo	go-to-page-label
Descrição	Rótulo do seletor "ir para página" (variante contextual).
Tipo	string
Valor padrão	'Página'

itemsText

Atributo	items-text
Descrição	Sufixo textual para a informação de quantidade de itens (variante contextual).
Tipo	string
Valor padrão	'itens'

loading

Atributo	loading
Descrição	Indica que a página solicitada ainda está sendo carregada pelo consumidor.
Tipo	boolean
Valor padrão	false

nextLabel

Atributo	next-label
Descrição	Rótulo acessível do botão de próxima página.
Tipo	string
Valor padrão	'Página seguinte'

perPage

Atributo	per-page
Descrição	Itens por página (inteiro positivo, aplicável na variante contextual). Valores inválidos usam 10.
Tipo	number
Valor padrão	10

perPageLabel

Atributo	per-page-label
Descrição	Rótulo do seletor de itens por página (variante contextual).
Tipo	string
Valor padrão	'Exibir'

perPageOptions

Atributo	---
Descrição	Opções disponíveis de itens por página na variante contextual. Passe o array por property binding; atributos HTML não representam arrays.
Exemplo de uso	const pagination = document.querySelector('br-pagination'); pagination.perPageOptions = [10, 25, 50, 100];
Tipo	number[]
Valor padrão	[10, 20, 30]

previousLabel

Atributo	previous-label
Descrição	Rótulo acessível do botão de página anterior.
Tipo	string
Valor padrão	'Voltar página'

total

Atributo	total
Descrição	Quantidade total de páginas (inteiro mínimo 1). Valores inválidos usam 1.
Tipo	number
Valor padrão	1

totalItems

Atributo	total-items
Descrição	Total de itens (inteiro não negativo, aplicável na variante contextual). Valores inválidos usam 0.
Tipo	number
Valor padrão	---

totalPages

Atributo	total-pages
Descrição	Quantidade total de páginas. Tem precedência sobre total; valores inválidos usam 1.
Tipo	number
Valor padrão	---

variant

Atributo	variant
Descrição	Variante de renderização do componente. Valores inválidos usam default. - default: paginação numérica (padrão) - contextual: paginação contextual com seletores e informação de itens
Tipo	"contextual" | "default"
Valor padrão	'default'

Slots

Nome	Descrição
"loading"	Indicador exibido enquanto uma página é carregada.
"pagination-info"	Informação customizada da paginação contextual. Quando utilizado, o texto padrão de contagem é substituído.

Eventos

Evento	Descrição	Depreciação	Propagação
brPaginationPageChange	Evento canônico para iniciar o carregamento de uma página. O detail contém { page }; o evento não é cancelável.	---	true
brPaginationPerPageChange	Evento canônico para iniciar o carregamento de uma nova quantidade de itens. O detail contém { perPage }; o evento não é cancelável.	---	true
pageChange	Solicita uma página por interação do usuário ou pelo método público. Em controlled, o evento informa a página solicitada, mas current só muda quando a aplicação confirma o resultado. O componente não faz chamadas remotas nem cancela a consulta do consumidor.	---	true
perPageChange	Solicita uma quantidade de itens por página (variante contextual). Em controlled, a aplicação confirma a mudança atribuindo perPage.	---	true

Métodos

goToPage

Descrição	Solicita navegação programática para uma página (1-indexada). Em controlled, aguarda a confirmação externa para alterar current.
Assinatura	goToPage(page: number) => Promise<void>
Parâmetros	page:

setPage

Descrição	Define programaticamente a página atual dentro do intervalo permitido.
Assinatura	setPage(page: number) => Promise<void>
Parâmetros	page: Página desejada (1-indexada).
Em controlled, emite a solicitação sem alterar current.

CSS Shadow Parts

Nome	Descrição
"ellipsis-button"	Parte encaminhada do botão de reticências.
"ellipsis"	Parte para o botão de reticências e seu contêiner.
"go-to-container"	Contêiner encaminhado do seletor de navegação direta.
"go-to-input"	Campo encaminhado do seletor de navegação direta.
"go-to-list"	Lista encaminhada do seletor de navegação direta.
"go-to"	Parte para o seletor de navegação direta na variante contextual.
"list"	Parte para a lista de páginas (elemento ul), usada para estilização via ::part().
"loading"	Área do indicador de carregamento.
"nav"	Parte para o contêiner raiz da paginação (elemento nav), usada para estilização via ::part().
"next-button-inner"	Botão interno encaminhado da próxima página.
"next-button"	Parte para o botão de próxima página, usada para estilização via ::part().
"page"	Parte para os itens de página numérica (elemento a), usada para estilização via ::part().
"per-page-container"	Contêiner encaminhado do seletor de itens por página.
"per-page-input"	Campo encaminhado do seletor de itens por página.
"per-page-list"	Lista encaminhada do seletor de itens por página.
"per-page"	Parte para o seletor de itens por página na variante contextual.
"prev-button-inner"	Botão interno encaminhado da página anterior.
"prev-button"	Parte para o botão de página anterior, usada para estilização via ::part().

Documentações relacionadas

Consulte o guia geral de dados remotos para escolher entre atualização otimista e controlada, iniciar consultas e coordenar loading com a resposta da aplicação.

Também são relacionados:

• Table, para paginar linhas carregadas remotamente;
• Select, quando a quantidade por página ou filtros usa um controle de seleção;
• Acessibilidade, para comunicar mudanças de estado durante o carregamento.

Dependências

Depende de

• br-item
• br-dropdown
• br-button
• br-icon
• br-list
• br-loading
• br-select
• br-select-option

Gráfico