Pular para o conteúdo
Formulário

Questionnaire

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

Onboarding, uma pergunta por vez

Pergunta 0 de 0
x
Quantas pessoas vão usar a conta?

Dá para convidar mais gente depois.

O agente pergunta, a pessoa responde

Marque o retorno da paciente Lívia Antunes para a semana que vem.
Entrada
{
  "perguntas": [
    "especialidade",
    "periodo"
  ]
}
Pergunta 0 de 0
x
O retorno é com qual especialidade?

Pergunta desabilitada e erro

Qual endereço a loja vai usar?, Opcional

Libera depois que o domínio próprio for verificado.

Quem aprova as compras da equipe?
Importar
import { Questionnaire } from '@rivocode/ui'

Quando usar

Um formulário que faz uma pergunta por vez. Guarda as respostas, diz em que pergunta a pessoa está, valida antes de avançar e cuida do voltar, do pular e do enviar. Serve para o agente de IA que precisa de um esclarecimento antes de agir, para o onboarding, para a pesquisa curta, para a triagem e para a configuração inicial.

<Questionnaire aria-label="Configurar a conta" onSubmit={(answers) => save(answers)}>
  <QuestionnaireProgress />

  <QuestionnaireItem name="equipe" required>
    <QuestionnaireTitle>Quantas pessoas vão usar a conta?</QuestionnaireTitle>
    <QuestionnaireDescription>Dá para convidar mais gente depois.</QuestionnaireDescription>
    <QuestionnaireChoices>
      <QuestionnaireChoice value="solo">Só eu</QuestionnaireChoice>
      <QuestionnaireChoice value="pequena">De 2 a 10 pessoas</QuestionnaireChoice>
    </QuestionnaireChoices>
    <QuestionnaireError />
  </QuestionnaireItem>

  <QuestionnaireItem name="avisos" multiple>
    <QuestionnaireTitle>Por onde você quer receber os avisos?</QuestionnaireTitle>
    <QuestionnaireChoices>
      <QuestionnaireChoice value="email">E-mail</QuestionnaireChoice>
      <QuestionnaireChoice value="whatsapp">WhatsApp</QuestionnaireChoice>
    </QuestionnaireChoices>
    <QuestionnaireInput placeholder="Outro canal" />
  </QuestionnaireItem>

  <QuestionnaireFooter>
    <QuestionnairePrevious />
    <QuestionnaireSkip />
    <QuestionnaireNext />
    <QuestionnaireSubmit />
  </QuestionnaireFooter>
</Questionnaire>

Uma pergunta por vez

Cada QuestionnaireItem é um <fieldset>, e o QuestionnaireTitle é a <legend> dele: o leitor de tela anuncia a pergunta junto com cada opção. Só a pergunta aberta aparece; as outras ficam escondidas e inert, fora do Tab e fora da leitura. A troca desliza para o lado da direção, com a curva e a duração dos tokens de movimento, e sem deslize quando o sistema pede para reduzir movimento.

A ordem é a ordem em que os itens aparecem na árvore. defaultItem abre em outra pergunta; item e onItemChange controlam a pergunta aberta pelo name, para quem quer guardar o passo na URL.

QuestionnaireProgress escreve "Pergunta 2 de 5" e a barra do Progress com o mesmo valor. Ao avançar, o foco vai para o primeiro controle da pergunta nova.

Obrigatória e opcional

  • required não deixa avançar sem resposta, e o "Pular" some.
  • Sem required, a pergunta vale de dois jeitos: com resposta, ou pulada de propósito pelo "Pular". Avançar sem nenhum dos dois também mostra erro, porque em pesquisa pular por engano e pular por escolha são coisas diferentes. O título ganha a marca "Opcional".

Quando a validação falha, o QuestionnaireError do item diz o motivo (sem ele na árvore, a frase sai sozinha no fim do item), o item fica descrito por ela, e o foco vai para o primeiro controle. No envio, a validação passa por todas as perguntas e volta para a primeira que falhou.

