Copiar página como Markdown para IA

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.

Exemplos

Básico

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

Recolher controles e código

Contextual

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

Expandir controles e código

Densidade

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

Expandir controles e código

Estado loading

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

Expandir controles e código

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

Gráfico

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;
  }
});

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.

Visão Geral​

Exemplos​

Básico​

Contextual​

Densidade​

Estado loading​

Propriedades​

ariaLabel​

colorMode​

controlled​

current​

currentPage​

customId​

density​

ellipsisLabel​

goToPageLabel​

itemsText​

loading​

nextLabel​

perPage​

perPageLabel​

perPageOptions​

previousLabel​

total​

totalItems​

totalPages​

variant​

Slots​

Eventos​

Métodos​

goToPage​

setPage​

CSS Shadow Parts​

Dependências​

Depende de​

Gráfico​

Dados remotos​

Visão Geral

Exemplos

Básico

Contextual

Densidade

Estado loading

Propriedades

ariaLabel

colorMode

controlled

current

currentPage

customId

density

ellipsisLabel

goToPageLabel

itemsText

loading

nextLabel

perPage

perPageLabel

perPageOptions

previousLabel

total

totalItems

totalPages

variant

Slots

Eventos

Métodos

goToPage

setPage

CSS Shadow Parts

Dependências

Depende de

Gráfico

Dados remotos