Stepper
O componente Stepper guia os usuários através de um processo dividido em etapas sequenciais, mostrando seu progresso e permitindo navegar entre as etapas do fluxo.
import React, { useState } from "react";
import { Box, Button, Stepper, Text } from "@nimbus-ds/components";
const labels = [
"Información personal",
"Dirección",
"Método de pago",
"Confirmación",
];
const Example: React.FC = () => {
const [selected, setSelected] = useState(0);
const [activeStep, setActiveStep] = useState(0);
return (
<Box display="flex" flexDirection="column" gap="3" minWidth="250px">
<Text color="neutral-textHigh">Selected step: {selected + 1}</Text>
<Stepper
activeStep={activeStep}
selectedStep={selected}
onSelectStep={setSelected}
justifyContent="flex-start"
>
{labels.map((label) => (
<Stepper.Item key={label} label={label} />
))}
</Stepper>
<Box display="flex" gap="3">
<Button
onClick={() => {
setActiveStep(activeStep - 1);
setSelected(activeStep - 1);
}}
disabled={activeStep === 0}
>
Previous
</Button>
<Button
appearance="primary"
onClick={() => {
setActiveStep(activeStep + 1);
setSelected(activeStep + 1);
}}
disabled={activeStep === labels.length - 1}
>
Next
</Button>
</Box>
</Box>
);
};
export default Example;O Stepper pode conter:
- Asset
- Text
- Line
Este componente utiliza:
- #text
- #icon
O componente Stepper guia os usuários através de um processo dividido em etapas sequenciais, mostrando seu progresso e permitindo navegar entre as etapas do fluxo.
- Guiar o usuário através de um processo estruturado em etapas sequenciais.
- Ideal para fluxos de configuração ou onboarding onde a ordem é relevante.
- Reduzir a carga cognitiva dividindo tarefas complexas. Apresentar uma etapa por vez faz com que o processo pareça mais simples e acessível.
- Permitir a navegação entre etapas. Em fluxos editáveis, o usuário pode voltar a uma etapa anterior para revisar ou corrigir dados.
- O fluxo não requer uma ordem sequencial clara. Se as etapas podem ser completadas em qualquer ordem ou não dependem uma da outra.
- Há menos de três etapas. Não justifica o uso do stepper.
- O usuário não pode interagir com as etapas. Se não é possível avançar nem retroceder manualmente e não há feedback visível.
- Focar o fluxo na ação principal: Ao iniciar um fluxo com Stepper, certifique-se de colocar o foco no primeiro campo relevante da etapa ativa para reduzir o atrito inicial.
- Navegação fluida com teclado: Permitir avançar e retroceder entre etapas usando Tab, Shift+Tab e teclas direcionais.
- Feedback instantâneo e visível: Mostrar indicador de sucesso quando as etapas são concluídas.
- Persistência de contexto: O usuário pode modificar uma etapa anterior sem completar a etapa em curso, e posteriormente finalizá-la.
- Minimizar telas de confirmação: Ao completar uma etapa com sucesso, evitar interrupções e avançar automaticamente para a próxima etapa.
- Suporte completo para navegação por teclado: Garantir que cada etapa e controle dentro do Stepper seja acessível via teclado (Tab/Shift+Tab e Enter).
- Manejo correto do foco: Ao mudar de etapa, o foco deve mover-se automaticamente para o primeiro elemento interativo da nova etapa.
- Mensagens e estados acessíveis: Mostrar os estados (completo, atual, pendente) através de texto visível e atributos aria-current, aria-disabled e aria-label adequados.
- Áreas de toque adequadas no mobile: Garantir que os itens tenham uma área mínima de 44×44px, para garantir uma interação precisa.
- Desktop
- Mobile
- Current: Etapa onde o usuário está atualmente. Não interativo.
- Completed: Etapa que o usuário já finalizou. Pode ser clicável para voltar a editar.
- Rest
- Hovered
- Focused
- Pressed
- Started: Etapa onde o usuário já entrou, mas ainda não completou. Interação possível.
- Rest
- Hovered
- Focused
- Pressed
- Pending: Etapa que ainda não foi iniciada pelo usuário. Não interativo.
✅ Do
- Utilizar o Stepper para dividir um processo em etapas sequenciais claras e com lógica progressiva.
- Manter uma quantidade entre 3 e 5 etapas para garantir clareza e foco.
- Escrever labels breves e orientados à ação para cada etapa.
- No desktop, utilizar o Stepper com o container Card.Stepper, ocupando a largura total do container.
- No mobile, utilizar o Stepper sem container, ocupando a largura total da tela.
- No mobile, mostrar apenas o label correspondente à etapa atual.
❌ Don't
- Não usar o componente se o fluxo tem menos de 3 etapas ou não implica progressão clara.
- Não usar se o usuário não pode editar as etapas.
- Não exceder as 5 etapas visíveis.
- Text - Para mostrar o conteúdo de cada etapa.
- Icon - Para indicadores visuais de estado.
Instale o componente via terminal.
npm install @nimbus-ds/stepperAdditional props are passed to the <Stepper> element. See div docs for a list of props accepted by the <Stepper> element.
Stepper
| Name | Type | Default | Description |
|---|---|---|---|
activeStep* | number | The currently active step (0-based index). Steps before this will be marked as completed. | |
children* | React.ReactNode | The content of the stepper (StepperItem components). Total steps will be calculated automatically based on the number of children. | |
selectedStep* | number | The currently selected step (0-based index). This step will be visually highlighted to show user selection. | |
onSelectStep* | object | Callback called when a step is selected. Receives the step number (0-based index) as parameter. |
Stepper.Item
| Name | Type | Default | Description |
|---|---|---|---|
step* | number | The step number (0-based index) for this item. This is automatically assigned by the parent Stepper component. | |
label | string | The label text to display for this step |
Stepper.Card
| Name | Type | Default | Description |
|---|---|---|---|
children* | React.ReactNode | The content to be rendered inside the card container |