Skip to content
WebJs
Menu

Questionnaire

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

What should the agent build next?

Choose a direction or describe another task.

What should every progress update include?

Select all that apply, or skip this question.

When should work begin?

Choose when the agent should begin the work.

import { html } from '@webjsdev/core';

export default function QuestionnaireDemo() {
  return html`
    <ui-questionnaire class="mx-auto max-w-md" shortcuts="letters">
      <ui-questionnaire-progress></ui-questionnaire-progress>

      <ui-questionnaire-item name="direction" required>
        <ui-questionnaire-title>
          What should the agent build next?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Choose a direction or describe another task.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="tool-calls">
            <span class="font-medium">Tool call timeline</span>
            <span class="text-muted-foreground">
              Show what the agent ran and what came back.
            </span>
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="approvals">
            <span class="font-medium">Approval checkpoints</span>
            <span class="text-muted-foreground">
              Ask before sensitive or destructive actions.
            </span>
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="handoffs">
            <span class="font-medium">Sub-agent handoffs</span>
            <span class="text-muted-foreground">
              Make delegated work and results easier to follow.
            </span>
          </ui-questionnaire-choice>
          <ui-questionnaire-input
            aria-label="Another agent feature"
            placeholder="Describe another feature…"
          ></ui-questionnaire-input>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="signals" multiple>
        <ui-questionnaire-title>
          What should every progress update include?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Select all that apply, or skip this question.
        </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-choice value="next-step">Next step</ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="timing" required>
        <ui-questionnaire-title>When should work begin?</ui-questionnaire-title>
        <ui-questionnaire-description>
          Choose when the agent should begin the work.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="now">Start now</ui-questionnaire-choice>
          <ui-questionnaire-choice value="next-cycle">
            Next development cycle
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="backlog">
            Add it to the backlog
          </ui-questionnaire-choice>
        </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>Next</ui-questionnaire-next>
        <ui-questionnaire-submit>Save plan</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add questionnaire

Usage

The questionnaire parts are custom elements. Importing the module registers them, and the page renders them by tag.

import '#components/ui/questionnaire.ts';
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 and map it into the parts. The page renders every question on the server, and the element takes over the progress, the actions and the shortcuts once it loads.

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}>
              <span class="font-medium">${choice.label}</span>
              ${'description' in choice
                ? html`<span class="text-muted-foreground">${choice.description}</span>`
                : ''}
            </ui-questionnaire-choice>
          `)}
          ${'input' in question
            ? 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>
`

The element renders a native <form>, so the answers are read with FormData. Its own submit handler runs first and cancels a submit that is not on the last question yet, so a listener checks defaultPrevented.

questionnaire.addEventListener('submit', (event) => {
  if (event.defaultPrevented) return;
  event.preventDefault();
  const answers = new FormData(event.target as HTMLFormElement);
  // answers.get('direction'), answers.getAll(...) for multiple items.
});

Composition

ui-questionnaire
├── ui-questionnaire-progress
├── ui-questionnaire-item
│   ├── ui-questionnaire-title
│   ├── ui-questionnaire-description
│   ├── ui-questionnaire-choices
│   │   ├── ui-questionnaire-choice
│   │   └── ui-questionnaire-input
│   └── ui-questionnaire-error
└── ui-questionnaire-actions
    ├── ui-questionnaire-previous
    ├── ui-questionnaire-skip
    ├── ui-questionnaire-next
    └── ui-questionnaire-submit

<ui-questionnaire> owns the ordered items, the active item, validation, progress, and navigation. The answers live in the form controls themselves. The containing page, card, dialog, or drawer owns close and cancellation behavior, persistence, transport, and branching.

Server Rendering

Every part renders on the server. Without JavaScript every question shows at once, Submit is the only action, and it posts the form with the browser's own required check: set action and method on <ui-questionnaire> to choose where. Once the element loads it shows one question at a time and fills in the progress and the Previous, Skip and Next buttons.

Multiple Selection

Use multiple for an item that accepts more than one fixed answer. Its choices render as checkboxes, read with FormData.getAll().

What context should the agent inspect?

Select every source that may affect the implementation.

import { html } from '@webjsdev/core';

export default function QuestionnaireMultiple() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md" shortcuts="letters">
      <ui-questionnaire-item name="context" multiple required>
        <ui-questionnaire-title>
          What context should the agent inspect?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Select every source that may affect the implementation.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="source">
            Relevant source files
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="tests">
            Existing tests
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="docs">
            Architecture documentation
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="history">
            Recent commit history
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-submit>Share context</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Freeform Answer

Compose <ui-questionnaire-input> with fixed choices when the user can provide another answer. On a single-answer item, typing clears the picked choice and picking a choice clears the text.

How should the agent approach this refactor?

Choose a strategy or write a more specific instruction.

import { html } from '@webjsdev/core';

export default function QuestionnaireFreeform() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md" shortcuts="letters">
      <ui-questionnaire-item name="approach" required>
        <ui-questionnaire-title>
          How should the agent approach this refactor?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Choose a strategy or write a more specific instruction.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="incremental">
            Make the smallest safe change
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="module">
            Refactor one module at a time
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="rewrite">
            Replace the implementation completely
          </ui-questionnaire-choice>
          <ui-questionnaire-input
            aria-label="Another refactoring approach"
            placeholder="Describe another approach…"
          ></ui-questionnaire-input>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-submit>Use this approach</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Explicit Skip

Add <ui-questionnaire-skip> when an optional item may be intentionally left unanswered. It shows only on an item without required, clears that item's answers, and moves on.

What kind of change is this?

Choose the category that best describes the work.

Are there any implementation constraints?

Answer if needed, or intentionally skip this question.

How should the work be reviewed?

Choose the checks the agent should complete before handoff.

import { html } from '@webjsdev/core';

export default function QuestionnaireSkipExample() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md">
      <ui-questionnaire-progress></ui-questionnaire-progress>

      <ui-questionnaire-item name="task" required>
        <ui-questionnaire-title>What kind of change is this?</ui-questionnaire-title>
        <ui-questionnaire-description>
          Choose the category that best describes the work.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="feature">New feature</ui-questionnaire-choice>
          <ui-questionnaire-choice value="fix">Bug fix</ui-questionnaire-choice>
          <ui-questionnaire-choice value="refactor">Refactor</ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="constraints">
        <ui-questionnaire-title>
          Are there any implementation constraints?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Answer if needed, or intentionally skip this question.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="no-dependencies">
            Do not add dependencies
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="no-migrations">
            Do not change the database
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="preserve-api">
            Preserve the public API
          </ui-questionnaire-choice>
          <ui-questionnaire-input
            aria-label="Another implementation constraint"
            placeholder="Describe another constraint…"
          ></ui-questionnaire-input>
        </ui-questionnaire-choices>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="review" required>
        <ui-questionnaire-title>
          How should the work be reviewed?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Choose the checks the agent should complete before handoff.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="tests">
            Run the test suite
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="diff">
            Review the final diff
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="both">
            Tests and diff review
          </ui-questionnaire-choice>
        </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>Next</ui-questionnaire-next>
        <ui-questionnaire-submit>Submit brief</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Shortcuts

Assign a letter or number key to each answer with shortcuts="letters" or shortcuts="numbers". A key picks the matching answer, except while typing in a text field. Set the attribute in the markup, since the choices read it when they render.

What should the agent do next?

Use the displayed shortcut or navigate with the keyboard.

import { html } from '@webjsdev/core';

export default function QuestionnaireShortcuts() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md" shortcuts="letters">
      <ui-questionnaire-item name="action" required>
        <ui-questionnaire-title>
          What should the agent do next?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Use the displayed shortcut or navigate with the keyboard.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="inspect">
            Inspect the implementation
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="tests">
            Run the relevant tests
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="patch">
            Prepare the patch
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-submit>Confirm action</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Custom Validation

The element checks required items itself. For a rule across answers, listen for submit, check the FormData against a schema such as Zod, call preventDefault() when it fails, and put the message in the item's <ui-questionnaire-error>. The demo below runs the built-in required check.

How much detail should the answer include?

Choose the response depth.

Who will read the answer?

Public answers require complete context.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  cardClass, cardHeaderClass, cardActionClass, cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';

// The schema check runs in your own submit listener: read the answers with
// FormData, and when the pair is rejected, call preventDefault() and put the
// message in that question's <ui-questionnaire-error>.
export default function QuestionnaireValidation() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md">
      <div data-slot="card" data-size="default" class=${cn(cardClass(), 'w-full')}>
        <ui-questionnaire-item name="detail" required>
          <div data-slot="card-header" class=${cardHeaderClass()}>
            <ui-questionnaire-title>
              How much detail should the answer include?
            </ui-questionnaire-title>
            <ui-questionnaire-description>
              Choose the response depth.
            </ui-questionnaire-description>
            <div data-slot="card-action" class=${cardActionClass()}>
              <ui-questionnaire-progress class="min-w-0"></ui-questionnaire-progress>
            </div>
          </div>
          <div data-slot="card-content" class=${cardContentClass()}>
            <ui-questionnaire-choices>
              <ui-questionnaire-choice value="summary">
                Concise summary
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="complete">
                Complete answer
              </ui-questionnaire-choice>
            </ui-questionnaire-choices>
            <ui-questionnaire-error></ui-questionnaire-error>
          </div>
        </ui-questionnaire-item>

        <ui-questionnaire-item name="audience" required>
          <div data-slot="card-header" class=${cardHeaderClass()}>
            <ui-questionnaire-title>Who will read the answer?</ui-questionnaire-title>
            <ui-questionnaire-description>
              Public answers require complete context.
            </ui-questionnaire-description>
            <div data-slot="card-action" class=${cardActionClass()}>
              <ui-questionnaire-progress class="min-w-0"></ui-questionnaire-progress>
            </div>
          </div>
          <div data-slot="card-content" class=${cardContentClass()}>
            <ui-questionnaire-choices>
              <ui-questionnaire-choice value="team">
                My team
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="public">
                Public audience
              </ui-questionnaire-choice>
            </ui-questionnaire-choices>
            <ui-questionnaire-error></ui-questionnaire-error>
          </div>
        </ui-questionnaire-item>

        <div data-slot="card-footer" class=${cardFooterClass()}>
          <ui-questionnaire-actions class="w-full">
            <ui-questionnaire-previous></ui-questionnaire-previous>
            <ui-questionnaire-next>Next</ui-questionnaire-next>
            <ui-questionnaire-submit>Validate answers</ui-questionnaire-submit>
          </ui-questionnaire-actions>
        </div>
      </div>
    </ui-questionnaire>
  `;
}
View Code

