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

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

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. 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 (1-indexada). Valores fora do intervalo serão ajustados.
Tipo	number
Valor padrão	1

currentPage

Atributo	current-page
Descrição	Página atual. Tem precedência sobre current.
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 Helpers.generateUniqueId(). > Uso compartilhado: mantenha esta descrição idêntica em todos os componentes que usam customId.
Tipo	string
Valor padrão	Helpers.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.
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 (aplicável na variante contextual).
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 (variante contextual).
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 (mínimo 1).
Tipo	number
Valor padrão	1

totalItems

Atributo	total-items
Descrição	Total de itens (aplicável na variante contextual).
Tipo	number
Valor padrão	---

totalPages

Atributo	total-pages
Descrição	Quantidade total de páginas. Tem precedência sobre total.
Tipo	number
Valor padrão	---

variant

Atributo	variant
Descrição	Variante de renderização do componente. - 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().

Dependências

Depende de

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

Gráfico