Wizard

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

currentIndex

Atributo	current-index
Descrição	Índice atual zero-based para controle externo opcional.
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().
Tipo	string
Valor padrão	generateUniqueId()

initialIndex

Atributo	initial-index
Descrição	Índice inicial zero-based. Quando informado, tem precedência sobre initialStep.
Tipo	number
Valor padrão	---

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

Atributo	initial-step
Depreciação	Use initialIndex.
Descrição	Índice da etapa inicial do wizard. Define qual etapa será exibida ao carregar o componente. A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).
Tipo	number
Valor padrão	1

orientation

Atributo	orientation
Descrição	Orientação visual do wizard. Define se os indicadores de progresso serão exibidos horizontalmente ou verticalmente.
Tipo	"horizontal" | "vertical"
Valor padrão	'horizontal'

progressionType

Atributo	progression-type
Descrição	Tipo de progressão entre etapas. - linear: O usuário deve completar cada etapa sequencialmente. Não é possível pular etapas futuras. - nonlinear: O usuário pode navegar livremente entre qualquer etapa.
Tipo	"linear" | "nonlinear"
Valor padrão	'nonlinear'

step

Atributo	step
Descrição	Etapa atual (numeração 1-indexada). Reflete para atributo step.
Tipo	number
Valor padrão	1

Slots

Nome	Descrição
"cancel-button"	Conteúdo customizado do botão de cancelar. Quando utilizado, o texto padrão "Cancelar" é substituído.
"default"	Slot para os painéis de etapa (br-wizard-panel) do wizard.
"next-button"	Conteúdo customizado do botão de avançar/concluir. Quando utilizado, os textos padrão "Avançar" e "Concluir" são substituídos.
"previous-button"	Conteúdo customizado do botão de voltar. Quando utilizado, o texto padrão "Voltar" é substituído.

Eventos

Evento	Descrição	Depreciação	Propagação
brWizardBeforeStepChange	Evento emitido ANTES de mudar de etapa (permite validação e cancelamento). Comportamento: - Disparado apenas ao AVANÇAR (targetStep > currentStep) - Não é disparado ao VOLTAR (targetStep < currentStep) - Funciona tanto para cliques nos botões quanto para cliques diretos nos steps - Pode ser cancelado com event.preventDefault() para bloquear a navegação	---	true
brWizardCancel	Evento emitido ao cancelar o wizard.	---	true
brWizardComplete	Evento emitido ao concluir o wizard (última etapa).	---	true
brWizardNavigationBlocked	Evento emitido quando uma ação é bloqueada (validação falha, progressão linear impedida). Emite uma string indicando o motivo: 'linear-progression' ou 'validation-failed'. Use getCurrentStepIndex() para obter o contexto da etapa atual.	---	true
brWizardStepChange	Evento emitido APÓS mudar de etapa com sucesso. Este evento é disparado independente da origem da navegação: - Botões "Avançar" ou "Voltar" - Click direto em um step do indicador de progresso - Chamadas programáticas via métodos públicos (goToStep, nextStep, etc)	---	true

Métodos

getAllSteps

Descrição	Retorna todos os painéis do wizard.
Assinatura	getAllSteps() => Promise<HTMLElement[]>
Parâmetros	---

getCurrentStep

Descrição	Retorna o elemento HTML do painel ativo no momento.
Assinatura	getCurrentStep() => Promise<HTMLElement | null>
Parâmetros	---

getCurrentStepIndex

Descrição	Retorna o índice (número) da etapa atual. A numeração começa em 1 (primeira etapa = 1, segunda = 2, etc).
Assinatura	getCurrentStepIndex() => Promise<number>
Parâmetros	---

getStepByIndex

Descrição	Retorna um painel específico pelo índice.
Assinatura	getStepByIndex(stepNumber: number) => Promise<HTMLElement | null>
Parâmetros	stepNumber: - Número da etapa (numeração começa em 1)

getTotalSteps

Descrição	Retorna o número total de etapas do wizard.
Assinatura	getTotalSteps() => Promise<number>
Parâmetros	---

goToStep

Descrição	Navega para uma etapa específica. Executa validação se estiver avançando (etapa alvo > etapa atual).
Assinatura	goToStep(stepNumber: number) => Promise<boolean>
Parâmetros	stepNumber: - Número da etapa de destino (numeração começa em 1)

next

Descrição	Avança para a próxima etapa.
Assinatura	next() => Promise<boolean>
Parâmetros	---

nextStep

Descrição	Avança para a próxima etapa. Executa validação via evento brWizardBeforeStepChange antes de navegar.
Assinatura	nextStep() => Promise<boolean>
Parâmetros	---

previous

Descrição	Retorna para a etapa anterior.
Assinatura	previous() => Promise<boolean>
Parâmetros	---

previousStep

Descrição	Volta para a etapa anterior. Não executa validação ao retornar.
Assinatura	previousStep() => Promise<boolean>
Parâmetros	---

reset

Descrição	Retorna à primeira etapa do wizard. Não executa validação (útil para reiniciar o fluxo).
Assinatura	reset() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"buttons"	Área de botões de navegação.
"content"	Conteúdo do painel ativo.
"form"	Área do formulário do wizard.
"panel"	Painel ativo do wizard.
"progress"	Área de progresso do wizard.

Dependências

Subcomponentes

• br-wizard-panel

Depende de

• br-step
• br-step-item
• br-button

Gráfico