Controlled

The element owns the active item and dispatches ui-active-change with { detail: { name } } each time it moves, so host state can follow it. Update a status line like the one in this demo from that listener.

Current checkpoint: Change scope

What may the agent change?

The host stores the active checkpoint while Questionnaire navigates.

Which verification level should it use?
What should the agent return when finished?
import { html } from '@webjsdev/core';

// The questionnaire owns the active question and announces each change with
// a ui-active-change event ({ detail: { name } }). A listener that writes
// the matching label into the status line keeps the host in step.
export default function QuestionnaireControlled() {
  return html`
    <div class="relative mx-auto flex h-full w-full max-w-md flex-col">
      <p class="absolute end-0 top-0 text-sm text-muted-foreground" role="status">
        Current checkpoint: Change scope
      </p>

      <ui-questionnaire class="mt-auto">
        <ui-questionnaire-progress></ui-questionnaire-progress>

        <ui-questionnaire-item name="scope" required>
          <ui-questionnaire-title>What may the agent change?</ui-questionnaire-title>
          <ui-questionnaire-description>
            The host stores the active checkpoint while Questionnaire navigates.
          </ui-questionnaire-description>
          <ui-questionnaire-choices>
            <ui-questionnaire-choice value="component">
              Only the target component
            </ui-questionnaire-choice>
            <ui-questionnaire-choice value="tests">
              Component and related tests
            </ui-questionnaire-choice>
            <ui-questionnaire-choice value="feature">
              The complete feature area
            </ui-questionnaire-choice>
          </ui-questionnaire-choices>
          <ui-questionnaire-error></ui-questionnaire-error>
        </ui-questionnaire-item>

        <ui-questionnaire-item name="checks" required>
          <ui-questionnaire-title>
            Which verification level should it use?
          </ui-questionnaire-title>
          <ui-questionnaire-choices>
            <ui-questionnaire-choice value="targeted">
              Targeted tests
            </ui-questionnaire-choice>
            <ui-questionnaire-choice value="package">
              Package tests and typecheck
            </ui-questionnaire-choice>
            <ui-questionnaire-choice value="full">
              Full workspace verification
            </ui-questionnaire-choice>
          </ui-questionnaire-choices>
          <ui-questionnaire-error></ui-questionnaire-error>
        </ui-questionnaire-item>

        <ui-questionnaire-item name="output" required>
          <ui-questionnaire-title>
            What should the agent return when finished?
          </ui-questionnaire-title>
          <ui-questionnaire-choices>
            <ui-questionnaire-choice value="summary">
              Concise summary
            </ui-questionnaire-choice>
            <ui-questionnaire-choice value="diff">
              Summary with changed files
            </ui-questionnaire-choice>
            <ui-questionnaire-choice value="handoff">
              Detailed implementation handoff
            </ui-questionnaire-choice>
          </ui-questionnaire-choices>
          <ui-questionnaire-error></ui-questionnaire-error>
        </ui-questionnaire-item>

        <ui-questionnaire-actions>
          <ui-questionnaire-previous></ui-questionnaire-previous>
          <ui-questionnaire-next>Next</ui-questionnaire-next>
          <ui-questionnaire-submit>Save workflow</ui-questionnaire-submit>
        </ui-questionnaire-actions>
      </ui-questionnaire>
    </div>
  `;
}
View Code

