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

O componente br-wizard é o orquestrador completo de fluxos passo a passo do GovBR-DS, desenvolvido para guiar a pessoa usuária através de formulários e tarefas complexas distribuídas em etapas consecutivas.

Para que serve

• Condução guiada de processos: Apresenta um formulário longo dividido em etapas menores e focadas, reduzindo a carga cognitiva e o índice de abandono.
• Barra de progresso e navegação integradas: Combina o indicador visual de etapas (step), os painéis de conteúdo de cada etapa (br-wizard-panel) e a barra de ações com botões de "Voltar", "Avançar", "Concluir" e "Cancelar".
• Validação por etapa: Permite interceptar o avanço de cada passo para validação antes de liberar o próximo painel.

Quando utilizar

• Utilize quando:
  • Houver um processo de cadastro, requerimento, compra ou configuração estruturado em etapas com dependência de sequência.
  • For essencial oferecer navegação pré-programada de retorno e avanço com controle de estado.
• Evite e prefira outro componente quando:
  • O objetivo for apenas mostrar o status de um pedido já concluído (use br-step simples).
  • O usuário puder navegar em qualquer ordem entre as seções da tela (use br-tab).

Composição e Subcomponentes

Subcomponente	Papel	Regra de uso
br-wizard-panel	Painel de etapa individual. Contém os campos e formulários de uma etapa específica.	Declarado dentro do slot padrão do br-wizard.
br-wizard	Orquestrador principal. Gerencia a barra de progresso, ações de navegação (voltar/avançar), botões de rodapé e controle do painel ativo.	Deve ser o contêiner raiz do fluxo.

Como os subcomponentes se relacionam

O br-wizard gerencia ativamente os elementos br-wizard-panel declarados em seu interior:

1. O pai exibe apenas o painel correspondente à etapa atual (activeStep), mantendo os demais ocultos.
2. Ao avançar ou retroceder, o br-wizard dispara eventos de validação e troca de etapa (brStepChange), atualizando simultaneamente o cabeçalho de progresso e as ações do rodapé.

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ão

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

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; valores inválidos usam 0.
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). Valores inválidos usam 1.
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