Build accessible, multi-step questionnaires with single, multiple, freeform, and intentionally skipped answers.
<ui-questionnaire> is a form element for presenting one question at a time. It manages answers, progress, validation, and navigation.
It works well for agent clarification prompts, onboarding, surveys, intake forms, and configuration.
The parts are custom elements that apply the kit's classes, and a class written on any part is merged onto the element that part renders, so you restyle it by adding classes, or by editing the copy the CLI puts in your project. For the themed examples, see Questionnaire.
Installation
The elements ship in the Questionnaire component file. Adding it copies components/ui/questionnaire.ts into your project, together with the Button its navigation actions are styled with.
Install the following dependencies:
Copy and paste the following code into your project.
/**
* Questionnaire: a multi-step flow of questions over real form controls.
* Tier-2. It is shadcn's Questionnaire (the headless primitive in
* `@shadcn/react`, styled), built on a native `<form>`: each question is a
* `<fieldset>`, each answer a real radio, checkbox or text input, and the
* answers are read with `FormData` like any form.
*
* Without JavaScript every question shows at once and Submit posts the form,
* with the browser's own `required` check. With JavaScript one question shows
* at a time: Next validates it, Previous goes back, Skip leaves an optional
* question unanswered, and Submit appears on the last one.
*
* shadcn parity:
* Questionnaire (shortcuts) → <ui-questionnaire shortcuts="letters" | "numbers" action method>
* Questionnaire item / defaultItem
* → the `item` property and attribute (the active question,
* settable from outside) / `default-item`
* Questionnaire render={<form action={…} />}
* → <ui-questionnaire as-child> around your own <form>
* QuestionnaireProgress → <ui-questionnaire-progress> ("Question 1 of 3")
* QuestionnaireItem (name, required, multiple, disabled)
* → <ui-questionnaire-item name required multiple disabled>
* QuestionnaireTitle / Description
* → <ui-questionnaire-title> / <ui-questionnaire-description>
* QuestionnaireChoices → <ui-questionnaire-choices>
* QuestionnaireChoice value → <ui-questionnaire-choice value checked>
* QuestionnaireChoiceDescription
* → <ui-questionnaire-choice-description>
* QuestionnaireInput → <ui-questionnaire-input placeholder aria-label> (a freeform answer)
* QuestionnaireError → <ui-questionnaire-error> (a default message when empty)
* QuestionnaireActions / Previous / Skip / Next / Submit (disabled)
* → <ui-questionnaire-actions> / -previous / -skip / -next / -submit
* (`variant` and `size` as on a button, and `disabled`)
* onActiveItemChange → `ui-active-change` ({ detail: { name } })
*
* A question's answers share its `name`, so `FormData.get(name)` reads a
* single answer and `getAll(name)` a `multiple` one. Typing a freeform answer
* clears a single question's choices, and picking a choice clears the text.
* A `disabled` question is left out of the flow (a conditional question).
*
* The active question is the `item` property (and attribute): set it from
* outside to go to that question, and it follows the reader's own steps.
* `default-item` names the question the flow opens on. A navigation button
* written `disabled` cannot be pressed, and a disabled Next or Submit also
* stops Enter from stepping on, as in shadcn.
*
* To bind a `'use server'` action, write the form yourself, the way a page
* binds any action, and mark the questionnaire `as-child`:
* `<ui-questionnaire as-child><form action=${saveAnswers} data-slot="questionnaire"
* class=${questionnaireClass()}> ...questions and actions... </form></ui-questionnaire>`.
* The element then renders no form of its own and drives yours, so the page's
* binding (its hidden action field, `method="post"`) is served and kept, and
* the form posts with JavaScript off. Without `as-child` the element renders
* the form, with your `action` and `method` attributes as plain strings.
*
* Keyboard: Enter goes to the next question, and on the last one submits.
* With `shortcuts`, a letter (A, B, C) or a number (1, 2, 3) picks the
* matching answer, except while typing in a text field.
*
* A11y (handled by the element): each question is a `<fieldset>` named by its
* title and described by its description, the progress is a
* `role="progressbar"` with its value, a question left unanswered is marked
* `aria-invalid` and its error announced with `role="alert"`, and a question
* not on screen is `hidden` and `inert`.
*
* @example
* ```html
* <ui-questionnaire shortcuts="letters">
* <ui-questionnaire-progress></ui-questionnaire-progress>
* <ui-questionnaire-item name="direction" required>
* <ui-questionnaire-title>What should we prototype next?</ui-questionnaire-title>
* <ui-questionnaire-description>Choose a direction or write your own.</ui-questionnaire-description>
* <ui-questionnaire-choices>
* <ui-questionnaire-choice value="delegation">Delegation</ui-questionnaire-choice>
* <ui-questionnaire-choice value="questions">Question prompts</ui-questionnaire-choice>
* <ui-questionnaire-input aria-label="Another answer" placeholder="Type another answer"></ui-questionnaire-input>
* </ui-questionnaire-choices>
* <ui-questionnaire-error></ui-questionnaire-error>
* </ui-questionnaire-item>
* <ui-questionnaire-item name="detail">
* <ui-questionnaire-title>How much detail?</ui-questionnaire-title>
* <ui-questionnaire-choices>
* <ui-questionnaire-choice value="focused">Focused</ui-questionnaire-choice>
* <ui-questionnaire-choice value="complete">Complete flow</ui-questionnaire-choice>
* </ui-questionnaire-choices>
* </ui-questionnaire-item>
* <ui-questionnaire-actions>
* <ui-questionnaire-previous></ui-questionnaire-previous>
* <ui-questionnaire-skip></ui-questionnaire-skip>
* <ui-questionnaire-next></ui-questionnaire-next>
* <ui-questionnaire-submit></ui-questionnaire-submit>
* </ui-questionnaire-actions>
* </ui-questionnaire>
* ```
*/
import { WebComponent, html, prop, signal, nothing } from '@webjsdev/core';
import { cn, takeAuthoredClass } from '../lib/utils.ts';
import { buttonClass, type ButtonVariant, type ButtonSize } from './button.ts';
/** The form's classes (the element applies them). */
export const questionnaireClass = (): string => 'gap-4 flex w-full min-w-0 flex-col';
/** The progress line (the element applies them). */
export const questionnaireProgressClass = (): string =>
'text-xs min-h-[1lh] w-fit min-w-[14ch] font-medium text-muted-foreground tabular-nums';
/** A question's fieldset (the element applies them). */
export const questionnaireItemClass = (): string => 'flex flex-col gap-4 min-w-0 border-0 p-0 outline-none';
/** A question's title (the element applies them). */
// The styles space the title from what follows only when no description is its
// following sibling. Here the title and the description sit in their own part
// hosts, so they are never siblings, and the question is asked of the item
// instead: an item holding a description takes the margin back.
export const questionnaireTitleClass = (): string =>
'text-base leading-snug font-medium cn-font-heading text-pretty [[data-slot=questionnaire-item]:has([data-slot=questionnaire-description])_&]:mb-0';
/** A question's description (the element applies them). */
export const questionnaireDescriptionClass = (): string =>
'text-sm text-muted-foreground text-pretty';
/** The answers' box (the element applies them). */
export const questionnaireChoicesClass = (): string =>
'gap-2 group/questionnaire-choices grid min-w-0';
/** One answer (the element applies them). */
export const questionnaireChoiceClass = (): string =>
'gap-2.5 rounded-md border border-input bg-transparent px-3 py-2.5 text-sm shadow-xs hover:bg-muted/50 data-[checked]:border-primary/40 data-[checked]:bg-muted has-[>input:focus-visible]:border-ring has-[>input:focus-visible]:ring-[3px] has-[>input:focus-visible]:ring-ring/50 dark:bg-input/20 dark:data-[checked]:bg-muted group/questionnaire-choice relative flex min-h-11 cursor-pointer items-start text-start transition-colors outline-none select-none data-[disabled]:pointer-events-none data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50';
/** An answer's description line. */
export const questionnaireChoiceDescriptionClass = (): string => 'text-muted-foreground';
/** The freeform answer (the element applies them). */
export const questionnaireInputClass = (): string =>
'h-9 rounded-md border border-input bg-transparent px-3 py-1 text-base shadow-xs focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 min-h-11 w-full min-w-0 transition-[color,box-shadow,background-color] outline-none disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 sm:min-h-0 selection:bg-primary selection:text-primary-foreground placeholder:text-muted-foreground';
/** The error line (the element applies them). */
export const questionnaireErrorClass = (): string => 'mt-2 text-sm text-destructive';
/** The actions row (the element applies them). */
export const questionnaireActionsClass = (): string =>
'gap-2 sm:min-h-9 grid min-h-11 w-full grid-cols-[minmax(0,1fr)_auto_auto] items-center';
const ROOT = 'ui-questionnaire';
const ITEM = 'ui-questionnaire-item';
let uid = 0;
function rootOf(el: Element): UiQuestionnaire | null {
return (typeof el.closest === 'function' ? el.closest(ROOT) : null) as UiQuestionnaire | null;
}
function itemOf(el: Element): UiQuestionnaireItem | null {
return (typeof el.closest === 'function' ? el.closest(ITEM) : null) as UiQuestionnaireItem | null;
}
// shadcn's className on each questionnaire part lands on the element that part
// renders, and no host draws a box of its own: the rendered elements are the
// flex and grid items the styles space (a hidden question's fieldset drops out
// of the form's gap, a button's column placement reaches the actions grid).
// No host hides itself, since every part hides its rendered element. The
// host's box is turned off through its style, which the server serves, unlike
// a class the element changes.
function takeAuthored(part: HTMLElement): string | null {
if (!part.getAttribute?.('style')) part.setAttribute?.('style', 'display: contents');
return takeAuthoredClass(part, null);
}
// A part connected after the root's first update asks it to push its state.
function announce(el: Element): void {
const root = rootOf(el);
if (root) root._partConnected();
}
function isTextEntry(target: EventTarget | null): boolean {
const el = target as HTMLElement | null;
if (!el || typeof el.matches !== 'function') return false;
return el.matches('textarea, input:not([type=radio]):not([type=checkbox]):not([type=button]):not([type=submit])');
}
// --------------------------------------------------------------------------
// <ui-questionnaire>
// --------------------------------------------------------------------------
export class UiQuestionnaire extends WebComponent({
action: String,
method: String,
shortcuts: prop<'' | 'letters' | 'numbers'>(String),
// The active question, by name: set it to go there.
item: String,
// The question the flow opens on.
defaultItem: prop(String, { attribute: 'default-item' }),
// Drive the author's own <form> instead of rendering one.
asChild: prop(Boolean, { attribute: 'as-child' }),
}) {
readonly #enhanced = signal(false);
readonly #active = signal('');
_queued = false;
constructor() {
super();
this.action = '';
this.method = '';
this.shortcuts = '';
this.item = '';
this.defaultItem = '';
this.asChild = false;
}
// The listeners sit on the host, which every event from the form reaches,
// so they serve the element's own form and an author's `as-child` one alike.
connectedCallback(): void {
super.connectedCallback?.();
this.addEventListener('submit', this._onSubmit);
this.addEventListener('keydown', this._onKeyDown);
this.addEventListener('change', this._onChange);
this.addEventListener('input', this._onChange);
this._partConnected();
}
disconnectedCallback(): void {
this.removeEventListener('submit', this._onSubmit);
this.removeEventListener('keydown', this._onKeyDown);
this.removeEventListener('change', this._onChange);
this.removeEventListener('input', this._onChange);
super.disconnectedCallback?.();
}
render() {
if (this.asChild) {
// The author's form is the questionnaire; this host only drives it.
if (typeof this.getAttribute === 'function' && !this.getAttribute('style')) this.setAttribute('style', 'display: contents');
return html`<slot></slot>`;
}
return html`<form
data-slot="questionnaire"
action=${this.action || nothing}
method=${this.method || nothing}
?novalidate=${this.#enhanced.get()}
data-shortcuts=${this.shortcuts || nothing}
class=${cn(questionnaireClass(), takeAuthored(this))}
><slot></slot></form>`;
}
/** The form the questionnaire runs on: its own, or the author's under `as-child`. */
form(): HTMLFormElement | null {
if (typeof this.querySelector !== 'function') return null;
return this.querySelector('form');
}
willUpdate(changedProperties: Map<string, unknown>): void {
super.willUpdate?.(changedProperties);
// The active question set from outside: go there, with no validation, as
// a controlled shadcn Questionnaire does.
if (changedProperties.has('item') && this.#enhanced.get() && this.item && this.item !== this.#active.get()) {
const target = this.items().find((i) => i.name === this.item);
if (target) queueMicrotask(() => this._go(target, { focus: false }));
}
}
_partConnected(): void {
if (this._queued) return;
this._queued = true;
queueMicrotask(() => {
this._queued = false;
this._enhance();
this.sync();
});
}
_enhance(): void {
if (this.#enhanced.get()) return;
const items = this.items();
const wanted = this.item || this.defaultItem;
const first = items.find((i) => i.name === wanted) ?? items[0];
if (!first) return;
this.#active.set(first.name);
this.item = first.name;
this.#enhanced.set(true);
// An author's form validates per question from here, as the element's own does.
if (this.asChild) {
const form = this.form();
if (form) {
form.noValidate = true;
if (this.shortcuts) form.setAttribute('data-shortcuts', this.shortcuts);
}
}
}
/** The questions in the flow, in order: every one not `disabled`. */
items(): UiQuestionnaireItem[] {
if (typeof this.querySelectorAll !== 'function') return [];
return Array.from(this.querySelectorAll<UiQuestionnaireItem>(ITEM)).filter((i) => rootOf(i) === this && !i.disabled);
}
_activeItem(): UiQuestionnaireItem | null {
const items = this.items();
return items.find((i) => i.name === this.#active.get()) ?? items[0] ?? null;
}
/** Whether a question has an answer: a checked choice or a filled text field. */
answered(item: UiQuestionnaireItem): boolean {
return item.inputs().some((i) => (i.type === 'radio' || i.type === 'checkbox' ? i.checked : i.value.trim() !== ''));
}
/** Push the active question, its neighbours and every answer into the parts. */
sync(): void {
const items = this.items();
const item = this._activeItem();
const at = item ? items.indexOf(item) : -1;
const last = at === items.length - 1;
for (const i of this._all(ITEM) as UiQuestionnaireItem[]) {
i.flow?.set({ enhanced: this.#enhanced.get(), active: i === item });
}
for (const c of this._all('ui-questionnaire-choice') as UiQuestionnaireChoice[]) c._syncChecked();
for (const p of this._all('ui-questionnaire-progress') as UiQuestionnaireProgress[]) {
p.progress?.set({ current: at + 1, total: items.length });
}
const show = (tag: string, visible: boolean) => {
for (const b of this._all(tag) as UiQuestionnaireButton[]) b.visible?.set(visible);
};
if (!this.#enhanced.get()) {
show('ui-questionnaire-previous', false);
show('ui-questionnaire-skip', false);
show('ui-questionnaire-next', false);
show('ui-questionnaire-submit', true);
return;
}
show('ui-questionnaire-previous', at > 0);
show('ui-questionnaire-skip', !!item && !item.required);
show('ui-questionnaire-next', items.length > 1 && !last);
show('ui-questionnaire-submit', items.length > 0 && last);
}
_all(tag: string): Element[] {
if (typeof this.querySelectorAll !== 'function') return [];
return Array.from(this.querySelectorAll(tag)).filter((el) => rootOf(el) === this);
}
_go(item: UiQuestionnaireItem | undefined, opts: { focus?: boolean } = {}): void {
if (!item) return;
if (item.name !== this.#active.get()) {
this.#active.set(item.name);
this.item = item.name;
this.dispatchEvent(new CustomEvent('ui-active-change', { bubbles: true, detail: { name: item.name } }));
}
this.sync();
// Focus the new question's first answer once it is shown.
if (opts.focus === false) return;
this.updateComplete.then(() => requestAnimationFrame(() => item.inputs().find((i) => !i.disabled)?.focus()));
}
// Whether every button of a kind is written `disabled` (and there is one).
_allDisabled(tag: string): boolean {
const buttons = this._all(tag) as UiQuestionnaireButton[];
return buttons.length > 0 && buttons.every((b) => b.disabled);
}
/** Check the active question; mark it and return false when it needs an answer. */
validate(item = this._activeItem()): boolean {
if (!item) return true;
const ok = !item.required || this.answered(item);
item.invalid?.set(!ok);
if (!ok) item.inputs().find((i) => !i.disabled)?.focus();
return ok;
}
/** Go to the next question, if the active one is answered or optional. */
next(): void {
const items = this.items();
const item = this._activeItem();
if (!item || !this.validate(item)) return;
this._go(items[items.indexOf(item) + 1]);
}
/** Go back one question. */
previous(): void {
const items = this.items();
const item = this._activeItem();
if (!item) return;
this._go(items[items.indexOf(item) - 1]);
}
/** Leave an optional question unanswered and go on. */
skip(): void {
const item = this._activeItem();
if (!item || item.required) return;
for (const i of item.inputs()) {
if (i.type === 'radio' || i.type === 'checkbox') i.checked = false;
else i.value = '';
}
item.invalid?.set(false);
const items = this.items();
const after = items[items.indexOf(item) + 1];
if (after) this._go(after);
else this.sync();
}
// Enter in the form, and the Submit button, both arrive here.
_onSubmit = (e: Event): void => {
if (!this.#enhanced.get() || (e.target as Element | null)?.closest?.(ROOT) !== this) return;
const items = this.items();
const item = this._activeItem();
if (item && items.indexOf(item) < items.length - 1) {
e.preventDefault();
// Enter steps on only while Next can be pressed.
if (!this._allDisabled('ui-questionnaire-next')) this.next();
return;
}
// On the last question every required one must be answered.
const missing = items.find((i) => i.required && !this.answered(i));
if (missing) {
e.preventDefault();
if (missing !== item) this._go(missing);
this.validate(missing);
}
};
_onKeyDown = (e: KeyboardEvent): void => {
if (!this.#enhanced.get() || !this.shortcuts || rootOf(e.target as Element) !== this || e.metaKey || e.ctrlKey || e.altKey || isTextEntry(e.target)) return;
const item = this._activeItem();
if (!item) return;
const choices = item.choices();
const k = e.key.toLowerCase();
const index = this.shortcuts === 'numbers' ? Number(k) - 1 : k.length === 1 ? k.charCodeAt(0) - 97 : -1;
const choice = Number.isInteger(index) && index >= 0 ? choices[index] : undefined;
const input = choice?.input();
if (!input || input.disabled) return;
e.preventDefault();
input.checked = input.type === 'checkbox' ? !input.checked : true;
input.dispatchEvent(new Event('change', { bubbles: true }));
};
// A pick or a keystroke: keep a single question's choices and text apart,
// clear its error once it is answered, and redraw.
_onChange = (e: Event): void => {
const target = e.target as HTMLInputElement;
const item = itemOf(target);
if (!item || rootOf(item) !== this) return;
if (!item.multiple) {
if (target.matches?.('[data-slot="questionnaire-input"]') && target.value.trim()) {
for (const i of item.inputs()) if (i.type === 'radio') i.checked = false;
} else if (target.type === 'radio' && target.checked) {
for (const i of item.inputs()) if (i.matches('[data-slot="questionnaire-input"]')) i.value = '';
}
}
if (item.invalid?.get() && this.answered(item)) item.invalid?.set(false);
this.sync();
};
}
UiQuestionnaire.register('ui-questionnaire');
// --------------------------------------------------------------------------
// <ui-questionnaire-progress>
// --------------------------------------------------------------------------
export class UiQuestionnaireProgress extends WebComponent {
readonly progress = signal<{ current: number; total: number }>({ current: 0, total: 0 });
constructor() {
super();
}
connectedCallback(): void {
super.connectedCallback?.();
announce(this);
}
render() {
const { current, total } = this.progress.get();
const label = total ? `Question ${current} of ${total}` : '';
return html`<div
data-slot="questionnaire-progress"
role="progressbar"
aria-label="Questionnaire progress"
aria-live="polite"
aria-valuemin=${total ? '1' : nothing}
aria-valuemax=${total ? String(total) : nothing}
aria-valuenow=${total ? String(current) : nothing}
aria-valuetext=${label || nothing}
class=${cn(questionnaireProgressClass(), takeAuthored(this))}
>${label}</div>`;
}
}
UiQuestionnaireProgress.register('ui-questionnaire-progress');
// --------------------------------------------------------------------------
// <ui-questionnaire-item>
// --------------------------------------------------------------------------
export class UiQuestionnaireItem extends WebComponent({
name: String,
required: Boolean,
multiple: Boolean,
disabled: Boolean,
}) {
readonly flow = signal<{ enhanced: boolean; active: boolean }>({ enhanced: false, active: false });
// The item's error line reads this signal, so it redraws when it changes.
readonly invalid = signal(false);
_id = '';
constructor() {
super();
this.name = '';
this.required = false;
this.multiple = false;
this.disabled = false;
}
connectedCallback(): void {
super.connectedCallback?.();
this._id ||= `ui-questionnaire-item-${++uid}`;
announce(this);
}
get titleId(): string {
return `${this._id}-title`;
}
get descriptionId(): string {
return `${this._id}-description`;
}
get errorId(): string {
return `${this._id}-error`;
}
/** The question's answer controls: its choices' inputs and its text field. */
inputs(): HTMLInputElement[] {
if (typeof this.querySelectorAll !== 'function') return [];
return Array.from(this.querySelectorAll<HTMLInputElement>('input[data-slot="questionnaire-choice-input"], input[data-slot="questionnaire-input"]'))
.filter((i) => itemOf(i) === this);
}
/** The question's choices, in order. */
choices(): UiQuestionnaireChoice[] {
if (typeof this.querySelectorAll !== 'function') return [];
return Array.from(this.querySelectorAll<UiQuestionnaireChoice>('ui-questionnaire-choice')).filter((c) => itemOf(c) === this);
}
/** Whether the item holds a `tag` part, or false on the server, where there is no DOM to query. */
_has(tag: string): boolean {
return typeof this.querySelector === 'function' && !!this.querySelector(tag);
}
render() {
const flow = this.flow.get();
const hide = flow.enhanced && !flow.active;
const hasTitle = this._has('ui-questionnaire-title');
const hasDescription = this._has('ui-questionnaire-description');
const described = [hasDescription ? this.descriptionId : '', this.invalid.get() ? this.errorId : ''].filter(Boolean).join(' ');
return html`<fieldset
data-slot="questionnaire-item"
?disabled=${this.disabled}
?data-active=${flow.active}
?hidden=${hide}
?inert=${hide}
aria-labelledby=${hasTitle && this._id ? this.titleId : nothing}
aria-describedby=${described || nothing}
aria-invalid=${this.invalid.get() ? 'true' : nothing}
class=${cn(questionnaireItemClass(), takeAuthored(this))}
><slot></slot></fieldset>`;
}
}
UiQuestionnaireItem.register('ui-questionnaire-item');
// --------------------------------------------------------------------------
// <ui-questionnaire-title> and <ui-questionnaire-description>
// --------------------------------------------------------------------------
export class UiQuestionnaireTitle extends WebComponent {
connectedCallback(): void {
super.connectedCallback?.();
announce(this);
}
render() {
const item = itemOf(this);
return html`<legend data-slot="questionnaire-title" id=${item?._id ? item.titleId : nothing} class=${cn(questionnaireTitleClass(), takeAuthored(this))}><slot></slot></legend>`;
}
}
UiQuestionnaireTitle.register('ui-questionnaire-title');
export class UiQuestionnaireDescription extends WebComponent {
connectedCallback(): void {
super.connectedCallback?.();
announce(this);
}
render() {
const item = itemOf(this);
return html`<p data-slot="questionnaire-description" id=${item?._id ? item.descriptionId : nothing} class=${cn(questionnaireDescriptionClass(), takeAuthored(this))}><slot></slot></p>`;
}
}
UiQuestionnaireDescription.register('ui-questionnaire-description');
// --------------------------------------------------------------------------
// <ui-questionnaire-choices>, <ui-questionnaire-choice>, -choice-description
// --------------------------------------------------------------------------
export class UiQuestionnaireChoices extends WebComponent {
render() {
return html`<div data-slot="questionnaire-choices" class=${cn(questionnaireChoicesClass(), takeAuthored(this))}><slot></slot></div>`;
}
}
UiQuestionnaireChoices.register('ui-questionnaire-choices');
export class UiQuestionnaireChoice extends WebComponent({
value: String,
checked: Boolean,
disabled: Boolean,
}) {
readonly #live = signal(false);
#seeded = false;
constructor() {
super();
this.value = '';
this.checked = false;
this.disabled = false;
}
// Seed the drawn state from `checked` here, not in connectedCallback: SSR
// runs willUpdate but never connects, and a pre-checked choice has to be
// drawn checked in the first paint and with JavaScript off.
willUpdate(changedProperties: Map<string, unknown>): void {
super.willUpdate?.(changedProperties);
if (!this.#seeded || changedProperties.has('checked')) {
this.#seeded = true;
this.#live.set(this.checked);
}
}
connectedCallback(): void {
super.connectedCallback?.();
announce(this);
}
input(): HTMLInputElement | null {
return this.querySelector?.('input[data-slot="questionnaire-choice-input"]') ?? null;
}
_syncChecked(): void {
const on = !!this.input()?.checked;
if (on !== this.#live.get()) this.#live.set(on);
this.requestUpdate?.();
}
// This choice's shortcut key, from its place in the question.
_shortcut(): string {
const mode = rootOf(this)?.shortcuts;
const item = itemOf(this);
if (!mode || !item) return '';
const i = item.choices().indexOf(this);
if (i < 0) return '';
if (mode === 'numbers') return i < 9 ? String(i + 1) : '';
return i < 26 ? String.fromCharCode(97 + i) : '';
}
render() {
const item = itemOf(this);
const type = item?.multiple ? 'checkbox' : 'radio';
const shortcut = this._shortcut();
const disabled = this.disabled || !!item?.disabled;
return html`<label
data-slot="questionnaire-choice"
data-type=${type}
?data-checked=${this.#live.get()}
?data-unchecked=${!this.#live.get()}
?data-disabled=${disabled}
data-shortcut=${shortcut || nothing}
class=${cn(questionnaireChoiceClass(), takeAuthored(this))}
><input
data-slot="questionnaire-choice-input"
type=${type}
name=${item?.name || nothing}
value=${this.value}
?checked=${this.checked}
?disabled=${disabled}
?required=${!!item?.required && type === 'radio'}
aria-keyshortcuts=${shortcut ? shortcut.toUpperCase() : nothing}
class="absolute inset-0 z-10 size-full cursor-pointer opacity-0"
><span aria-hidden="true" data-slot="questionnaire-choice-indicator"
class="size-4 translate-y-[--spacing(0.45)] rounded-[4px] border-input shadow-xs group-data-[checked]/questionnaire-choice:border-primary group-data-[checked]/questionnaire-choice:bg-primary group-data-[checked]/questionnaire-choice:text-primary-foreground dark:bg-input/30 pointer-events-none relative flex shrink-0 items-center justify-center border group-data-[type=radio]/questionnaire-choice:rounded-full"
><span data-slot="questionnaire-choice-indicator-dot"
class="size-2 bg-primary-foreground hidden rounded-full group-data-[type=checkbox]/questionnaire-choice:hidden group-data-[checked]/questionnaire-choice:block"
></span><svg data-slot="questionnaire-choice-indicator-check" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
class="size-3.5 hidden group-data-[type=radio]/questionnaire-choice:hidden group-data-[checked]/questionnaire-choice:block"
><path d="M20 6 9 17l-5-5"></path></svg></span><span data-slot="questionnaire-choice-label"
class="gap-0.5 flex min-w-0 flex-1 flex-col leading-snug"
><slot></slot></span><span data-slot="questionnaire-choice-shortcut" aria-hidden="true" ?hidden=${!shortcut}
class="size-5 translate-y-[--spacing(0.45)] items-center justify-center rounded-md border border-input bg-background font-mono text-[0.625rem] leading-none font-medium text-muted-foreground pointer-events-none ms-auto hidden shrink-0 group-data-[shortcut]/questionnaire-choice:inline-flex"
>${shortcut.toUpperCase()}</span></label>`;
}
}
UiQuestionnaireChoice.register('ui-questionnaire-choice');
export class UiQuestionnaireChoiceDescription extends WebComponent {
render() {
return html`<span data-slot="questionnaire-choice-description" class=${cn(questionnaireChoiceDescriptionClass(), takeAuthored(this))}><slot></slot></span>`;
}
}
UiQuestionnaireChoiceDescription.register('ui-questionnaire-choice-description');
// --------------------------------------------------------------------------
// <ui-questionnaire-input>
// --------------------------------------------------------------------------
export class UiQuestionnaireInput extends WebComponent({
placeholder: String,
}) {
constructor() {
super();
this.placeholder = '';
}
connectedCallback(): void {
super.connectedCallback?.();
announce(this);
}
render() {
const item = itemOf(this);
return html`<div data-slot="questionnaire-input-wrapper" class=${cn('w-full group/questionnaire-input relative min-w-0', takeAuthored(this))}><input
data-slot="questionnaire-input"
type="text"
name=${item?.name || nothing}
placeholder=${this.placeholder || nothing}
aria-label=${this.getAttribute?.('aria-label') || nothing}
?disabled=${!!item?.disabled}
class=${questionnaireInputClass()}
></div>`;
}
}
UiQuestionnaireInput.register('ui-questionnaire-input');
// --------------------------------------------------------------------------
// <ui-questionnaire-error>
// --------------------------------------------------------------------------
export class UiQuestionnaireError extends WebComponent {
connectedCallback(): void {
super.connectedCallback?.();
announce(this);
}
render() {
const item = itemOf(this);
const invalid = !!item?.invalid?.get();
const fallback = item?.required ? 'Choose an answer to continue.' : 'Choose an answer or skip this question.';
return html`<p
data-slot="questionnaire-error"
id=${item?._id ? item.errorId : nothing}
?hidden=${!invalid}
role=${invalid ? 'alert' : nothing}
class=${cn(questionnaireErrorClass(), takeAuthored(this))}
><slot>${fallback}</slot></p>`;
}
}
UiQuestionnaireError.register('ui-questionnaire-error');
// --------------------------------------------------------------------------
// <ui-questionnaire-actions> and the four buttons
// --------------------------------------------------------------------------
export class UiQuestionnaireActions extends WebComponent {
render() {
return html`<div data-slot="questionnaire-actions" class=${cn(questionnaireActionsClass(), takeAuthored(this))}><slot></slot></div>`;
}
}
UiQuestionnaireActions.register('ui-questionnaire-actions');
/** What the four navigation buttons share. */
export class UiQuestionnaireButton extends WebComponent({
variant: String,
size: String,
// Written by the author, as shadcn's `disabled` on a navigation button.
disabled: Boolean,
}) {
static part = '';
static label = '';
static place = '';
static submits = false;
static defaultVariant = 'outline';
// Submit shows from the first paint; the others wait for the flow.
readonly visible = signal((this.constructor as typeof UiQuestionnaireButton).submits);
constructor() {
super();
const ctor = this.constructor as typeof UiQuestionnaireButton;
this.variant = ctor.defaultVariant;
this.size = 'default';
this.disabled = false;
}
connectedCallback(): void {
super.connectedCallback?.();
announce(this);
}
render() {
const ctor = this.constructor as typeof UiQuestionnaireButton;
return html`<button
type=${ctor.submits ? 'submit' : 'button'}
data-slot=${`questionnaire-${ctor.part}`}
data-size=${this.size}
data-variant=${this.variant}
?hidden=${!this.visible.get()}
?disabled=${this.disabled}
aria-hidden=${this.visible.get() ? nothing : 'true'}
aria-keyshortcuts=${this.visible.get() && !this.disabled && (ctor.part === 'next' || ctor.part === 'submit') ? 'Enter' : nothing}
class=${cn(buttonClass({ variant: this.variant as ButtonVariant, size: this.size as ButtonSize }), ctor.place, takeAuthored(this))}
@click=${this._onClick}
><slot>${ctor.label}</slot></button>`;
}
_onClick = (): void => {};
}
export class UiQuestionnairePrevious extends UiQuestionnaireButton {
static part = 'previous';
static label = 'Previous';
static place = 'col-start-1 row-start-1 min-h-11 justify-self-start sm:min-h-0';
_onClick = (): void => rootOf(this)?.previous();
}
UiQuestionnairePrevious.register('ui-questionnaire-previous');
export class UiQuestionnaireSkip extends UiQuestionnaireButton {
static part = 'skip';
static label = 'Skip';
static place = 'col-start-2 row-start-1 min-h-11 justify-self-end sm:min-h-0';
_onClick = (): void => rootOf(this)?.skip();
}
UiQuestionnaireSkip.register('ui-questionnaire-skip');
export class UiQuestionnaireNext extends UiQuestionnaireButton {
static part = 'next';
static label = 'Next';
static place = 'col-start-3 row-start-1 min-h-11 justify-self-end sm:min-h-0';
static defaultVariant = 'default';
_onClick = (): void => rootOf(this)?.next();
}
UiQuestionnaireNext.register('ui-questionnaire-next');
export class UiQuestionnaireSubmit extends UiQuestionnaireButton {
static part = 'submit';
static label = 'Submit';
static place = 'col-start-3 row-start-1 min-h-11 justify-self-end sm:min-h-0';
static submits = true;
static defaultVariant = 'default';
}
UiQuestionnaireSubmit.register('ui-questionnaire-submit');
Update the import paths to match your project setup.
Import
import '#components/ui/questionnaire.ts';
Importing the file registers every part as its own element. Each part takes the attributes listed in the API Reference, plus a class that is merged onto the element it renders.
Anatomy
<ui-questionnaire>
<ui-questionnaire-progress></ui-questionnaire-progress>
<ui-questionnaire-item name="question">
<ui-questionnaire-title></ui-questionnaire-title>
<ui-questionnaire-description></ui-questionnaire-description>
<ui-questionnaire-choices>
<ui-questionnaire-choice value="answer">
Label
<ui-questionnaire-choice-description></ui-questionnaire-choice-description>
</ui-questionnaire-choice>
<ui-questionnaire-input></ui-questionnaire-input>
</ui-questionnaire-choices>
<ui-questionnaire-error></ui-questionnaire-error>
</ui-questionnaire-item>
<ui-questionnaire-actions>
<ui-questionnaire-previous></ui-questionnaire-previous>
<ui-questionnaire-skip></ui-questionnaire-skip>
<ui-questionnaire-next></ui-questionnaire-next>
<ui-questionnaire-submit></ui-questionnaire-submit>
</ui-questionnaire-actions>
</ui-questionnaire>
<ui-questionnaire> renders a form. Each <ui-questionnaire-item> renders a fieldset, and its <ui-questionnaire-title> renders the legend. <ui-questionnaire-choice> renders a label around a native radio or checkbox, the indicator and the shortcut hint, all from one element.
Styled version
The kit has one version, and it is styled. Its parts are these elements:
Basic usage
Each item is one step. Its name identifies the step and becomes the form field name for its answers. A choice's value is the submitted answer.
type Question = {
name: string;
required: boolean;
prompt: string;
description: string;
choices: { value: string; label: string; description?: string }[];
input?: { label: string; placeholder: string };
};
const items: Question[] = [
{
name: 'prototype',
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' },
],
},
];
html`
<ui-questionnaire>
<ui-questionnaire-progress></ui-questionnaire-progress>
${items.map((question) => html`
<ui-questionnaire-item name=${question.name} ?required=${question.required}>
<ui-questionnaire-title>${question.prompt}</ui-questionnaire-title>
<ui-questionnaire-description>${question.description}</ui-questionnaire-description>
<ui-questionnaire-choices>
${question.choices.map((choice) => html`
<ui-questionnaire-choice value=${choice.value}>
${choice.label}
${choice.description
? html`<ui-questionnaire-choice-description>${choice.description}</ui-questionnaire-choice-description>`
: ''}
</ui-questionnaire-choice>
`)}
${question.input
? html`<ui-questionnaire-input aria-label=${question.input.label} placeholder=${question.input.placeholder}></ui-questionnaire-input>`
: ''}
</ui-questionnaire-choices>
<ui-questionnaire-error></ui-questionnaire-error>
</ui-questionnaire-item>
`)}
<ui-questionnaire-actions>
<ui-questionnaire-previous></ui-questionnaire-previous>
<ui-questionnaire-skip></ui-questionnaire-skip>
<ui-questionnaire-next></ui-questionnaire-next>
<ui-questionnaire-submit></ui-questionnaire-submit>
</ui-questionnaire-actions>
</ui-questionnaire>
`
questionnaire.addEventListener('submit', (event) => {
// The element cancels a submit that only moved to the next item.
if (event.defaultPrevented) return;
event.preventDefault();
const formData = new FormData(event.target as HTMLFormElement);
console.log({
prototype: formData.get('prototype'),
detail: formData.get('detail'),
});
});
Every part renders on the server from its markup, and the element reads the item order from the DOM. Before the element loads, every item shows at once and Submit is the only action; once it loads it shows one item at a time and fills in the progress and the Previous, Skip and Next actions.
Multiple selection
multiple turns an item's fixed choices into native checkboxes. Read the answers with FormData.getAll().
<ui-questionnaire-item name="signals" multiple required>
<ui-questionnaire-title>What should every update include?</ui-questionnaire-title>
<ui-questionnaire-description>Select all that apply.</ui-questionnaire-description>
<ui-questionnaire-choices>
<ui-questionnaire-choice value="progress">Progress</ui-questionnaire-choice>
<ui-questionnaire-choice value="decisions">Decisions</ui-questionnaire-choice>
<ui-questionnaire-choice value="risks">Risks</ui-questionnaire-choice>
</ui-questionnaire-choices>
<ui-questionnaire-error></ui-questionnaire-error>
</ui-questionnaire-item>
const signals = new FormData(form).getAll('signals').map(String);
Freeform answers
<ui-questionnaire-input> adds a freeform answer and renders a native text input named after its item. On a single-answer item, typing clears the picked choice and picking a choice clears the text.
<ui-questionnaire-item name="prototype" required>
<ui-questionnaire-title>What should we prototype next?</ui-questionnaire-title>
<ui-questionnaire-choices>
<ui-questionnaire-choice value="delegation">Delegation</ui-questionnaire-choice>
<ui-questionnaire-choice value="questions">Question prompts</ui-questionnaire-choice>
<ui-questionnaire-input
aria-label="Another prototype direction"
placeholder="Type another direction…"
></ui-questionnaire-input>
</ui-questionnaire-choices>
<ui-questionnaire-error></ui-questionnaire-error>
</ui-questionnaire-item>
The text input is always submitted, as an empty string when it was not used, so treat "" as no answer.
Explicit skip
<ui-questionnaire-skip> shows on an optional item, clears that item's answers, and moves on. A skipped item submits like an unanswered one, its choices absent from FormData and its text input empty. When your application needs to tell the two apart, record the click on the Skip action together with the active item, which the ui-active-change event names.
let active = questionnaire.items()[0]?.name;
const skipped = new Set<string>();
questionnaire.addEventListener('ui-active-change', (e) => {
active = e.detail.name;
});
questionnaire.querySelector('ui-questionnaire-skip')?.addEventListener('click', () => {
skipped.add(active);
});
<ui-questionnaire>
<ui-questionnaire-item name="timing">
<ui-questionnaire-title>When should this be revisited?</ui-questionnaire-title>
<ui-questionnaire-description>Skip this if timing has not been decided.</ui-questionnaire-description>
<ui-questionnaire-choices>
<ui-questionnaire-choice value="week">This week</ui-questionnaire-choice>
<ui-questionnaire-choice value="cycle">Next cycle</ui-questionnaire-choice>
</ui-questionnaire-choices>
</ui-questionnaire-item>
<ui-questionnaire-actions>
<ui-questionnaire-skip></ui-questionnaire-skip>
<ui-questionnaire-submit></ui-questionnaire-submit>
</ui-questionnaire-actions>
</ui-questionnaire>
Answer shortcuts
Use shortcuts="letters" or shortcuts="numbers" to give each fixed choice a key, by its position in its item. Each choice shows its own hint.
<ui-questionnaire shortcuts="letters">
<ui-questionnaire-item name="review" required>
<ui-questionnaire-title>What should the agent review?</ui-questionnaire-title>
<ui-questionnaire-choices>
<ui-questionnaire-choice value="api">Public API</ui-questionnaire-choice>
<ui-questionnaire-choice value="tests">Test coverage</ui-questionnaire-choice>
</ui-questionnaire-choices>
</ui-questionnaire-item>
</ui-questionnaire>
"letters" assigns A through Z; "numbers" assigns 1 through 9. A disabled choice keeps its position, so the keys after it do not shift, and its own key does nothing. Selecting an answer by shortcut does not advance to the next item. Set the attribute in the markup, since the choices read it when they render.
Validation
Questionnaire validates the active item before moving forward, and when the form submits on the last item it returns to the first required item that has no answer.
- A required item is valid after it has an answer: a checked choice or a filled text input.
- An optional item is always valid.
- Disabled items are left out.
required does not add visible "Required" text. Say it in the title or description.
When validation fails, Questionnaire keeps or opens the invalid item, marks its fieldset aria-invalid, and focuses its first answer. Add <ui-questionnaire-error> to show a message.
<ui-questionnaire-item name="scope" required>
<ui-questionnaire-title>What should the project include? (Required)</ui-questionnaire-title>
<ui-questionnaire-choices><!-- choices --></ui-questionnaire-choices>
<ui-questionnaire-error></ui-questionnaire-error>
</ui-questionnaire-item>
The error stays hidden until the item is invalid. Its content replaces the default message, which is "Choose an answer to continue." on a required item.
<ui-questionnaire-error>Please choose a project scope.</ui-questionnaire-error>
Validation still works without an error part. When one is rendered, it is a role="alert" while shown, so the message is announced.
For Zod or another validator, check the FormData in a submit listener, cancel the submit when it fails, and set the item's invalid property, which shows its error on the item on screen, the last one when Submit fires.
import type { UiQuestionnaireItem } from '#components/ui/questionnaire.ts';
questionnaire.addEventListener('submit', (event) => {
if (event.defaultPrevented) return;
const data = Object.fromEntries(new FormData(event.target as HTMLFormElement));
if (!schema.safeParse(data).success) {
event.preventDefault();
const item = questionnaire.querySelector<UiQuestionnaireItem>('ui-questionnaire-item[name="audience"]');
if (item) item.invalid = true;
}
});
Controlled navigation
The element owns the active item. It dispatches ui-active-change with { detail: { name } } each time it moves, so your state can follow it, and its next(), previous() and skip() methods move it from your own controls.
Current checkpoint: Change scope
questionnaire.addEventListener('ui-active-change', (e) => {
status.textContent = `Current checkpoint: ${e.detail.name}`;
});
nextButton.addEventListener('click', () => questionnaire.next());
Resume with defaults
Restore a saved draft with checked on the choices. The flow starts on the first item.
<ui-questionnaire>
<ui-questionnaire-item name="scope" required>
<ui-questionnaire-title>Which files are in scope?</ui-questionnaire-title>
<ui-questionnaire-choices>
<ui-questionnaire-choice value="component" checked>Component only</ui-questionnaire-choice>
</ui-questionnaire-choices>
</ui-questionnaire-item>
</ui-questionnaire>
Conditional items
Set disabled to remove an item from the current flow. Disabled items are excluded from progress, navigation, validation, and submission. To change it at runtime, toggle the attribute from a change listener and call the questionnaire's sync().
questionnaire.addEventListener('change', (e) => {
const input = e.target as HTMLInputElement;
if (input.name !== 'runtime') return;
questionnaire
.querySelector('ui-questionnaire-item[name="region"]')
?.toggleAttribute('disabled', input.value !== 'remote');
questionnaire.sync();
});
Navigation state
Navigation actions stay enabled so activating Next or Submit can show a validation error. To change the look of Next while the active item has no checked choice, select on the state the markup does carry:
[data-slot="questionnaire"]:not(:has([data-slot="questionnaire-item"][data-active] :checked))
[data-slot="questionnaire-next"] {
opacity: 0.5;
}
Custom progress
<ui-questionnaire-progress> renders Question {current} of {total} and takes no render target or content. Style it with classes. For another format, render your own line and update it from ui-active-change.
questionnaire.addEventListener('ui-active-change', (e) => {
const items = questionnaire.items();
const current = items.findIndex((item) => item.name === e.detail.name) + 1;
output.textContent = `Checkpoint ${current} of ${items.length}`;
});
The progressbar's accessible name is fixed as "Questionnaire progress"; an aria-label on the element is not passed to it.
Animated items
Animate the active item while keeping progress and navigation stationary. A class on <ui-questionnaire-item> lands on the fieldset it renders, which carries data-active while it is shown.
<ui-questionnaire-item
class="data-active:animate-in data-active:fade-in-0 data-active:slide-in-from-bottom-2 data-active:duration-300 motion-reduce:animate-none"
name="task"
required
>
...
</ui-questionnaire-item>
Inactive items hide immediately, so animate the entry only.
Card composition
Place the root around a card and put the title and description in the card header, with the card's classes on them. The title still renders the legend, and the item names its fieldset by the title wherever it sits.
<ui-questionnaire>
<div data-slot="card" class=${cardClass()}>
<ui-questionnaire-item name="task" required>
<div data-slot="card-header" class=${cardHeaderClass()}>
<ui-questionnaire-title class=${cardTitleClass()}>What should the agent work on?</ui-questionnaire-title>
<ui-questionnaire-description class=${cardDescriptionClass()}>
Choose the task that should be handled next.
</ui-questionnaire-description>
<div data-slot="card-action" class=${cardActionClass()}>
<ui-questionnaire-progress></ui-questionnaire-progress>
</div>
</div>
<div data-slot="card-content" class=${cardContentClass()}>
<ui-questionnaire-choices><!-- choices --></ui-questionnaire-choices>
<ui-questionnaire-error></ui-questionnaire-error>
</div>
</ui-questionnaire-item>
<div data-slot="card-footer" class=${cardFooterClass()}>
<ui-questionnaire-next>Next</ui-questionnaire-next>
<ui-questionnaire-submit>Submit</ui-questionnaire-submit>
</div>
</div>
</ui-questionnaire>
Dialog composition
Keep dialog dismissal separate from Skip: closing cancels the flow, while skipping records an intentional unanswered item.
<ui-dialog>
<ui-dialog-trigger><button class=${buttonClass({ variant: 'outline' })}>Open clarification</button></ui-dialog-trigger>
<ui-dialog-content>
<ui-questionnaire>
<ui-questionnaire-item name="scope" required>
<div data-slot="dialog-header" class=${dialogHeaderClass()}>
<ui-questionnaire-progress></ui-questionnaire-progress>
<ui-questionnaire-title class=${dialogTitleClass()}>Which files are in scope?</ui-questionnaire-title>
<ui-questionnaire-description class=${dialogDescriptionClass()}>
Choose how broadly the agent can update the workspace.
</ui-questionnaire-description>
</div>
<ui-questionnaire-choices><!-- choices --></ui-questionnaire-choices>
<ui-questionnaire-error></ui-questionnaire-error>
</ui-questionnaire-item>
<div data-slot="dialog-footer" class=${dialogFooterClass()}>
<ui-dialog-close><button class=${buttonClass({ variant: 'outline' })}>Cancel</button></ui-dialog-close>
<ui-questionnaire-next>Next</ui-questionnaire-next>
<ui-questionnaire-submit>Send answer</ui-questionnaire-submit>
</div>
</ui-questionnaire>
</ui-dialog-content>
</ui-dialog>
Custom render targets
Each part renders a fixed element (the root a form, an item a fieldset, a title a legend, a description a p, the actions buttons), and a class on the part is merged onto that element. A part's host is display: contents, so the rendered element is the box its parent lays out. To render something else, edit the component file the CLI copied into your project.
Unlike the headless primitive, every rendered element carries a data-slot, which the styles key on and you can select on too.
Native forms
<ui-questionnaire> always renders a native form. It takes action and method attributes, which it passes to the form, and the native submit and reset events bubble from it. Do not nest a questionnaire inside another form. Binding a 'use server' action needs action=${fn} on a <form> your template writes, so the element's form takes a URL, not a server action.
Answers serialize through native controls:
FormData.get(itemName)reads a single answer.FormData.getAll(itemName)reads multiple answers.- A skipped item's choices are absent from
FormData; its text input, if it has one, is present and empty.
The form gets novalidate once the element loads, so validation uses the error parts instead of the browser's constraint UI. With JavaScript off every item shows, and the browser's own required check covers a required single-answer item's radios.
form.reset() restores the native controls only. The element does not reset the active item or the validation state.
Keyboard navigation
Questionnaire builds on native radio, checkbox, input, and button behavior.
Shortcuts pause while you type in a text field and while Ctrl, Cmd or Alt is held. Enter is the browser's own form submission. Leave out shortcuts to keep the keys free.
Navigation actions stay enabled so an attempted action can reveal validation feedback. See Navigation state to restyle an unanswered action.
Accessibility
<ui-questionnaire-item>renders afieldset.<ui-questionnaire-title>renders alegendwith anid, and the item names its fieldset by it witharia-labelledby, wherever the title sits inside the item.- The description and, while the item is invalid, the error are connected with
aria-describedby. - An invalid item's fieldset exposes
aria-invalid="true", and its error is arole="alert". The answer controls do not carryaria-invalid. <ui-questionnaire-progress>renders arole="progressbar"named "Questionnaire progress", with current, minimum, maximum, and text values, as a polite live region.- Fixed choices are native radios and checkboxes.
- Assigned shortcut keys are exposed with
aria-keyshortcutson each choice's input, and the visible Next or Submit carriesaria-keyshortcuts="Enter". - Inactive items are
hiddenandinert; actions that do not apply arehiddenandaria-hidden. - Navigation focuses the newly active item's first available answer.
- Validation focuses the first available answer control.
- Disabled items are omitted from progress and navigation.
Always give <ui-questionnaire-input> an accessible name with aria-label, which the element passes to the input it renders. When the input has a visible label, repeat its text in aria-label.
<ui-questionnaire-input
aria-label="Other answer"
placeholder="Type another answer…"
></ui-questionnaire-input>
A placeholder is not a label.
Data attributes
Use these attributes for styling. Boolean attributes are present when true and absent when false. They sit on the elements the parts render, not on the part hosts, and every rendered element also carries a data-slot named after its part. Some states are carried by a native or ARIA attribute, which is listed with them.
Root and Progress
The progress element carries the position as aria-valuenow and aria-valuemax.
Item
The fieldset also carries hidden and inert while inactive, disabled when the item is disabled, and aria-invalid="true" after failed validation.
Choice
The choice renders a label (data-slot="questionnaire-choice") holding the input (questionnaire-choice-input), the indicator (questionnaire-choice-indicator, with -indicator-dot and -indicator-check), the label text (questionnaire-choice-label) and the shortcut hint (questionnaire-choice-shortcut).
Choices
No state attributes. The shortcut mode is on the form's data-shortcuts.
Input
No state attributes. The input (data-slot="questionnaire-input") sits in a wrapper (questionnaire-input-wrapper) and is natively disabled with its item; style an empty input with :placeholder-shown.
Error
No state attributes. The error is hidden until its item is invalid, and a role="alert" while it shows.
Previous, Skip, Next, and Submit
An action that does not apply to the active item is hidden and aria-hidden; a visible Next or Submit carries aria-keyshortcuts="Enter".
API Reference
ui-questionnaire
The form and coordination root.
The flow starts on the first enabled item, the order comes from the markup, and novalidate is set once the element loads.
ui-questionnaire-progress
Position within the enabled items. It renders Question {current} of {total} and takes no attributes, content or render target apart from a merged class. Its accessible name is "Questionnaire progress".
ui-questionnaire-item
One questionnaire step, rendered as a fieldset.
It also has an invalid property, set by validation and settable from your own validator, and inputs() and choices() methods returning its answer controls and its choices. Item names must be unique within a questionnaire.
ui-questionnaire-title
The item title. It renders a legend with an id the item uses for aria-labelledby, and takes a merged class.
ui-questionnaire-description
Supporting text, rendered as a p and connected to the item with aria-describedby. It takes a merged class.
ui-questionnaire-choices
A layout container (a div) for fixed and freeform answers. It takes a merged class.
ui-questionnaire-choice
A fixed answer. It renders a label around a native radio, or a checkbox in a multiple item, its indicator, its content and its shortcut hint, so the whole row is associated with the control.
Its input() method returns the native control, which owns its state after the first render. Put a <ui-questionnaire-choice-description> inside for a second line.
Choice input, label and shortcut
The choice's input, label and shortcut hint are rendered by <ui-questionnaire-choice>: the input is laid transparent over the row, the label text is the choice's content, and the shortcut hint shows the assigned key and stays hidden without one. They are not separate elements, so they take no attributes; style them through their data-slot.
ui-questionnaire-input
A freeform answer, a native text input whose name is its item's.
The input is a type="text" field.
ui-questionnaire-error
The validation message, a p hidden until its item fails validation. Its content replaces the default message, "Choose an answer to continue." on a required item and "Choose an answer or skip this question." otherwise. It takes a merged class.
Navigation actions
<ui-questionnaire-previous>, <ui-questionnaire-skip>, <ui-questionnaire-next> and <ui-questionnaire-submit> render native buttons and stay mounted while their visibility changes. Their content replaces the default label.
<ui-questionnaire-actions> is the layout container: a grid that places Previous at the start and Skip, Next and Submit at the end. It takes a merged class.