Resume

Restore saved answers with checked on the choices. The flow starts on the first item.

What kind of migration is this?

This answer was saved during the previous session.

How should the migration be verified?

These checks were selected during the previous session.

Anything else the agent should remember?

This note was saved with the draft.

import { html } from '@webjsdev/core';

// The saved answers are the choices' checked attributes.
export default function QuestionnaireResume() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md">
      <ui-questionnaire-progress></ui-questionnaire-progress>

      <ui-questionnaire-item name="change" required>
        <ui-questionnaire-title>What kind of migration is this?</ui-questionnaire-title>
        <ui-questionnaire-description>
          This answer was saved during the previous session.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="incremental" checked>
            Incremental migration
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="cutover">
            Single cutover
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="verification" multiple required>
        <ui-questionnaire-title>
          How should the migration be verified?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          These checks were selected during the previous session.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="tests" checked>
            Run migration tests
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="typecheck" checked>
            Run the typecheck
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="manual">
            Perform a manual smoke test
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="notes">
        <ui-questionnaire-title>
          Anything else the agent should remember?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          This note was saved with the draft.
        </ui-questionnaire-description>
        <ui-questionnaire-input aria-label="Saved migration note"></ui-questionnaire-input>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-previous></ui-questionnaire-previous>
        <ui-questionnaire-next>Next</ui-questionnaire-next>
        <ui-questionnaire-submit>Update draft</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Conditional Items

