Questionnaire

A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions.

1
"use client";
2

3
import type { SubmitEvent } from "react";
4
import { toast } from "sonner";
5

6
import {
7
  Questionnaire,
8
  QuestionnaireActions,
9
  QuestionnaireChoice,
10
  QuestionnaireChoices,
11
  QuestionnaireDescription,
12
  QuestionnaireError,
13
  QuestionnaireInput,
14
  QuestionnaireItem,
15
  QuestionnaireNext,
16
  QuestionnairePrevious,
17
  QuestionnaireProgress,
18
  QuestionnaireSkip,
19
  QuestionnaireSubmit,
20
  QuestionnaireTitle,
21
} from "@/components/ui/pxl/questionnaire";
22

23
const questionnaireItems = [
24
  {
25
    choices: [
26
      {
27
        description: "Show what the agent ran and what came back.",
28
        label: "Tool call timeline",
29
        value: "tool-calls",
30
      },
31
      {
32
        description: "Ask before sensitive or destructive actions.",
33
        label: "Approval checkpoints",
34
        value: "approvals",
35
      },
36
      {
37
        description: "Make delegated work and results easier to follow.",
38
        label: "Sub-agent handoffs",
39
        value: "handoffs",
40
      },
41
    ],
42
    description: "Choose a direction or describe another task.",
43
    input: {
44
      label: "Another agent feature",
45
      placeholder: "Describe another feature…",
46
    },
47
    name: "direction",
48
    required: true,
49
    title: "What should the agent build next?",
50
  },
51
  {
52
    choices: [
53
      { label: "Progress", value: "progress" },
54
      { label: "Decisions", value: "decisions" },
55
      { label: "Risks", value: "risks" },
56
      { label: "Next step", value: "next-step" },
57
    ],
58
    description: "Select all that apply, or skip this question.",
59
    multiple: true,
60
    name: "signals",
61
    required: false,
62
    title: "What should every progress update include?",
63
  },
64
  {
65
    choices: [
66
      { label: "Start now", value: "now" },
67
      { label: "Next development cycle", value: "next-cycle" },
68
      { label: "Add it to the backlog", value: "backlog" },
69
    ],
70
    description: "Choose when the agent should begin the work.",
71
    name: "timing",
72
    required: true,
73
    title: "When should work begin?",
74
  },
75
] as const;
76

77
export default function QuestionnaireDemo() {
78
  function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
79
    event.preventDefault();
80

81
    const formData = new FormData(event.currentTarget);
82
    const answers = {
83
      direction: formData.get("direction"),
84
      signals: formData.getAll("signals"),
85
      timing: formData.get("timing"),
86
    };
87

88
    toast("Agent plan saved", {
89
      description: `Direction: ${answers.direction ?? "None"} · Progress signals: ${answers.signals.join(", ") || "None"} · Timing: ${answers.timing ?? "None"}`,
90
    });
91
  }
92

93
  return (
94
    <Questionnaire
95
      className="mx-auto max-w-md"
96
      defaultItem="direction"
97
      items={questionnaireItems}
98
      shortcuts="letters"
99
      onSubmit={handleSubmit}
100
    >
101
      <QuestionnaireProgress />
102
      {questionnaireItems.map((question) => (
103
        <QuestionnaireItem
104
          key={question.name}
105
          multiple={"multiple" in question && question.multiple}
106
          name={question.name}
107
          required={question.required}
108
        >
109
          <QuestionnaireTitle>{question.title}</QuestionnaireTitle>
110
          <QuestionnaireDescription>
111
            {question.description}
112
          </QuestionnaireDescription>
113
          <QuestionnaireChoices>
114
            {question.choices.map((choice) => (
115
              <QuestionnaireChoice key={choice.value} value={choice.value}>
116
                <span className="font-medium">{choice.label}</span>
117
                {"description" in choice ? (
118
                  <span className="text-muted-foreground">
119
                    {choice.description}
120
                  </span>
121
                ) : null}
122
              </QuestionnaireChoice>
123
            ))}
124
            {"input" in question ? (
125
              <QuestionnaireInput
126
                aria-label={question.input.label}
127
                placeholder={question.input.placeholder}
128
              />
129
            ) : null}
130
          </QuestionnaireChoices>
131
          <QuestionnaireError />
132
        </QuestionnaireItem>
133
      ))}
134
      <QuestionnaireActions>
135
        <QuestionnairePrevious />
136
        <QuestionnaireSkip />
137
        <QuestionnaireNext>Next</QuestionnaireNext>
138
        <QuestionnaireSubmit>Save plan</QuestionnaireSubmit>
139
      </QuestionnaireActions>
140
    </Questionnaire>
141
  );
