Pular para o conteúdo
Navegação

Steps

/componentes/steps.mdmarkdown cru, para quem lê com agent em vez de olho

No meio

Passo 2 de 3

Turma

Importar
import { Steps } from '@rivocode/ui'

Quando usar

A régua de passos de um formulário longo. Anda junto com o useWizard().

No celular vira uma linha de texto com barra de progresso: quatro bolinhas com rótulo em 390px viram quatro palavras cortadas, e o que importa ali é saber quanto falta.

As duas formas estão sempre na página, e o CSS mostra uma de cada vez. O className, o aria-label e os demais atributos valem para as duas, e a linha do celular vira group quando recebe nome. O id, o ref e o data-testid ficam só na lista da mesa, porque identidade não pode aparecer duas vezes na página; referência por aria-describedby continua lendo a lista mesmo escondida.

Só dá para voltar, nunca pular para frente. Passo adiante costuma depender do que o anterior validou, e um clique que atravessa isso leva a pessoa a uma tela que ela não sabe preencher. Por isso o onStepChange só é chamado com um passo já concluído, e sem ele a régua inteira é só leitura. Só o passo que se clica é <button>: o atual, os futuros e os concluídos sem onStepChange são div, e não botão desabilitado - botão que nunca funciona é parada de Tab e nome de botão para o leitor de tela, prometendo uma ação que não existe.

Com step={steps.length}, tudo concluído, a régua larga mostra todas as bolinhas feitas e o celular para no último passo, com a barra cheia e o "concluído" para o leitor de tela. Antes ele contava "Passo 5 de 4", sem título, e a barra passava de 100%.

O par é step e onStepChange, o mesmo do Tour: passo de uma sequência, contado de zero.

O estado, e o rodapé

useWizard(steps) conta e valida a passagem, e não desenha nada. Devolve um WizardState: o índice step, o current da lista, os avisos isFirst e isLast, e next, back e goTo.

O next aceita uma checagem que pode ser assíncrona. Devolva false e o passo não anda. É por aqui que entra o trigger do React Hook Form, sem o assistente precisar conhecer o React Hook Form:

const steps: Step[] = [
  { id: 'client', title: 'Cliente' },
  { id: 'items', title: 'Itens' },
  { id: 'review', title: 'Conferir' },
]

const wizard = useWizard(steps)

<Steps steps={steps} step={wizard.step} onStepChange={wizard.goTo} />

<WizardFooter>
  <Button variant="ghost" onClick={wizard.back} disabled={wizard.isFirst}>
    Voltar
  </Button>
  <Button onClick={() => wizard.next(() => form.trigger())}>
    {wizard.isLast ? 'Fazer o pedido' : 'Continuar'}
  </Button>
</WizardFooter>

O next troca o passo só depois que o clique termina. Dentro de um <form>, o último passo costuma trocar o Continuar por um botão type="submit". Se a troca acontecesse no meio do clique, o navegador terminaria aquele clique como envio, e a pessoa pagaria sem ver a revisão. Dê key diferente aos dois botões também, para o React criar outro elemento em vez de mudar o tipo do mesmo.

WizardFooter põe voltar de um lado e avançar do outro, e o último filho vai sempre para o fim: no primeiro passo, sem o Voltar, o Continuar fica à direita, no mesmo lugar dos passos seguintes, e não pula para a esquerda. No celular empilha na ordem invertida com os dois ocupando a largura toda, o botão que continua embaixo, onde o polegar está, e gruda no pé da tela (sticky bottom-0, na camada --rc-z-sticky, com um traço em cima): o formulário rola por baixo e o avanço não sai de alcance. O fundo é o de quem está em volta: o Card, o Dialog e a Sheet declaram a superfície deles em --rc-ground, e o rodapé a pinta; solto na página, ele pinta o fundo da página. Painel montado à mão com outro fundo declara o dele no className ([--rc-ground:var(--rc-surface)]), ou vira Card.

Quando não usar

Para o que já aconteceu com alguma coisa (a trilha de uma entrega, o histórico de uma alteração), use Timeline. Esta régua é de assistente: olha para a frente, sabe quantos passos faltam e existe para conduzir alguém até o fim de um formulário. A linha do tempo olha para trás, e ninguém avança nela.

Dois ou três campos não pedem assistente. Quebrar em passos um formulário que cabe numa tela troca a rolagem por cliques, e esconde de quem preenche o tamanho do que ele aceitou fazer.

No React Native

Traduz, e o que porta é o modo estreito que o web já desenhava: a linha "Passo 2 de 4", o título do passo e a barra de progresso. A régua de bolinhas não atravessa porque ela já tinha sido medida e reprovada abaixo de 640px: cinco passos numa faixa de 390px dão 60px de rótulo por passo, e "Conferir os itens" vira "Confe…" cinco vezes seguidas. A descrição, que o modo estreito do web esconde por falta de largura, aparece: aqui o passo atual é o único na tela.

Por isso não há onStepChange: ele só existia na régua larga, e sem bolinha não há o que tocar. Voltar é o botão do WizardFooter, e pular passo continua sendo o goTo.

O useWizard() atravessa inteiro e idêntico: é useState e três contas de índice, sem DOM e sem media query. Deixar o passo para o router nativo seria trocar um estado de tela por cinco rotas, e um assistente não é navegação: os passos partilham um formulário só, o back do aparelho não pode perder o que já foi digitado, e "Conferir" não é um endereço que alguém deva abrir direto. Quem quiser uma rota por passo continua podendo, porque o goTo aceita o índice que o router mandar. O WizardFooter empilha sempre, na ordem escrita (voltar em cima, avançar embaixo, onde o polegar está), e o w-full de cada botão, que no web chega por seletor de filho, aqui é o alignItems: stretch padrão do React Native.

API

PropTipo
stepobrigatória

Indice do passo atual, contando de zero.

number
stepsobrigatória0.4.0Step[]
labels

Os textos da peca, para trocar o idioma: `position` e a contagem "Passo 2 de 5", que recebe o passo atual contando de 1 e o total; `done` e o que o leitor de tela ouve depois do titulo de um passo ja feito, "concluído" sem ele.

Partial<StepsLabels>
onStepChange

Recebe o indice do passo ja concluido que foi clicado.

((step: number) => void)

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.