Step

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-step é o indicador visual de etapas e progresso do GovBR-DS, desenvolvido para orientar a pessoa usuária ao longo de fluxos sequenciais e processos com múltiplos passos.

Para que serve

• Visualização de progresso: Informa claramente em qual etapa do processo o usuário se encontra, quais já foram concluídas e quais ainda estão pendentes.
• Orientação flexível: Suporta leiaute horizontal (ideal para telas amplas) e vertical (ideal para fluxos em barra lateral ou dispositivos móveis).
• Semântica e acessibilidade WAI-ARIA: Comunica o passo ativo através de aria-current="step" e indica etapas concluídas ou bloqueadas.

Quando utilizar

• Utilize quando:
  • O fluxo tiver entre 2 e 5 etapas lógicas com uma sequência recomendada de execução (ex.: Identificação > Dados > Pagamento > Confirmação).
• Evite e prefira outro componente quando:
  • A pessoa usuária puder alternar livremente entre as seções em qualquer ordem sem dependência de progresso (prefira br-tab).
  • For necessário um contêiner completo que gerencie também os painéis de formulário e botões de avançar/voltar (prefira br-wizard).

Composição e Subcomponentes

Subcomponente	Papel	Regra de uso
br-step-item	Etapa individual. Representa cada passo com número, rótulo e estado.	Declarado dentro do slot padrão do br-step.
br-step	Orquestrador de progresso. Gerencia a orientação, conecta as linhas de fluxo e calcula os estados das etapas.	Contêiner raiz da barra de progresso.

Como os subcomponentes se relacionam

O componente pai br-step recebe múltiplos elementos br-step-item em seu slot padrão:

1. Com base na propriedade current ou nos índices declarados, o pai calcula as linhas conectoras visuais entre as etapas.
2. Sincroniza os estados de cada etapa: concluída (completed), ativa (active) ou desabilitada (disabled).

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ãoVerticalModo controller

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

contentType

Atributo	content-type
Descrição	Propriedade que define o tipo de conteúdo a ser exibido dentro do componente step e stepItem. Valores inválidos usam default.
Tipo	"br-icon" | "default" | "no-content" | "slotted"
Valor padrão	'default'

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	define o passo que começará destacado. Valores inválidos usam 0.
Tipo	string
Valor padrão	'0'

labelPosition

Atributo	label-position
Descrição	Propriedade que define a posição onde o texto de destaque, label, ficará localizado no stepItem. Valores inválidos usam bottom.
Tipo	"bottom" | "left" | "right" | "top"
Valor padrão	'bottom'

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

Atributo	layout
Depreciação	Use orientation.
Descrição	propriedade responsável por definir a orientação do componente Step. Valores inválidos usam horizontal.
Tipo	"horizontal" | "vertical"
Valor padrão	'horizontal'

mode

Atributo	mode
Descrição	Propriedade que define o tipo de comportamento que o componente Step deverá seguir. Valores inválidos usam step.
Tipo	"controller" | "step"
Valor padrão	'step'

orientation

Atributo	orientation
Descrição	Orientação do componente. Quando informada, tem precedência sobre layout; valores inválidos usam horizontal.
Tipo	"horizontal" | "vertical"
Valor padrão	---

progressionType

Atributo	progression-type
Descrição	Propriedade que define o tipo de progressão de etapas que o step vai executar. Valores inválidos usam nonlinear.
Tipo	"linear" | "nonlinear"
Valor padrão	'nonlinear'

verticalContentPlacement

Atributo	vertical-content-placement
Descrição	Define a posição do conteúdo de cada etapa no layout vertical. - between: conteúdo abaixo do indicador/rótulo, entre as etapas. - side: conteúdo em coluna lateral à linha de indicadores. Valores inválidos usam between.
Tipo	"between" | "side"
Valor padrão	'between'

Slots

Nome	Descrição
"default"	Slot para os itens do step (br-step-item), aceitando apenas esse componente.

Eventos

Evento	Descrição	Depreciação	Propagação
brStepChange	Emite um evento quando o step ativo muda. O evento carrega o índice do novo step ativo (0-based).	---	true

Métodos

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

Descrição	Método disponibilizado via API do elemento que controla o componente Step, responsável por retornar ao passo anterior e atualizar o valor do estado activeStep
Assinatura	BackToPreviousStep() => Promise<void>
Depreciação	Use previous.
Parâmetros	---

GetActiveStep

Descrição	Método disponibilizado via API do elemento que permite a um componente externo obter a etapa com o estado ativo do componente Step.
Assinatura	GetActiveStep() => Promise<number>
Parâmetros	---

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

Descrição	Método disponibilizado via API do elemento que controla o componente Step, responsável por avançar para o próximo passo e atualizar o valor do estado activeStep
Assinatura	ProceedToNextStep() => Promise<void>
Depreciação	Use next.
Parâmetros	---

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

Descrição	Método disponibilizado via API do elemento que integra um componente externo ao componente Step, permitindo sinalizar validações ou destacar a etapa com estado ativo.
Assinatura	StepValidation(validationStatus: StepValidationStatus) => Promise<void>
Depreciação	Use setCurrentValidation.
Parâmetros	validationStatus:

next

Descrição	Avança para o próximo passo.
Assinatura	next() => Promise<void>
Parâmetros	---

previous

Descrição	Retorna ao passo anterior.
Assinatura	previous() => Promise<void>
Parâmetros	---

setCurrentValidation

Descrição	Define o estado de validação do passo ativo.
Assinatura	setCurrentValidation(validationStatus: StepValidationStatus) => Promise<void>
Parâmetros	validationStatus:

CSS Shadow Parts

Nome	Descrição
"container"	Parte para o contêiner principal envolvendo todos os step-items, usada para estilizar layout geral via ::part().

Dependências

Subcomponentes

• br-step-item

Usado por

• br-carousel
• br-wizard

Gráfico