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

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

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. 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.
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.
Tipo	"bottom" | "left" | "right" | "top"
Valor padrão	'bottom'

mode

Atributo	mode
Descrição	Define o modo de exibição do componente.
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.
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 inválidos são normalizados para 0.
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.

Dependências

Usado por

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

Depende de

• br-button

Gráfico

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.

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>