onStatusChange de cada item conta quando ele muda entre unanswered, answered e skipped. disabled mostra a pergunta sem deixar responder: ela fica fora da validação e das respostas.

As respostas

As opções são <input> nativos, e o name do item é o name deles: sem multiple são radios, com multiple são caixas de marcar. O QuestionnaireInput também leva o name do item. Por isso o formulário é um formulário de verdade, e o onSubmit recebe a mesma resposta de duas formas:

<Questionnaire
  onSubmit={(answers, data) => {
    answers.equipe // "pequena"
    answers.avisos // ["email", "SMS"]
    data.getAll('avisos') // o mesmo, pelo FormData
  }}
/>

Pergunta pulada fica ausente dos dois, e não com texto vazio. Pular também limpa o que já estava marcado nela, e a limpeza passa pelo onChange de cada controle: um QuestionnaireInput controlado recebe o texto vazio como se a pessoa tivesse apagado, e o estado de quem controla acompanha a tela.

Respostas que já vêm marcadas

defaultAnswers traz as respostas de antes, no mesmo formato do onSubmit: texto na escolha única e no campo livre, lista no multiple. Valor que não é de nenhuma opção vai para o QuestionnaireInput do item, como resposta "outra". Vale na montagem, como o defaultValue de um campo, e a pergunta preenchida assim já conta como respondida no progresso e na validação.

onAnswersChange entrega as respostas a cada mudança e a cada pulo, para guardar o rascunho enquanto a pessoa responde. Juntos, os dois retomam um questionário interrompido:

<Questionnaire
  defaultAnswers={draft ?? undefined}
  onAnswersChange={(answers) => saveDraft(answers)}
  onSubmit={(answers) => send(answers)}
/>

Não há answers controlado no web: as respostas moram nos <input> do formulário, e o FormData do onSubmit sai deles. Quem precisa controlar um campo controla o QuestionnaireInput ou a QuestionnaireChoice com checked.

No servidor, a pergunta aberta já sai no HTML: item, defaultItem ou, sem nenhum dos dois, a primeira na ordem da página, com os botões dela.

Sozinho no item, o QuestionnaireInput é a resposta livre, e o nome dele é o título da pergunta. Ao lado de opções ele é a resposta "outra", e o nome falado é "Outra resposta": numa pergunta de escolha única, escrever nele desmarca a opção, e marcar uma opção apaga o texto; com multiple, o texto entra na lista junto com as marcadas.

O teclado

Cada opção tem um atalho: A, B, C, ou 1, 2, 3 com shortcuts="numbers". A letra aparece na própria opção e vai para o aria-keyshortcuts do input. O atalho vale com o foco dentro do questionário e para enquanto se digita num campo: escrever "abc" no campo livre não marca nada. shortcuts={false} desliga.

Ctrl+Enter (ou ⌘+Enter) valida e avança, e na última pergunta envia. No campo livre, Enter faz o mesmo.

Com um agente de IA

É a forma de o agente pedir esclarecimento sem sair da conversa: o ToolCall mostra o que ele quer, e o questionário colhe a resposta. Quando a pessoa envia, a chamada vira done com as respostas de saída.

const [answers, setAnswers] = useState<QuestionnaireAnswers | null>(null)

<ToolCall
  name="pedir_esclarecimento"
  title="Preciso de duas respostas antes de agendar"
  status={answers ? 'done' : 'approval'}
  output={answers ?? undefined}
/>
{!answers && (
  <Questionnaire shortcuts="numbers" onSubmit={(sent) => setAnswers(sent)}>
    <QuestionnaireItem name="periodo" required>
      <QuestionnaireTitle>Qual período a paciente prefere?</QuestionnaireTitle>
      <QuestionnaireChoices>
        <QuestionnaireChoice value="manha">Manhã</QuestionnaireChoice>
        <QuestionnaireChoice value="tarde">Tarde</QuestionnaireChoice>
      </QuestionnaireChoices>
    </QuestionnaireItem>
    <QuestionnaireFooter>
      <QuestionnaireSubmit>Responder ao agente</QuestionnaireSubmit>
    </QuestionnaireFooter>
  </Questionnaire>
)}