142
}

Installation

Command
Manual

pnpm dlx shadcn@latest add pxl-ui/registry/questionnaire

Install the following dependencies:

pnpm add @shadcn/react/questionnaire

Copy and paste the following code into your project.

1
import { Questionnaire as QuestionnairePrimitive } from "@shadcn/react/questionnaire";
2
import type { ComponentProps } from "react";
3

4
import { cn } from "@/lib/utils";
5
import { type Button, buttonVariants } from "@/ui/pxl/button";
6

7
import { inputWrapperVariants } from "./input";
8

9
function Questionnaire({
10
  className,
11
  ...props
12
}: ComponentProps<typeof QuestionnairePrimitive.Root>) {
13
  return (
14
    <QuestionnairePrimitive.Root
15
      data-slot="questionnaire"
16
      className={cn("flex w-full min-w-0 flex-col gap-4", className)}
17
      {...props}
18
    />
19
  );
20
}
21

22
function QuestionnaireProgress({
23
  className,
24
  ...props
25
}: ComponentProps<typeof QuestionnairePrimitive.Progress>) {
26
  return (
27
    <QuestionnairePrimitive.Progress
28
      data-slot="questionnaire-progress"
29
      className={cn(
30
        "min-h-lh w-fit min-w-[14ch] text-xs font-medium text-muted-foreground tabular-nums",
31
        className,
32
      )}
33
      {...props}
34
    />
35
  );
36
}
37

38
function QuestionnaireItem({
39
  className,
40
  ...props
41
}: ComponentProps<typeof QuestionnairePrimitive.Item>) {
42
  return (
43
    <QuestionnairePrimitive.Item
44
      data-slot="questionnaire-item"
45
      className={cn(
46
        "flex min-w-0 flex-col gap-4 border-0 p-0 outline-none",
47
        className,
48
      )}
49
      {...props}
50
    />
51
  );
52
}
53

54
function QuestionnaireTitle({
55
  className,
56
  ...props
57
}: ComponentProps<typeof QuestionnairePrimitive.Title>) {
58
  return (
59
    <QuestionnairePrimitive.Title
60
      data-slot="questionnaire-title"
61
      className={cn(
62
        "font-heading text-sm font-medium text-pretty [&:not(:has(~[data-slot=questionnaire-description]))]:mb-4",
63
        className,
64
      )}
65
      {...props}
66
    />
67
  );
68
}
69

70
function QuestionnaireDescription({
71
  className,
72
  ...props
73
}: ComponentProps<typeof QuestionnairePrimitive.Description>) {
74
  return (
75
    <QuestionnairePrimitive.Description
76
      data-slot="questionnaire-description"
77
      className={cn(
78
        "text-xs/relaxed text-pretty text-muted-foreground",
79
        className,
80
      )}
81
      {...props}
82
    />
83
  );
84
}
85

86
function QuestionnaireChoices({
87
  className,
88
  ...props
89
}: ComponentProps<typeof QuestionnairePrimitive.Choices>) {
90
  return (
91
    <QuestionnairePrimitive.Choices
92
      data-slot="questionnaire-choices"
93
      className={cn(
94
        "group/questionnaire-choices grid min-w-0 gap-2",
95
        className,
96
      )}
97
      {...props}
98
    />
99
  );
100
}
101

