Stepper

Mostra em que passo de um fluxo a pessoa está, com passos concluídos, atual e futuros.

O Stepper indica progresso em fluxos de poucos passos: o onboarding, a importação de CSV (Arquivo, Prévia, Importação) e os Marcos da Jornada. Ele mostra o estado; quem avança é você, no botão "Continuar". Para alternar visões sem ordem, use Tabs; para uma lista cronológica longa, Timeline.

import { Stepper } from "@rastreio-x/ui";

Padrão

currentStep é o índice (a partir de zero) do passo atual. Passos anteriores aparecem concluídos, com o check animado. Dê aria-label à lista.

Pedido aceito
2Coletado
3Em trânsito
4Entregue

Com descrições

Stepper.Description explica o que acontece em cada passo, e cabe melhor em telas largas.

FonteConecte a loja
TemplateEscolha a Origem
3MarcaPublique a Marca
4RevisãoConfira e ative

Vertical

orientation="vertical" empilha os passos, útil em diálogos e colunas estreitas.

ArquivoEscolha o CSV de Pedidos
2PréviaConfira as linhas lidas
3ImportaçãoOs Pedidos são recebidos

Tamanhos

sm (o do onboarding do Admin), md e lg.

Arquivo
2Prévia
3Importação

Arquivo
2Prévia
3Importação

Arquivo
2Prévia
3Importação

Com ícones

Stepper.Icon dentro do Stepper.Indicator troca o número por um ícone de @rastreio-x/ui/icons (com aria-hidden). O passo concluído continua mostrando o check.

Aceito
Coletado
Em trânsito
Entregue

Controlado e clicável

Com onStepChange os passos viram botões; sem ele, o Stepper é só informativo. Controle o estado com currentStep.

Passo 1 de 4

Anatomia

Stepper
├── Stepper.Content
├── Stepper.Description
├── Stepper.Icon
├── Stepper.Indicator
├── Stepper.Separator
├── Stepper.Step
└── Stepper.Title

Stepper.Step: um passo (li); fornece o contexto de estado aos filhos.
Stepper.Indicator: o círculo com número, ícone ou check.
Stepper.Content, Stepper.Title e Stepper.Description: o texto do passo.
Stepper.Separator: a linha entre passos, preenchida conforme o progresso; some no último passo.

Propriedades

Stepper:

Stepper
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`currentStep`	`number`	-	Índice da etapa atual (controlado).
`defaultStep`	`number`	`0`	Índice da etapa inicial (não controlado).
`onStepChange`	`((step: number) => void)`	-	Chamada quando a etapa atual muda.
`orientation`	`'horizontal' \| 'vertical'`	`"horizontal"`	Orientação: `horizontal` (padrão) ou `vertical`.
`size`	`'lg' \| 'md' \| 'sm'`	`"md"`	Tamanho: `sm`, `md` (padrão) ou `lg`.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Stepper.Step:

Stepper.Step
Prop	Tipo	Padrão	Descrição
`_index`	`number`	-	Uso interno do componente: não defina.
`_isLast`	`boolean`	-	Uso interno do componente: não defina.
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Stepper.Separator:

Stepper.Separator
Prop	Tipo	Padrão	Descrição
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`force`	`boolean`	-	Renderiza o separador mesmo na última etapa.
`progress`	`number`	-	Progresso do separador, de 0 a 1; sem ele, é calculado pela etapa atual.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Animações

CSS
indicativo

O check do passo concluído é desenhado com animação e a linha do separador se preenche de acordo com o progresso, em transição de CSS. Com prefers-reduced-motion, a folha global da fachada reduz as transições a 0,01 ms e o estado aparece direto.

Acessibilidade

É uma lista ordenada (ol); o leitor de tela anuncia a posição ("2 de 4").
O passo atual é marcado com aria-current="step"; passos concluídos e futuros se distinguem por ícone e texto, não só por cor.
Com onStepChange, cada passo é um botão alcançável por Tab, ativado com Enter ou Espaço.
Passe aria-label ("Passos do onboarding") para dar nome ao conjunto.
Títulos curtos: o texto não pode ser cortado em 390 px.

Boas práticas

Faça

Três a cinco passos, com títulos curtos em Title Case e o botão de avançar fora do Stepper.

Evite

Dez passos numa linha, ou títulos longos que quebram em várias linhas.

Deixe o Stepper informativo quando o fluxo for linear e validado; torne-o clicável só se voltar não perde dados.
Use sm em cabeçalhos de página e md dentro de diálogos.
Em celulares estreitos, prefira orientation="vertical" ou reduza a quantidade de passos visíveis.

Relacionados

Timeline para eventos cronológicos, como os Marcos entregues.
Tabs para visões sem ordem.
Button para avançar e voltar.