Loading

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-loading é o indicador de carregamento e progresso do GovBR-DS, utilizado para informar visualmente e de forma acessível que uma operação assíncrona está em execução no sistema.

Para que serve

• Feedback de processamento: Alerta a pessoa usuária de que uma requisição, cálculo ou carregamento de dados está ocorrendo, evitando múltiplos cliques acidentais.
• Modo spinner (indeterminado): Indicador circular contínuo para operações de duração imprevisível.
• Modo progress (determinado): Indicador com percentual explícito (0 a 100%) para downloads, uploads ou tarefas com progresso mensurável, suportando ação de cancelamento.
• Acessibilidade para tecnologias assistivas: Comunica o estado de carregamento através de regiões acessíveis (aria-live="polite" e papéis progressbar ou status).

Quando utilizar

• Utilize quando:
  • Uma operação assíncrona demorar mais de 300 a 500 milissegundos para responder.
  • Durante o envio de formulários volumosos, processamento de arquivos ou transição de telas pesadas.
• Evite e prefira outro componente quando:
  • A resposta for quase instantânea (menos de 300ms), para evitar piscamento rápido de tela que cause desconforto visual.
  • A espera ocorrer dentro de um botão durante o clique (use a prop loading do próprio br-button).

Estrutura e Slots

O br-loading oferece slots para personalização:

• label: Slot para rótulo ou mensagem descritiva do carregamento (substitui a prop label).
• cancel-button: Slot para botão customizado de cancelamento no modo progress.

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

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

PadrãoProgresso

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

Propriedades

cancelLabel

Atributo	cancel-label
Descrição	Define o texto do botão de cancelamento. No modo spinner, esta prop não tem efeito.
Tipo	string
Valor padrão	'Cancelar'

cancelable

Atributo	cancelable
Descrição	Define se o botão de cancelamento será exibido. Ao pressionar o botão, o evento brLoadingCancel é emitido. No modo spinner, esta prop não tem efeito.
Tipo	boolean
Valor padrão	false

compact

Atributo	compact
Descrição	Remove o espaçamento externo e oculta visualmente o rótulo, mantendo-o disponível para tecnologias assistivas. Use em áreas compactas, como controles de paginação ou campos de formulário.
Tipo	boolean
Valor padrão	false

completion

Atributo	completion
Descrição	Define o comportamento quando o progresso atinge 100. Valores inválidos usam persist. No modo spinner, esta prop não tem efeito.
Tipo	"hide" | "persist" | "reset"
Valor padrão	'persist'

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId().
Tipo	string
Valor padrão	generateUniqueId()

density

Atributo	density
Descrição	Densidade visual canônica. Quando informada, tem precedência sobre size. Aceita small, medium ou large. Valores inválidos usam medium.
Tipo	"large" | "medium" | "small"
Valor padrão	---

label

Atributo	label
Descrição	Define o rótulo exibido no modo spinner. No modo progress, esta prop não tem efeito.
Tipo	string
Valor padrão	---

labelPosition

Atributo	label-position
Descrição	Define a posição da label em relação ao loading. Valores inválidos usam bottom.
Tipo	"bottom" | "left" | "right" | "top"
Valor padrão	'bottom'

mode

Atributo	mode
Descrição	Define o modo de exibição do componente. Valores inválidos usam spinner.
Tipo	"progress" | "spinner"
Valor padrão	'spinner'

size Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Atributo	size
Depreciação	Use density.
Descrição	Define o tamanho visual nos modos spinner e progress.
Tipo	"large" | "medium" | "small"
Valor padrão	'medium'

speed

Atributo	speed
Descrição	Define a velocidade da animação/transição. Valores inválidos usam normal.
Tipo	"fast" | "normal" | "slow"
Valor padrão	'normal'

value

Atributo	value
Descrição	Define o progresso no modo progress. No modo spinner, esta prop não tem efeito. Valores não numéricos usam 0; valores fora de 0–100 são limitados ao intervalo.
Tipo	number
Valor padrão	0

Slots

Nome	Descrição
"cancel-button"	Conteúdo customizado do botão de cancelar. Quando utilizado, a prop cancelLabel é ignorada.
"label"	Rótulo customizado do loading. Quando utilizado, a prop label é ignorada.

Eventos