102
function QuestionnaireChoice({
103
  children,
104
  className,
105
  ...props
106
}: ComponentProps<typeof QuestionnairePrimitive.Choice>) {
107
  return (
108
    <QuestionnairePrimitive.Choice
109
      data-slot="questionnaire-choice"
110
      className={cn(
111
        "group/questionnaire-choice relative flex min-h-11 cursor-pointer items-start gap-2.5 rounded-none pixel-size-md pixel-border pixel-color-input bg-transparent px-3 py-2.5 text-start text-xs transition-colors outline-none select-none hover:bg-muted/50 has-[>input:focus-visible]:pixel-color-ring has-[>input:focus-visible]:ring-1 has-[>input:focus-visible]:ring-ring/50 data-invalid:pixel-color-destructive data-checked:pixel-color-foreground/30 data-checked:bg-muted",
112
        "data-disabled:pointer-events-none data-disabled:cursor-not-allowed data-disabled:opacity-50",
113
        className,
114
      )}
115
      {...props}
116
    >
117
      <QuestionnairePrimitive.ChoiceInput
118
        data-slot="questionnaire-choice-input"
119
        className="absolute inset-0 z-10 size-full cursor-pointer opacity-0"
120
      />
121
      <span
122
        aria-hidden="true"
123
        data-slot="questionnaire-choice-indicator"
124
        className="pointer-events-none relative flex size-4 shrink-0 translate-y-[--spacing(0.45)] items-center justify-center pixel-border pixel-color-input group-has-data-[slot=questionnaire-choice-description]/questionnaire-choice:translate-y-0.5 group-data-[type=radio]/questionnaire-choice:pixel-border group-data-checked/questionnaire-choice:pixel-color-primary-foreground group-data-checked/questionnaire-choice:bg-primary group-data-checked/questionnaire-choice:text-primary-foreground"
125
      >
126
        <span
127
          data-slot="questionnaire-choice-indicator-dot"
128
          className="hidden size-2 pixel-rounded bg-primary-foreground group-data-[type=checkbox]/questionnaire-choice:hidden group-data-checked/questionnaire-choice:block"
129
        />
130
        <svg
131
          data-slot="questionnaire-choice-indicator-check"
132
          className="hidden size-3.5 group-data-[type=radio]/questionnaire-choice:hidden group-data-checked/questionnaire-choice:block"
133
          xmlns="http://www.w3.org/2000/svg"
134
          fill="currentColor"
135
          viewBox="0 0 24 24"
136
        >
137
          <path d="M10 18H8v-2h2v2Zm-2-2H6v-2h2v2Zm4-2v2h-2v-2h2Zm-6 0H4v-2h2v2Zm8 0h-2v-2h2v2Zm2-2h-2v-2h2v2Zm2-2h-2V8h2v2Zm2-2h-2V6h2v2Z" />
138
        </svg>
139
      </span>
140
      <QuestionnairePrimitive.ChoiceLabel
141
        data-slot="questionnaire-choice-label"
142
        className="flex min-w-0 flex-1 flex-col gap-0.5 leading-snug"
143
      >
144
        {children}
145
      </QuestionnairePrimitive.ChoiceLabel>
146
      <QuestionnairePrimitive.ChoiceShortcut
147
        data-slot="questionnaire-choice-shortcut"
148
        className="pointer-events-none ms-auto hidden size-4 shrink-0 translate-y-[--spacing(0.45)] items-center justify-center rounded-none pixel-border pixel-size-sm pixel-color-input bg-background font-mono text-[0.625rem] leading-none font-medium text-muted-foreground group-has-data-[slot=questionnaire-choice-description]/questionnaire-choice:translate-y-0.5 group-data-shortcut/questionnaire-choice:inline-flex"
149
      />
150
    </QuestionnairePrimitive.Choice>
151
  );
152
}
153

154
function QuestionnaireChoiceDescription({
155
  className,
156
  ...props
157
}: ComponentProps<"span">) {
158
  return (
159
    <span
160
      data-slot="questionnaire-choice-description"
161
      className={cn("text-muted-foreground", className)}
162
      {...props}
163
    />
164
  );
165
}
166

167
function QuestionnaireInput({
168
  className,
169
  ...props
170
}: ComponentProps<typeof QuestionnairePrimitive.Input>) {
171
  return (
172
    <div
173
      data-slot="questionnaire-input-wrapper"
174
      className={cn(
175
        "group/questionnaire-input relative w-full min-w-0",
176
        inputWrapperVariants(),
177
      )}
178
    >
179
      <QuestionnairePrimitive.Input
180
        data-slot="questionnaire-input"
181
        className={cn(
182
          "h-8 min-h-11 w-full min-w-0 rounded-none bg-transparent px-2.5 py-1 text-xs transition-[color,box-shadow,background-color] outline-none focus-visible:pixel-color-ring focus-visible:ring-1 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:pixel-color-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 sm:min-h-0 md:text-xs dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:pixel-color-destructive/50 dark:aria-invalid:ring-destructive/40",
183
          "selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground",
184
          className,
185
        )}
186
        {...props}
187
      />
188
    </div>
189
  );
190
}
191

192
function QuestionnaireError({
193
  className,
194
  ...props
195
}: ComponentProps<typeof QuestionnairePrimitive.Error>) {
196
  return (
197
    <QuestionnairePrimitive.Error
198
      data-slot="questionnaire-error"
199
      className={cn("mt-2 text-xs text-destructive", className)}
200
      {...props}
201
    />
202
  );
203
}
204

