Questionnaire

import {
  Questionnaire,
  QuestionnaireActions,
  QuestionnaireChoice,
  QuestionnaireChoices,
  QuestionnaireDescription,
  QuestionnaireError,
  QuestionnaireInput,
  QuestionnaireItem,
  QuestionnaireNext,
  QuestionnairePrevious,
  QuestionnaireProgress,
  QuestionnaireSkip,
  QuestionnaireSubmit,
  QuestionnaireTitle,
} from "@/components/ui/questionnaire"

function Actions() {
  return (
    <QuestionnaireActions>
      <QuestionnairePrevious />
      <QuestionnaireSkip />
      <QuestionnaireNext />
      <QuestionnaireSubmit />
    </QuestionnaireActions>
  )
}

export default function QuestionnaireDemo() {
  return (
    <div className="w-[28rem]">
      <Questionnaire onSubmit={(event) => event.preventDefault()}>
        <QuestionnaireProgress />
        <QuestionnaireItem name="role" required>
          <QuestionnaireTitle>
            What best describes your role?
          </QuestionnaireTitle>
          <QuestionnaireDescription>
            This helps us tailor the setup to your team.
          </QuestionnaireDescription>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="engineering">
              Engineering
            </QuestionnaireChoice>
            <QuestionnaireChoice value="design">Design</QuestionnaireChoice>
            <QuestionnaireChoice value="product">Product</QuestionnaireChoice>
            <QuestionnaireChoice value="other">
              Something else
            </QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>
        <QuestionnaireItem name="team-size">
          <QuestionnaireTitle>How large is your team?</QuestionnaireTitle>
          <QuestionnaireChoices>
            <QuestionnaireChoice value="solo">Just me</QuestionnaireChoice>
            <QuestionnaireChoice value="small">
              2 to 10 people
            </QuestionnaireChoice>
            <QuestionnaireChoice value="medium">
              11 to 50 people
            </QuestionnaireChoice>
            <QuestionnaireChoice value="large">
              More than 50 people
            </QuestionnaireChoice>
          </QuestionnaireChoices>
          <QuestionnaireError />
        </QuestionnaireItem>
        <QuestionnaireItem name="company" required>
          <QuestionnaireTitle>What is your company called?</QuestionnaireTitle>
          <QuestionnaireInput placeholder="Acme Inc." />
          <QuestionnaireError>
            Enter a company name to continue.
          </QuestionnaireError>
        </QuestionnaireItem>
        <Actions />
      </Questionnaire>
    </div>
  )
}

Questionnaire renders a form that presents a sequence of questions, one at a time. Each QuestionnaireItem is a fieldset with a QuestionnaireTitle, an optional QuestionnaireDescription, an answer area and a QuestionnaireError. Answers are either QuestionnaireChoices holding QuestionnaireChoice cards (with optional QuestionnaireChoiceDescription), or a QuestionnaireInput.

QuestionnaireProgress shows the current position, and QuestionnaireActions lays out QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext and QuestionnaireSubmit, which show and hide themselves based on the current question. Use Questionnaire for onboarding flows and surveys; use Field and regular form controls when all fields should be visible at once.

Installation

CLI

$ pnpm dlx shadcn@latest add @esuiss/questionnaire

Works in any project with a components.json. See Installation for the one-line registry setup. Or use the suiss/ui CLI:

$ pnpm dlx @esuiss/ui@latest add questionnaire

Manual

1. Install the dependencies and add the cn helper:

$ pnpm add @base-ui/react @phosphor-icons/react

2. Add the pieces it builds on: Button, use-questionnaire.

3. Copy the source into components/ui/questionnaire.tsx:

4. Update the import paths to match your project.

Usage

import { Questionnaire, QuestionnaireProgress, QuestionnaireItem, QuestionnaireTitle, QuestionnaireDescription, QuestionnaireChoices, QuestionnaireChoice, QuestionnaireChoiceDescription, QuestionnaireInput, QuestionnaireError, QuestionnaireActions, QuestionnairePrevious, QuestionnaireSkip, QuestionnaireNext, QuestionnaireSubmit } 

<div

Give every item a unique name; answers are submitted as form data under that name. The first item is shown by default. Use defaultItem to start elsewhere, or item with onItemChange to control the active question.

A required item blocks Next and Submit until it is answered. An optional item shows the Skip button. Set multiple on an item to render its choices as checkboxes instead of radio buttons.

Pass items to define the sequence, which items are required or disabled, and the order used for shortcut keys, instead of deriving them from the rendered items. Native browser validation is off by default (noValidate); the component runs its own validation on Next and Submit.

Examples

With shortcuts

Choices labelled with letter keys, so pressing a letter selects the matching answer.

Number shortcuts

Choices labelled with number keys from 1 to 9.

Multiple choice

A multiple item with checkboxes, a default selection, a disabled choice and a custom error.

With choice descriptions

Choice cards with a title and a secondary description.

Text input

A required email question answered with QuestionnaireInput.

Start on later question

A questionnaire that opens on its second question with defaultItem.

API Reference

Accessibility

• Each item is a fieldset named by its legend title; inactive items are hidden and inert.
• Choices are native radio buttons or checkboxes inside a label. A choice description is linked with aria-describedby.
• QuestionnaireInput is labelled by the question title unless you pass aria-label.
• The item's description and, when invalid, its error are linked with aria-describedby. The error uses role="alert" and focus moves to the invalid answer.
• QuestionnaireProgress has role="progressbar", an aria-label of Questionnaire progress, aria-valuetext and aria-live="polite".
• Keyboard: Enter on an answered control advances or submits; Command or Control plus Enter advances from anywhere; ArrowUp and ArrowDown move between answers; outside text fields and radio buttons, ArrowLeft goes back and ArrowRight goes forward once the question has an answer. The active item lists these in aria-keyshortcuts.
• Hidden navigation buttons are aria-hidden, inert and removed from the tab order.

Notes

• Styling hooks: every part sets a data-slot, such as questionnaire, questionnaire-item, questionnaire-choice, questionnaire-choice-indicator, questionnaire-choice-shortcut, questionnaire-input and questionnaire-error.
• Choices expose data-checked or data-unchecked, plus data-type, data-disabled, data-invalid and data-shortcut. Inputs expose data-filled or data-empty. Navigation buttons expose data-visible or data-hidden.
• Shortcut badges are hidden below the md breakpoint.
• The default error text is Choose an answer to continue. for required items; pass children to customize it.
• Uses the primary, border, secondary, destructive and accent colors.

Questionnaire is a View that tracks which question is active, collects answers and validates them. Each QuestionnaireItem is one question; only the active item is shown, and moving between items slides the content horizontally with a Reanimated keyframe that follows the layout direction.

Items hold QuestionnaireChoice rows, which are Pressable radios or, with multiple, checkboxes, or a QuestionnaireInput for a typed answer. QuestionnaireActions holds the Previous, Skip, Next and Submit buttons, each of which only appears when it applies.

Installation

$ pnpm dlx shadcn@latest add @esuiss-rn/questionnaire

$ pnpm dlx @esuiss/ui@latest add questionnaire

$ pnpm dlx @esuiss/ui@latest add questionnaire --platform swift