shortcuts="numbers" combina com o campo de prompt ao lado: letra é o que a pessoa digita na conversa, e o atalho só vale com o foco no questionário.

Os textos

Todos saem em português e todos se trocam por labels: progress (recebe a posição e o total), previous, skip, next, submit, required, unanswered, other e optional. Os botões também aceitam filho, que vale só para aquele botão.

Partes

  • QuestionnaireProgress: o texto e a barra; aceita o classNames do Progress (label, value, track, indicator).
  • QuestionnaireItem, QuestionnaireTitle, QuestionnaireDescription: a pergunta.
  • QuestionnaireChoices, QuestionnaireChoice: as opções. classNames da opção alcança control (a linha inteira), key, label, description e indicator.
  • QuestionnaireInput: a resposta livre, ou a "outra".
  • QuestionnaireError: a frase do erro, no lugar que você escolher.
  • QuestionnaireFooter com QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext e QuestionnaireSubmit: os botões são o Button da casa. O "Voltar" encosta à esquerda, o "Próxima" some na última pergunta e o "Enviar" só existe nela.

Quando não usar

  • Todas as perguntas cabem numa tela: use o Form, com um FormField por pergunta. Esconder quatro perguntas curtas atrás de quatro cliques troca uma olhada por uma sequência, e quem quer revisar antes de enviar não vê nada.
  • Etapas longas, cada uma com vários campos: use Steps com o useWizard. O questionário é uma pergunta por tela; um cadastro em que cada passo tem endereço, telefone e documento é assistente, e a régua do Steps mostra os passos pelo nome.
  • Uma escolha só, dentro de outra tela: RadioGroup ou CheckboxGroup. Um questionário de uma pergunta é um grupo de opções com progresso "1 de 1".
  • Confirmar uma ação do agente: o ToolCall em approval já tem Aprovar e Recusar. O questionário é para quando a resposta não cabe num sim ou não.

No React Native

Traduz, uma pergunta por vez e com os mesmos estados: obrigatória não avança sem resposta, opcional vale por resposta ou por pular, e o envio volta para a primeira pergunta que falhou. A regra de validação e os textos moram num arquivo só, compartilhado pelos dois pacotes, e labels troca os mesmos nomes.

A API é a do toque: tudo é controlado (item e onItemChange, value e onValueChange), e as perguntas vêm por items, cada uma com type single, multiple ou text, e other para o campo de resposta outra. Não há atalho de letra, porque não há teclado físico; a troca de pergunta e o erro saem pelo anúncio do leitor de tela do sistema, e a pergunta nova entra com os tokens de movimento.

O defaultAnswers e o onAnswersChange do web não fazem falta aqui: as respostas já são o value controlado, e o rascunho se retoma passando o salvo como valor inicial do estado.

API

PropTipoPadrão
defaultAnswers

As respostas que ja vem marcadas, pela chave de cada item: texto na escolha unica e no campo livre, lista no `multiple`.

QuestionnaireAnswerssem padrão
defaultItem

A pergunta aberta no comeco, sem controlar.

stringsem padrão
item

A pergunta aberta, pelo `name` do item.

stringsem padrão
labels

Os textos da peca: botoes, progresso e erros, para outra lingua ou outro tom.

Partial<QuestionnaireLabels>sem padrão
onAnswersChange

Chamado a cada resposta que muda e a cada pergunta pulada, com o mesmo formato do `onSubmit`.

((answers: QuestionnaireAnswers) => void)sem padrão
onItemChange

Chamado a cada troca de pergunta, com o `name` da nova.

((item: string) => void)sem padrão
onSubmit

Chamado quando a ultima pergunta valida e todas as anteriores tambem.

((answers: QuestionnaireAnswers, data: FormData) => void)sem padrão
refRef<HTMLFormElement>sem padrão
shortcuts

O atalho de cada opcao: `letters` marca a primeira com A, `numbers` com 1.

false | QuestionnaireShortcuts"letters"

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.