Questionnaire
A step-by-step form that moves between questions with a sense of direction, shows real progress and answers from the keyboard.
- Form components
- 15 parts
- 5 examples
- vs shadcn/ui
@shadcn/react@tabler/icons-reactclass-variance-authority
See it in a real product: Tool Calls
View blockpnpm dlx shadcn@latest add https://hextaui.com/r/questionnaire.jsonAdds the component, the HextaUI theme tokens and any HextaUI components it depends on.
Add the theme tokens to your global CSS, if you haven’t yet.
Install the dependencies.
pnpm add @shadcn/react @base-ui/react @tabler/icons-react class-variance-authority cnCopy and paste the following code into your project.
components/ui/questionnaire.tsx components/ui/button.tsx components/ui/input.tsx components/ui/kbd.tsx components/ui/number-flow.tsx lib/motion.ts Update the import paths to match your project setup.
Answers submit as a regular form, keyed by each item's name. Questions move toward the direction you go, the card eases to each question's height, and the progress fills only for questions that were answered or skipped.
transition="lift" moves questions up and down like a stack. variant="bar" on the progress shows one continuous bar.
With autoAdvance, picking a single answer moves on after a short pause, so you can answer with 1–5 alone. Changing an earlier answer never jumps ahead, and the last question never submits by itself.
Disable an item to leave it out. It drops from the progress and the flow until it applies.
The slide follows the reading direction.
| Key | Action |
|---|---|
| ↑↓ | Moves between the answers, including the text field. Moving doesn't pick. |
| Space | Picks the focused answer, or toggles it in multiple choice. |
| Enter | Continues. On an unpicked single answer it picks it first. Submits on the last question. |
| ←→ | Previous or next question, mirrored in right-to-left. Next shakes when an answer is needed. Inside the text field they move the cursor. |
| HomeEnd | First or last answer. |
| A1 | Picks an answer by its key when shortcuts is set. Key caps brighten once the questionnaire has focus; click anywhere in it to start. |
| Esc | Leaves the text field so letter shortcuts work again. |
| ⌘Enter | Submits from anywhere. |
- Each
QuestionnaireItemis a<fieldset>whose title is its<legend>. Inactive questions are hidden and inert, including the one animating out. - The progress is a
progressbarthat announces “Question 2 of 5”; the segments and spinning number are decorative. - Errors use
role="alert"and the invalid answers getaria-invalid. - With reduced motion, questions switch instantly and nothing shakes.
| Prop | Type | Default |
|---|---|---|
transition | "slide" | "lift" | "slide" |
autoAdvanceMoves on 350ms after a single answer is picked for the first time. | boolean | false |
shortcutsAdds a key shortcut to every answer. | "letters" | "numbers" | – |
item | string | – |
defaultItem | string | – |
onItemChange | (item: string) => void | – |
| Attribute | Description |
|---|---|
data-slot="questionnaire" | The form, with data-transition. |
data-current / data-total | The current position and number of questions. |
data-first / data-last | Present on the first or last question. |
| Prop | Type | Default |
|---|---|---|
variant | "segments" | "bar" | "segments" |
| Attribute | Description |
|---|---|
data-slot="questionnaire-progress-segment" | One per question, with data-status, data-active and data-invalid. |
| Prop | Type | Default |
|---|---|---|
nameThe form field name. | string | – |
required | boolean | false |
multipleCheckboxes instead of radios. | boolean | false |
disabledLeaves the question out of the flow. | boolean | false |
onStatusChange | (status) => void | – |
| Attribute | Description |
|---|---|
data-status | "unanswered", "answered" or "skipped". |
data-active | The current question. |
data-invalid | Needs an answer. |
data-leaving | The question animating out. |
| Prop | Type | Default |
|---|---|---|
value | string | – |
defaultChecked | boolean | – |
disabled | boolean | false |
render | ReactElement | (props, state) => ReactElement | <label> |
| Attribute | Description |
|---|---|
data-checked / data-unchecked | Whether the answer is picked. |
data-type | "radio" or "checkbox". |
data-shortcut | The answer's key. |
A free-text answer that sits with the choices. Typing clears the picked choice. Give it a label or aria-label.
| Prop | Type | Default |
|---|---|---|
variant | Button variant | "ghost", or "default" for Next and Submit |
size | Button size | "default" |
QuestionnaireNext and QuestionnaireSubmit share a slot, so the last question swaps Next for Submit without moving anything.
- ButtonButtons in every variant and size, with a built-in loading, success and error flow that skips the spinner for fast requests.
- InputA text input with three sizes, invalid and read-only states, native validation styling and a 16px touch font so phones never zoom in.
- KbdKey caps for shortcuts that show the right symbols on every platform, read them out properly and press down with the real keys.
- MotionThe easing curves, durations and reduced-motion check every component animates with, plus hooks for size morphs and sliding highlights.
- Number flowAnimated numbers where only the changed digits spin, with any Intl format and locale.
- CalendarA date grid for single, range and multiple selection, with sliding months, range previews and touch-sized days.
Used in Pro blocks
Blocks that build on Questionnaire.
Every block comes with HextaUI Pro, and Prompt Input is free.