Disable items that do not apply to the user's earlier answers. A disabled item is left out of the flow and the progress. To toggle one at runtime, set its disabled attribute from a change listener and call the questionnaire's sync(); in this demo the environment question stays disabled.

Where should the agent run?

Cloud runs add an environment question to this flow.

Which cloud environment should it use?
When should the agent request approval?
import { html } from '@webjsdev/core';

// A disabled question is left out of the flow. Toggle the environment
// question's disabled attribute from a change listener on the runtime
// answer, and the progress and actions follow.
export default function QuestionnaireConditional() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md">
      <ui-questionnaire-progress></ui-questionnaire-progress>

      <ui-questionnaire-item name="runtime" required>
        <ui-questionnaire-title>Where should the agent run?</ui-questionnaire-title>
        <ui-questionnaire-description>
          Cloud runs add an environment question to this flow.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="local" checked>
            Local workspace
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="cloud">
            Cloud workspace
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="environment" required disabled>
        <ui-questionnaire-title>
          Which cloud environment should it use?
        </ui-questionnaire-title>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="preview">Preview</ui-questionnaire-choice>
          <ui-questionnaire-choice value="staging">Staging</ui-questionnaire-choice>
          <ui-questionnaire-choice value="isolated">
            Isolated sandbox
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="approval" required>
        <ui-questionnaire-title>
          When should the agent request approval?
        </ui-questionnaire-title>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="writes">
            Before writing files
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="commands">
            Before running commands
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="sensitive">
            Only for sensitive actions
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-previous></ui-questionnaire-previous>
        <ui-questionnaire-next>Next</ui-questionnaire-next>
        <ui-questionnaire-submit>Save execution plan</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

