Pular para o conteúdo
Camaleo
PT · ENGitHub
// visualizar em
salvo em todas as páginas

Stepper

Indicador de etapas que mostra em que ponto a pessoa está de um fluxo com ordem fixa, como uma compra ou um cadastro, e quanto falta. É uma lista numerada, não uma navegação.

Padrão Lista ordenada com aria-current="step"Componente clienteCódigo ↗
minimal · light · #3fa34d
  1. ContaE-mail e senha
  2. EmpresaCNPJ e endereço
  3. RevisãoConferir e ativar
orientation

Instalação

Configure o Camaleo uma vez (Instalação) e importe o que precisar. É um componente de cliente: cada etapa lê sua situação do stepper.

import { Stepper, Step, StepIndicator, StepTitle, StepDescription, StepSeparator } from "@camaleo/react";

Anatomia

O Stepper é um <ol> e cada Step um <li>, então o leitor de tela diz "lista, 4 itens" e a posição de cada um. Passe activeStep ao stepper e cada etapa descobre sua situação: concluída antes dele, atual nele, futura depois. A linha entre as etapas é desenhada pela própria etapa, ou por um StepSeparator colocado por último nela; o indicador fica escondido do leitor de tela, então é o título que carrega o sentido. Um stepper horizontal com menos de 30rem de largura (uma container query, não a tela) esconde todos os títulos menos o da etapa atual.

Exemplos

Cada exemplo é um arquivo real que você pode copiar. Todos usam o estilo, o modo e a cor escolhidos na barra acima.

minimal · light · #3fa34d
Finalizar compra3 itens · R$ 274,00
  1. Carrinho, concluída
  2. Entrega
  3. Pagamento
  4. Revisão
  1. Carrinho
  2. Entrega
  3. Pagamento
  4. Revisão

Etapa 1 de 4: Carrinho

Café do Cerrado 500 g, filtros de papel e uma caneca de cerâmica. Subtotal R$ 274,00.

Voltar e Continuar

Clique em Continuar. O foco vai para o título da nova etapa, então o leitor de tela diz "Etapa 2 de 4: Entrega" e quem usa teclado começa no topo do novo formulário.

  1. CarrinhoConcluída
  2. EntregaEm andamento
  3. PagamentoNão iniciada

Situação em palavras

Cor e um sinal de visto não bastam. Dê nome à lista com aria-label e uma palavra para cada situação, visível ou dentro de VisuallyHidden.

  1. , concluída
  2. , concluída
  3. Pagamento
  4. Revisão, não iniciada

Voltar a uma etapa concluída

Clique em Carrinho. Só as etapas que a pessoa já alcançou são links; as seguintes ficam como texto, porque os dados delas ainda não existem.

  1. Carrinho, concluída
  2. Entrega, concluída
  3. Pagamento, precisa de atençãoCartão recusado
  4. Revisão

Cartão recusado. Tente outro cartão.

Etapa com erro

status="error" deixa a etapa vermelha com um X e mantém o aria-current quando ela é a etapa ativa. Diga também em palavras o que deu errado, porque a cor e o ícone não são anunciados.

  1. Pedido feito, concluída
  2. Embalado, aguardando a transportadora
  3. Entregue

Uma linha com estilo próprio

Coloque um StepSeparator por último na etapa quando uma linha precisa de outro visual, como uma linha tracejada até uma etapa que depende de outra pessoa.

  1. Perfil da loja, concluídaNome, logo e endereço da Grão Cafés.
  2. Cadastrar produtos, concluída12 de 12 importados da sua planilha.
  3. Conectar pagamentosVincule uma conta bancária para receber as vendas.
  4. Abrir a lojaEscolha um domínio e publique.

Vertical, com descrições

Em coluna sobra espaço para uma linha embaixo de cada etapa. Use numa barra lateral ou num checklist de configuração que a pessoa retoma depois.

  1. Criar conta, concluídaana@graocafes.com.br
  2. Escolher plano, concluídaPro, R$ 49/mês
  3. Convidar a equipeOpcionalAdicione pessoas agora ou depois em Configurações.
  4. Começar a venderSeu painel está pronto.

Etapa opcional

Marque com um badge, não só com um texto mais claro, para a pessoa saber que pode seguir sem ela.

  1. Carrinho, concluída
  2. Entrega
  3. Pagamento
  4. Revisão

Compacto no celular

Com menos de 30rem de largura, o stepper horizontal mostra só o título da etapa atual; os outros continuam na lista para o leitor de tela. Coloque "Etapa 2 de 4" acima dele para que todos vejam o tamanho do fluxo.

Em contexto