205
function QuestionnaireActions({ className, ...props }: ComponentProps<"div">) {
206
  return (
207
    <div
208
      data-slot="questionnaire-actions"
209
      className={cn(
210
        "grid min-h-11 w-full grid-cols-[minmax(0,1fr)_auto_auto] items-center gap-1.5 sm:min-h-8",
211
        className,
212
      )}
213
      {...props}
214
    />
215
  );
216
}
217

218
function QuestionnairePrevious({
219
  children,
220
  className,
221
  size = "default",
222
  variant = "outline",
223
  ...props
224
}: ComponentProps<typeof QuestionnairePrimitive.Previous> &
225
  Pick<ComponentProps<typeof Button>, "size" | "variant">) {
226
  return (
227
    <QuestionnairePrimitive.Previous
228
      data-slot="questionnaire-previous"
229
      data-size={size}
230
      data-variant={variant}
231
      className={cn(
232
        buttonVariants({ size, variant }),
233
        "col-start-1 row-start-1 min-h-11 justify-self-start sm:min-h-0",
234
        className,
235
      )}
236
      {...props}
237
    >
238
      {children ?? "Previous"}
239
    </QuestionnairePrimitive.Previous>
240
  );
241
}
242

243
function QuestionnaireSkip({
244
  children,
245
  className,
246
  size = "default",
247
  variant = "outline",
248
  ...props
249
}: ComponentProps<typeof QuestionnairePrimitive.Skip> &
250
  Pick<ComponentProps<typeof Button>, "size" | "variant">) {
251
  return (
252
    <QuestionnairePrimitive.Skip
253
      data-slot="questionnaire-skip"
254
      data-size={size}
255
      data-variant={variant}
256
      className={cn(
257
        buttonVariants({ size, variant }),
258
        "col-start-2 row-start-1 min-h-11 justify-self-end sm:min-h-0",
259
        className,
260
      )}
261
      {...props}
262
    >
263
      {children ?? "Skip"}
264
    </QuestionnairePrimitive.Skip>
265
  );
266
}
267

268
function QuestionnaireNext({
269
  children,
270
  className,
271
  size = "default",
272
  variant = "default",
273
  ...props
274
}: ComponentProps<typeof QuestionnairePrimitive.Next> &
275
  Pick<ComponentProps<typeof Button>, "size" | "variant">) {
276
  return (
277
    <QuestionnairePrimitive.Next
278
      data-slot="questionnaire-next"
279
      data-size={size}
280
      data-variant={variant}
281
      className={cn(
282
        buttonVariants({ size, variant }),
283
        "col-start-3 row-start-1 min-h-11 justify-self-end sm:min-h-0",
284
        className,
285
      )}
286
      {...props}
287
    >
288
      {children ?? "Next"}
289
    </QuestionnairePrimitive.Next>
290
  );
291
}
292

293
function QuestionnaireSubmit({
294
  children,
295
  className,
296
  size = "default",
297
  variant = "default",
298
  ...props
299
}: ComponentProps<typeof QuestionnairePrimitive.Submit> &
300
  Pick<ComponentProps<typeof Button>, "size" | "variant">) {
301
  return (
302
    <QuestionnairePrimitive.Submit
303
      data-slot="questionnaire-submit"
304
      data-size={size}
305
      data-variant={variant}
306
      className={cn(
307
        buttonVariants({ size, variant }),
308
        "col-start-3 row-start-1 min-h-11 justify-self-end sm:min-h-0",
309
        className,
310
      )}
311
      {...props}
312
    >
313
      {children ?? "Submit"}
314
    </QuestionnairePrimitive.Submit>
315
  );
316
}
317

318
export {
319
  Questionnaire,
320
  QuestionnaireActions,
321
  QuestionnaireChoice,
322
  QuestionnaireChoiceDescription,
323
  QuestionnaireChoices,
324
  QuestionnaireDescription,
325
  QuestionnaireError,
326
  QuestionnaireInput,
327
  QuestionnaireItem,
328
  QuestionnaireNext,
329
  QuestionnairePrevious,
330
  QuestionnaireProgress,
331
  QuestionnaireSkip,
332
  QuestionnaireSubmit,
333
  QuestionnaireTitle,
334
};

Update the import paths to match your project setup.

Usage

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