The kit exposes no per-item status, and its navigation buttons never disable. Next validates the active item instead: pressed with no answer, it stays put, marks the item invalid and shows its error. The buttons take variant and size as a button does.

What may the agent modify?

Next stays on this question until an answer is selected.

What must pass before completion?
import { html } from '@webjsdev/core';

// Next validates the active question itself: pressed with no answer, it
// stays put, marks the question invalid and shows its error.
export default function QuestionnaireNavigationState() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md">
      <ui-questionnaire-progress></ui-questionnaire-progress>

      <ui-questionnaire-item name="permission" required>
        <ui-questionnaire-title>What may the agent modify?</ui-questionnaire-title>
        <ui-questionnaire-description>
          Next stays on this question until an answer is selected.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="files">Project files</ui-questionnaire-choice>
          <ui-questionnaire-choice value="tests">
            Project files and tests
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="config">
            Files, tests, and configuration
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="verification" required>
        <ui-questionnaire-title>
          What must pass before completion?
        </ui-questionnaire-title>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="tests">Tests</ui-questionnaire-choice>
          <ui-questionnaire-choice value="types">
            Tests and types
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="all">
            Tests, types, and visual QA
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-previous></ui-questionnaire-previous>
        <ui-questionnaire-next variant="secondary">Next</ui-questionnaire-next>
        <ui-questionnaire-submit>Save permissions</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Custom Progress

<ui-questionnaire-progress> renders a "Question 1 of 4" line. Style the line with classes on the element.

How large is the change?
How should commits be organized?
Which tests should run?
How should the work be delivered?
import { html } from '@webjsdev/core';

// <ui-questionnaire-progress> renders a "Question 1 of 4" line. Style it
// with classes on the element; it takes no custom render.
export default function QuestionnaireProgressExample() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md">
      <ui-questionnaire-progress class="w-full"></ui-questionnaire-progress>

      <ui-questionnaire-item name="scope" required>
        <ui-questionnaire-title>How large is the change?</ui-questionnaire-title>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="small">Small patch</ui-questionnaire-choice>
          <ui-questionnaire-choice value="medium">
            Feature-sized change
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="large">
            Cross-package change
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="strategy" required>
        <ui-questionnaire-title>
          How should commits be organized?
        </ui-questionnaire-title>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="single">
            Single commit
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="logical">
            Logical commits
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="squash">
            Squash before review
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="tests" required>
        <ui-questionnaire-title>Which tests should run?</ui-questionnaire-title>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="targeted">
            Targeted tests
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="package">
            Package suite
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="workspace">
            Full workspace
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item name="delivery" required>
        <ui-questionnaire-title>
          How should the work be delivered?
        </ui-questionnaire-title>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="patch">Patch only</ui-questionnaire-choice>
          <ui-questionnaire-choice value="commit">
            Committed locally
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="branch">
            Push a review branch
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-previous></ui-questionnaire-previous>
        <ui-questionnaire-next>Next</ui-questionnaire-next>
        <ui-questionnaire-submit>Finish plan</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Animated Items

Animate the active item while keeping progress and navigation stationary. Each item moves its class onto the fieldset it renders, which carries data-active while it is shown, so the data-active: variant targets it directly.

What should the agent do?

Choose the task for this run.

How should the work be reviewed?

Select the verification depth.

How should the result be delivered?

Choose the final handoff format.

import { html } from '@webjsdev/core';

// The element moves this class onto the fieldset it renders, which carries
// data-active while its question is on screen, so the variants key on the
// fieldset itself.
const itemClass =
  'data-active:animate-in data-active:fade-in-0 data-active:slide-in-from-bottom-2 data-active:duration-300 motion-reduce:animate-none';