São pedaços inteiros de interface para copiar, no estilo que você escolheu.

Grão Cafés3 itens · R$ 274,00
  1. Carrinho, concluída
  2. Entrega
  3. Pagamento
  4. Revisão

Endereço de entrega

Finalizar compraCard · Stepper · Field · Input · Button

Configure sua loja

2 de 4 concluídas
  1. Perfil da loja, concluída
  2. Cadastrar produtos, concluída
  3. Conectar pagamentos
  4. Abrir a loja
Conectar pagamentos

As vendas caem nesta conta todo dia útil. Leva uns 3 minutos.

Configuração da lojaCard · Badge · Stepper · Field · Button
Pedido nº 4821Feito em 14/03/2026 · 3 itensA caminho
  1. Pedido feito, concluída14/03, 9:12
  2. Embalado, concluída14/03, 16:40
  3. Saiu para entregaPrevisto para hoje até 18h
  4. EntreguePrecisa de assinatura
Rastreio do pedidoCard · Badge · Stepper · Button

Boas práticas

  1. Empresa, concluída
  2. Documentos
  3. Frete
  4. Abrir
FaçaDe três a cinco etapas, com uma ou duas palavras.

A pessoa lê o fluxo inteiro de relance e sabe quanto falta para terminar.

  1. Conte sobre a sua empresa e os sócios, concluída
  2. Envie seus documentos
  3. Configure as regiões e os valores de frete
  4. Revise e abra a sua loja
EviteFrases como rótulos.

Elas não cabem lado a lado, então o stepper esconde todas menos a atual e a pessoa não vê o que vem depois. Coloque os detalhes no título de cada etapa.

Notificações: escolha sobre o que enviamos e-mail para você.
FaçaAbas para seções sem ordem.

Uma página de configurações não tem primeira nem última seção, e nada ali fica "concluído".

  1. Perfil
  2. Notificações
  3. Cobrança
Notificações: escolha sobre o que enviamos e-mail para você.
EviteStepper para navegação livre.

Números e sinais de visto prometem uma ordem e um fim que não existem, e as etapas nem dão para clicar.

Props

PropriedadeTipoPadrãoDescrição
orientationStepperOrientation"horizontal"Coloca as etapas em linha ou em coluna. A vertical comporta descrições e barras laterais estreitas.
activeStepnumber—Índice (a partir de 0) da etapa atual. As anteriores ficam completed, ela fica current e as seguintes upcoming, a não ser que um Step defina o próprio status.
aria-labelstring—Dá nome à lista, por exemplo "Etapas da compra".

O Step recebe status ("completed" · "current" · "upcoming" · "error") ou os atalhos completed e current; sem eles, a situação vem do activeStep, e é "upcoming" quando não há um. O StepIndicator usa a situação da sua etapa, ou o próprio status; com "completed" mostra um sinal de visto e com "error" um X no lugar dos filhos. O resto são as props nativas de <ol>, <li> e <span>.

Styling hooks

Mude o visual sem copiar o componente: use os atributos ou defina os tokens num elemento pai, num estilo ou no próprio stepper.

Atributos

data-orientationhorizontal · vertical (no stepper)
data-statuscompleted · current · upcoming · error (na etapa e no indicador)
aria-current"step" na etapa atual

Tokens que ele lê

Cor

--cml-accent--cml-accent-fg--cml-border-control--cml-brand--cml-brand-50--cml-brand-700--cml-danger--cml-fg--cml-fg-secondary--cml-stepper-completed-bg--cml-stepper-completed-fg--cml-stepper-current-bg--cml-stepper-current-border--cml-stepper-current-fg--cml-stepper-error-border--cml-stepper-error-fg--cml-surface

Forma e tamanho

--cml-border-width

Tipografia e movimento

--cml-font-body--cml-stepper-completed-line--cml-stepper-line

Só deste componente

--cml-step-indicator-bg--cml-step-indicator-fg--cml-step-indicator-radius--cml-step-indicator-size
/* indicadores quadrados e linha mais grossa no checkout */
.checkout [data-slot="stepper"] {
  --cml-step-indicator-radius: 6px;
  --cml-stepper-line: 3px solid var(--cml-border-control);
}

Acessibilidade

TabPula o stepper, a menos que uma etapa tenha um link ou botão; aí passa por eles, em ordem.
EnterNum link de etapa, volta para aquela etapa.

Relacionados

TimelineUm histórico do que aconteceu, com datas, e não um fluxo a concluir.ProgressUma barra para progresso sem etapas com nome.Error summaryLista o que corrigir antes da próxima etapa.
Esta página foi útil? · Editar esta página no GitHub