const items = [
  {
    name: "direction",
    required: true,
    prompt: "What should we prototype next?",
    description: "Choose a direction or write your own.",
    choices: [
      {
        value: "delegation",
        label: "Delegation",
        description: "Show how work moves to a specialist.",
      },
      {
        value: "questions",
        label: "Question prompts",
        description: "Show choices while the interface waits.",
      },
      { value: "both", label: "Both together" },
    ],
    input: { label: "Another answer", placeholder: "Type another answer…" },
  },
  {
    name: "detail",
    required: false,
    prompt: "How much detail should it include?",
    description: "Skip this if you are not sure yet.",
    choices: [
      { value: "focused", label: "Focused" },
      { value: "complete", label: "Complete flow" },
    ],
  },
] as const

Define the collection once: pass it to Questionnaire for server-rendered progress, actions, and shortcuts, then map it into the parts.

<Questionnaire items={items} onSubmit={handleSubmit}>
  <QuestionnaireProgress />
  {items.map((question) => (
    <QuestionnaireItem
      key={question.name}
      name={question.name}
      required={question.required}
    >
      <QuestionnaireTitle>{question.prompt}</QuestionnaireTitle>
      <QuestionnaireDescription>
        {question.description}
      </QuestionnaireDescription>
      <QuestionnaireChoices>
        {question.choices.map((choice) => (
          <QuestionnaireChoice key={choice.value} value={choice.value}>
            <span className="font-medium">{choice.label}</span>
            {"description" in choice ? (
              <span className="text-muted-foreground">
                {choice.description}
              </span>
            ) : null}
          </QuestionnaireChoice>
        ))}
        {"input" in question ? (
          <QuestionnaireInput
            aria-label={question.input.label}
            placeholder={question.input.placeholder}
          />
        ) : null}
      </QuestionnaireChoices>
      <QuestionnaireError />
    </QuestionnaireItem>
  ))}
  <QuestionnaireActions>
    <QuestionnairePrevious />
    <QuestionnaireSkip />
    <QuestionnaireNext />
    <QuestionnaireSubmit />
  </QuestionnaireActions>
</Questionnaire>

function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault()
  const answers = new FormData(event.currentTarget)
  // answers.get("direction"), answers.getAll(...) for multiple items.
}

Composition

Questionnaire
├── QuestionnaireProgress
├── QuestionnaireItem
│   ├── QuestionnaireTitle
│   ├── QuestionnaireDescription
│   ├── QuestionnaireChoices
│   │   ├── QuestionnaireChoice
│   │   └── QuestionnaireInput
│   └── QuestionnaireError
└── QuestionnaireActions
    ├── QuestionnairePrevious
    ├── QuestionnaireSkip
    ├── QuestionnaireNext
    └── QuestionnaireSubmit

Questionnaire owns the ordered items, active item, answer state, validation, progress, and navigation. The containing page, card, dialog, or drawer owns close and cancellation behavior, persistence, transport, and branching.

Multiple Selection

Use multiple for an item that accepts more than one fixed answer.

Freeform Answer

Compose QuestionnaireInput with fixed choices when the user can provide another answer.

Explicit Skip

Add QuestionnaireSkip when an optional item may be intentionally left unanswered.

Shortcuts

Assign a letter or number key to each answer with shortcuts.

Custom Validation

Combine controlled navigation with an external schema such as Zod to return to an invalid item and present its error.

Controlled

Control the active item from host state, such as returning to an invalid step.

Accessibility

QuestionnaireItem renders a fieldset, and QuestionnaireTitle renders its legend. Descriptions and active errors are associated with the current item, and invalid items and answer controls expose aria-invalid.

Fixed choices preserve native radio and checkbox behavior. Progress is exposed as a named progressbar, navigation uses real buttons, and inactive items and actions are hidden and inert. Successful navigation focuses the newly active item; failed validation focuses an available answer control.

Always give QuestionnaireInput an accessible name with a visible label, aria-label, or aria-labelledby. A placeholder is not a label. See the Questionnaire accessibility guide for labeling custom compositions and the complete keyboard behavior.

Unstyled

The behavior in Questionnaire comes from the @shadcn/react package. To use it directly with your own markup and styles, see Questionnaire under @shadcn/react.

API Reference

The props, data attributes, and render states for every part are documented on the @shadcn/react Questionnaire page. The styled components inherit the corresponding unstyled props. Navigation components also accept Button size and variant props, and QuestionnaireActions is a styled-only layout helper.