export default function QuestionnaireAnimated() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md">
      <ui-questionnaire-progress></ui-questionnaire-progress>

      <ui-questionnaire-item class=${itemClass} name="task" required>
        <ui-questionnaire-title>What should the agent do?</ui-questionnaire-title>
        <ui-questionnaire-description>
          Choose the task for this run.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="implement">
            Implement the requested change
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="debug">
            Debug the current behavior
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="review">
            Review the implementation
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item class=${itemClass} name="review" required>
        <ui-questionnaire-title>
          How should the work be reviewed?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Select the verification depth.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="targeted">
            Targeted checks
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="complete">
            Complete test suite
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="manual">
            Tests and manual QA
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-item class=${itemClass} name="delivery" required>
        <ui-questionnaire-title>
          How should the result be delivered?
        </ui-questionnaire-title>
        <ui-questionnaire-description>
          Choose the final handoff format.
        </ui-questionnaire-description>
        <ui-questionnaire-choices>
          <ui-questionnaire-choice value="summary">
            Concise summary
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="diff">
            Summary and changed files
          </ui-questionnaire-choice>
          <ui-questionnaire-choice value="handoff">
            Detailed review handoff
          </ui-questionnaire-choice>
        </ui-questionnaire-choices>
        <ui-questionnaire-error></ui-questionnaire-error>
      </ui-questionnaire-item>

      <ui-questionnaire-actions>
        <ui-questionnaire-previous></ui-questionnaire-previous>
        <ui-questionnaire-next>Next</ui-questionnaire-next>
        <ui-questionnaire-submit>Save workflow</ui-questionnaire-submit>
      </ui-questionnaire-actions>
    </ui-questionnaire>
  `;
}
View Code

Card

Compose the questionnaire with the Card class helpers while keeping the question title and description semantic: put cardTitleClass() and cardDescriptionClass() on the title and description elements.

What should the agent work on?

Choose the task that should be handled next.

What should the final handoff include?

Pick the level of detail needed for review.

import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass,
  cardActionClass, cardContentClass, cardFooterClass,
} from '#components/ui/card.ts';

// The title and description keep their own legend and description roles,
// so the card's classes go on them rather than on a separate card title.
export default function QuestionnaireCard() {
  return html`
    <ui-questionnaire class="mx-auto w-full max-w-md" shortcuts="numbers">
      <div data-slot="card" data-size="default" 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>
              <ui-questionnaire-choice value="fix">
                Fix the failing tests
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="refactor">
                Refactor the data layer
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="docs">
                Update the integration guide
              </ui-questionnaire-choice>
            </ui-questionnaire-choices>
            <ui-questionnaire-error></ui-questionnaire-error>
          </div>
        </ui-questionnaire-item>

        <ui-questionnaire-item name="output" required>
          <div data-slot="card-header" class=${cardHeaderClass()}>
            <ui-questionnaire-title class=${cardTitleClass()}>
              What should the final handoff include?
            </ui-questionnaire-title>
            <ui-questionnaire-description class=${cardDescriptionClass()}>
              Pick the level of detail needed for review.
            </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>
              <ui-questionnaire-choice value="summary">
                Summary only
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="files">
                Summary and changed files
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="review">
                Full review handoff
              </ui-questionnaire-choice>
            </ui-questionnaire-choices>
            <ui-questionnaire-error></ui-questionnaire-error>
          </div>
        </ui-questionnaire-item>

        <div data-slot="card-footer" class=${cardFooterClass()}>
          <ui-questionnaire-actions class="w-full">
            <ui-questionnaire-previous></ui-questionnaire-previous>
            <ui-questionnaire-next>Next</ui-questionnaire-next>
            <ui-questionnaire-submit>Create task</ui-questionnaire-submit>
          </ui-questionnaire-actions>
        </div>
      </div>
    </ui-questionnaire>
  `;
}
View Code

Dialog

Compose the questionnaire inside a Dialog while keeping cancellation and dismissal host-owned.

Which files are in scope?

Choose how broadly the agent can update the workspace.

How much verification is needed?

Choose the checks the agent should run before handoff.

import { html } from '@webjsdev/core';
import { buttonClass } from '#components/ui/button.ts';
import {
  dialogHeaderClass, dialogTitleClass, dialogDescriptionClass, dialogFooterClass,
} from '#components/ui/dialog.ts';

// Cancel and dismissal belong to the dialog. Close it from a submit listener
// on the questionnaire once the answers are sent.
export default function QuestionnaireDialog() {
  return html`
    <ui-dialog>
      <ui-dialog-trigger>
        <button type="button" data-slot="button" data-variant="outline" data-size="default" 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>
              <ui-questionnaire-choice value="component">
                Component only
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="feature">
                Complete feature directory
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="workspace">
                Any related workspace file
              </ui-questionnaire-choice>
            </ui-questionnaire-choices>
            <ui-questionnaire-error></ui-questionnaire-error>
          </ui-questionnaire-item>

          <ui-questionnaire-item name="tests" required>
            <div data-slot="dialog-header" class=${dialogHeaderClass()}>
              <ui-questionnaire-progress></ui-questionnaire-progress>
              <ui-questionnaire-title class=${dialogTitleClass()}>
                How much verification is needed?
              </ui-questionnaire-title>
              <ui-questionnaire-description class=${dialogDescriptionClass()}>
                Choose the checks the agent should run before handoff.
              </ui-questionnaire-description>
            </div>
            <ui-questionnaire-choices>
              <ui-questionnaire-choice value="targeted">
                Targeted tests
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="package">
                Package tests
              </ui-questionnaire-choice>
              <ui-questionnaire-choice value="full">
                Full workspace verification
              </ui-questionnaire-choice>
            </ui-questionnaire-choices>
            <ui-questionnaire-error></ui-questionnaire-error>
          </ui-questionnaire-item>

          <div data-slot="dialog-footer" class=${dialogFooterClass()}>
            <ui-dialog-close>
              <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>
                Cancel
              </button>
            </ui-dialog-close>
            <ui-questionnaire-actions class="w-full">
              <ui-questionnaire-previous></ui-questionnaire-previous>
              <ui-questionnaire-next>Next</ui-questionnaire-next>
              <ui-questionnaire-submit>Send answer</ui-questionnaire-submit>
            </ui-questionnaire-actions>
          </div>
        </ui-questionnaire>
      </ui-dialog-content>
    </ui-dialog>
  `;
}
View Code

Accessibility

<ui-questionnaire-item> renders a fieldset, and <ui-questionnaire-title> renders its legend, which also names the fieldset. Descriptions and active errors are associated with the current item, and an item left unanswered exposes aria-invalid with its error announced as an alert.

Fixed choices are native radios and checkboxes. Progress is exposed as a named progressbar, navigation uses real buttons, and inactive items are hidden and inert. Successful navigation focuses the newly active item's first answer, and failed validation focuses an available answer control. Enter goes to the next item, and on the last one submits.

Always give <ui-questionnaire-input> an accessible name with aria-label. A placeholder is not a label.

Unstyled

The behavior lives in the <ui-questionnaire-*> elements, and the classes they apply are exported as helpers such as questionnaireChoiceClass(). Since webjs ui add copies the source into your project, change the markup or the classes there.

API Reference

ui-questionnaire

The root. It renders the <form> and owns the active item, validation, and navigation.

AttributeTypeDefault
shortcuts"letters" | "numbers"-
actionstring-
methodstring-

It dispatches ui-active-change with { detail: { name } } after the active item changes. Its methods are next(), previous(), skip(), validate(item?) (marks the active item invalid and returns false when it needs an answer), answered(item), items() (the items in the flow) and sync() (redraws the parts after host code changes an item).

ui-questionnaire-item

One question, rendered as a fieldset. Its answers share its name.

AttributeTypeDefault
namestring""
requiredbooleanfalse
multiplebooleanfalse
disabledbooleanfalse

ui-questionnaire-choice

One fixed answer: a radio, or a checkbox in a multiple item, with its label. Put a <ui-questionnaire-choice-description> inside for a second line.

AttributeTypeDefault
valuestring""
checkedbooleanfalse
disabledbooleanfalse

ui-questionnaire-input

A freeform answer, a text field named after its item.

AttributeTypeDefault
placeholderstring""
aria-labelstring-

ui-questionnaire-error

The item's error line, hidden until the item is invalid. Its content replaces the default message, which is "Choose an answer to continue." on a required item and "Choose an answer or skip this question." otherwise.

<ui-questionnaire-previous>, <ui-questionnaire-skip>, <ui-questionnaire-next> and <ui-questionnaire-submit> show only when they apply. Their content replaces the default label (Previous, Skip, Next, Submit).

AttributeTypeDefault
variant"default" | "outline" | "ghost" | "destructive" | "secondary" | "link""outline", "default" on Next and Submit
size"default" | "xs" | "sm" | "lg""default"

Layout parts

<ui-questionnaire-actions> is a styled-only layout helper.