Evento	Descrição	Depreciação	Propagação
brDidHide	Notifica que o componente foi ocultado.	---	true
brDidShow	Notifica que o componente foi exibido.	---	true
brIndeterminateStateChange	Notifica mudança do estado lógico no modo spinner.	---	true
brLoadingCancel	Notifica clique no botão de cancelamento no modo progress. Este evento não altera o progresso automaticamente. A aplicação consumidora define a ação após o cancelamento (ex.: limpar ou ocultar).	---	true
brLoadingChange	Notifica mudança de progresso no modo progress.	---	true
brLoadingComplete	Notifica conclusão do progresso no modo progress.	---	true
brLoadingHide	Evento canônico emitido quando o loading é ocultado.	---	true
brLoadingReset	Notifica reinício do progresso no modo progress.	---	true
brLoadingShow	Evento canônico emitido quando o loading é exibido.	---	true

Métodos

complete

Descrição	Define o progresso como concluído.
Assinatura	complete() => Promise<{ value: number; }>
Parâmetros	---

hide

Descrição	Oculta o componente.
Assinatura	hide() => Promise<{ visible: boolean; }>
Parâmetros	---

incrementValue

Descrição	Soma um valor ao progresso atual.
Assinatura	incrementValue(step?: number) => Promise<{ value: number; }>
Parâmetros	step: Incremento aplicado.

reset

Descrição	Reinicia o progresso e exibe o componente.
Assinatura	reset() => Promise<{ value: number; }>
Parâmetros	---

setValue

Descrição	Define o valor do progresso.
Assinatura	setValue(value: number) => Promise<{ value: number; }>
Parâmetros	value: Valor desejado.

show

Descrição	Exibe o componente.
Assinatura	show() => Promise<{ visible: boolean; }>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"cancel-button"	Botão de cancelamento no modo progress cancelável.
"container"	Wrapper principal do loading.
"label-wrapper"	Wrapper do rótulo no modo spinner.
"percentage"	Texto de percentual no modo progress.
"svg"	Elemento SVG principal do loading.
"wrapper"	Wrapper do conteúdo do spinner/progress.

Eventos nativos

Elemento HTML de referência

O modo determinado referencia semanticamente <progress>, mas br-loading renderiza SVG/contêiner com role="progressbar". Não existe controle nativo interno equivalente.

Como ouvir os eventos

const loading = document.querySelector('br-loading');

loading.addEventListener('brLoadingComplete', (event) => {
  console.log(event.detail);
});

Eventos nativos suportados

<progress> não define um evento próprio de mudança. Alterar value programaticamente não emite input nem change.

Eventos não aplicáveis ou não suportados

Evento	Situação	Motivo	Alternativa
input / change	Não aplicável	Indicador não é controle editável.	Observe a fonte da operação ou brLoadingChange.
eventos de formulário	Não aplicável	O indicador não participa de FormData.	Mantenha estado no fluxo da aplicação.

Eventos customizados do componente

brLoadingChange, brLoadingCancel, brLoadingComplete, brLoadingReset, brLoadingShow e brLoadingHide representam o ciclo próprio. Consulte a tabela gerada de eventos para payload e flags.

Valor e estado após o evento

value é propriedade/estado, não evento. Consulte também mode, completion e cancelable no host.

Frameworks

HTML usa addEventListener; React usa ref; Angular e Vue usam listeners para os eventos brLoading*. Não use onChange como substituto.

Acessibilidade

O host expõe nome e estado por role="progressbar" e atributos ARIA. O modo indeterminado não anuncia valor numérico.

Evidência de teste

_tests/loading.e2e.tsx cobre ARIA, valor e eventos próprios em Chromium headless. Não há evento nativo a comparar; três engines permanecem pendentes.

Dependências

Usado por

• br-input
• br-pagination
• br-select-list
• br-table
• br-textarea
• br-upload

Depende de

• br-button

Gráfico

Migração de <br-loading> (1.x → 2.x)

O loading continua aceitando um valor de progresso, mas seus modos e tamanhos agora são propriedades explícitas.

Propriedades e controle

API 1.x	API 2.x	Ação na migração
—	label, cancelable, labelPosition	Use quando precisar de acessibilidade e controle de cancelamento.
medium	size="medium"	Substitua o booleano pelo tamanho explícito.
percent	value	Renomeie a propriedade.
progress	mode	Converta para o modo de carregamento atual.

Para controlar o componente, prefira os métodos show, hide, reset, setValue e incrementValue. Acompanhe o ciclo de vida pelos eventos brLoading*.

Exemplo

1.x:

<br-loading progress percent="40" medium></br-loading>

2.x:

<br-loading mode="progress" value="40" size="medium" label="Carregando"></br-loading>