# Questionnaire A multi-step questionnaire with single-choice, multiple-choice, freeform, and skippable questions. ```twig What should the agent build next? Choose a direction or describe another task. Tool call timeline Show what the agent ran and what came back. Approval checkpoints Ask before sensitive or destructive actions. Sub-agent handoffs Make delegated work and results easier to follow. What should every progress update include? Select all that apply, or skip this question. Progress Decisions Risks Next step When should work begin? Choose when the agent should begin the work. Start now Next development cycle Add it to the backlog Save plan ``` ## Installation > [!NOTE] > Available since UX Toolkit 3.5. ```shell php bin/console ux:install questionnaire --kit shadcn ``` ## Usage ```twig What should we prototype next? Choose a direction or write your own. Delegation Question prompts ``` `Questionnaire` renders a `form`, so answers are submitted with the name of each `Questionnaire:Item`. An item marked `multiple` submits an array, and its inputs are named `[]`. `Questionnaire` owns the ordered items, the active item, validation, progress, and navigation. The containing page, card, or dialog owns cancellation, persistence, and transport. Set `:interactive="false"` to hand that ownership to the server instead. The component then renders as plain markup: no `data-controller`, no `data-action`, and no `data-questionnaire-*` attributes anywhere in the tree, so the Stimulus controller never boots. See [Server-Driven Flow](#server-driven-flow). ## Examples ### Multiple Selection Use the `multiple` prop for an item that accepts more than one fixed answer. ```twig What context should the agent inspect? Select every source that may affect the implementation. Relevant source files Existing tests Architecture documentation Recent commit history Share context ``` ### Freeform Answer Compose `Questionnaire:Input` with fixed choices when the user can provide another answer. The input and the choices share the item name, so answering one clears the other. ```twig How should the agent approach this refactor? Choose a strategy or write a more specific instruction. Make the smallest safe change Refactor one module at a time Replace the implementation completely Use this approach ``` ### Explicit Skip Add `Questionnaire:Skip` when an optional item may be intentionally left unanswered. The button only appears on items that are not `required`. ```twig What kind of change is this? Choose the category that best describes the work. New feature Bug fix Refactor Are there any implementation constraints? Answer if needed, or intentionally skip this question. Do not add dependencies Do not change the database Preserve the public API How should the work be reviewed? Choose the checks the agent should complete before handoff. Run the test suite Review the final diff Tests and diff review Submit brief ``` ### Shortcuts Assign a letter or number key to each answer with the `shortcuts` prop. Press the key to select the matching choice. ```twig
What should the agent do next? Use the displayed shortcut or navigate with the keyboard. Inspect the implementation Run the relevant tests Prepare the patch Confirm action How much of the codebase may change? The same questionnaire with numbered shortcuts. A single file One package The whole workspace Confirm scope
``` ### Custom Validation Fill `Questionnaire:Error` with your own message to replace the default one shown when a required item has no answer. ```twig How detailed should the answer be? The error below replaces the default validation message. A short summary A full walkthrough Pick a level of detail before continuing. Who will read the answer? Each item can carry its own message. A reviewer A maintainer Tell us who the answer is for. Save answers ``` ### Controlled Use the `defaultItem` prop to render a questionnaire that opens on a specific item, such as the one a server-side validation marked invalid. ```twig What may the agent change? One component Tests only A whole feature Which checks should run before handoff? This questionnaire opens here instead of on the first item. Targeted tests Package suite Full workspace Save answers ``` ### Resume Restore a saved session by combining `defaultItem` with the `checked` prop on the answers that were already given. ```twig What kind of migration is this? This answer was restored from the saved session. Incremental migration One-time cutover How should the migration be verified? Two answers were already selected before the session was saved. Automated tests Type checking Manual review Anything else to carry over? Resume run ``` ### Conditional Items Mark an item `disabled` when it does not apply to the user's earlier answers: it is inert and navigation steps over it. ```twig Where should the agent run? The sandbox question only applies to cloud runs. On this machine In the cloud Which sandbox should the cloud run use? Preview Staging Fully isolated When should the agent ask for approval? Before every action Before destructive actions Never Start run ``` ### Navigation State Each `Questionnaire:Item` exposes `data-status`, so answered and skipped questions can be styled differently from unanswered ones. ```twig What may the agent modify? The dashed border becomes solid once this question is answered. Project files Tests only Configuration Which checks should the agent run? Skipping this question dims it instead. Tests Type checking Everything Confirm ``` ### Custom Progress Replace the content of `Questionnaire:Progress` to build a custom indicator. Elements marked `data-questionnaire-target="progressStep"` receive `data-active`, and `progressCurrent` / `progressTotal` receive the step numbers. ```twig Checkpoint 1 of 3 How large is the change? Small patch Feature-sized change Cross-package change How should commits be organized? Single commit Logical commits Squash before review How should the work be delivered? Patch only Committed locally Push a review branch Finish plan ``` ### Animated Items Animate the active item with `data-[active=true]` while progress and navigation stay stationary. ```twig What should the agent do? Each item fades and slides in as it becomes active. Implement the change Debug the failure Review the diff How much should be reviewed? The touched files The complete diff A manual walkthrough How should the result be delivered? A short summary A review branch Start work ``` ### Card Compose `Questionnaire` with `Card` slots while keeping the question title and description semantic. ```twig What should the agent work on? Choose the task that should be handled next. Fix the failing tests Refactor the data layer Update the integration guide What should the final handoff include? Pick the level of detail needed for review. Summary only Summary and changed files Full review handoff Create task ``` ### Dialog Compose `Questionnaire` inside a `Dialog` while keeping cancellation and dismissal owned by the dialog. ```twig
Open clarification How much should the agent change? Answer before the agent continues. One component One feature The whole workspace Which tests should run afterwards? The dialog keeps owning dismissal. Targeted tests Package suite Continue
``` ### Server-Driven Flow Set `:interactive="false"` when the server owns the flow, as with a Symfony [form flow](https://symfony.com/doc/current/form/form_flow.html). The Stimulus controller is not registered at all, so nothing on the client moves the user between questions, validates an answer, or shows and hides the navigation: the server renders the current step, its errors, and the buttons it wants. In this mode `defaultItem` selects which `Questionnaire:Item` is rendered visible; leave it unset and every item renders, so the usual approach is to output only the current step. `Questionnaire:Progress` takes `current` and `total` to keep the progressbar accurate, `Questionnaire:Error` renders whenever you output it, and `Questionnaire:Previous`, `Questionnaire:Skip` and `Questionnaire:Next` become `type="submit"` so a `name` and `value` tell the server which way to go. `Questionnaire` renders a `form` by default. Set `as="div"` to nest it inside a form you already render, and let that outer form own the method, the action and the hidden fields. ```twig
How should the migration be verified? The server validated this step and sent you back to it. Automated tests Type checking Manual review Choose how the migration should be verified.
``` #### With a Symfony form flow A flow type declares its steps and adds a navigator, which supplies the `back`, `next`, `finish` and `reset` buttons: ```php use Symfony\Component\Form\Flow\AbstractFlowType; use Symfony\Component\Form\Flow\FormFlowBuilderInterface; use Symfony\Component\Form\Flow\Type\NavigatorFlowType; class MigrationType extends AbstractFlowType { public function buildFormFlow(FormFlowBuilderInterface $builder, array $options): void { $builder->addStep('change', ChangeType::class); $builder->addStep('verification', VerificationType::class); $builder->add('navigator', NavigatorFlowType::class); } } ``` The controller renders the form of the current step: ```php $flow = $this->createForm(MigrationType::class, $migration); $flow->handleRequest($request); if ($flow->isSubmitted() && $flow->isValid() && $flow->isFinished()) { return $this->redirectToRoute('migration_success'); } return $this->render('migration.html.twig', ['form' => $flow->getStepForm()]); ``` The `form_flow_*()` functions read the flow cursor, and the `field_*()` functions give each field its submitted name, label, choices and errors. Calling `field_name()` also marks the field as rendered, so `form_end()` still emits the CSRF token and the flow's hidden fields without duplicating anything you laid out by hand: ```twig {# `form` is the step form returned by `$flow->getStepForm()` #} {% set step = form_flow_current_step(form) %} {{ form_start(form) }} {{ field_label(form[step]) }} {{ field_help(form[step]) }} {% for choice in field_choices(form[step]) %} {{ choice.label }} {% endfor %} {% for error in field_errors(form[step]) %} {{ error }} {% endfor %} {% if form_flow_can_move_back(form) %} {{ field_label(form.navigator.back) }} {% endif %} {% if form_flow_can_move_next(form) %} {{ field_label(form.navigator.next) }} {% endif %} {% if form_flow_is_last_step(form) %} {{ field_label(form.navigator.finish) }} {% endif %} {{ form_end(form) }} ``` The navigator only exposes the buttons that apply to the current step, so each one is guarded rather than rendered unconditionally: `form_flow_can_move_back()` for back, `form_flow_can_move_next()` for next, and `form_flow_is_last_step()` for finish. `formnovalidate` on the back button lets the user return to the previous step without tripping HTML validation on the step they are leaving. `form_flow_step_index()` is zero-based, hence the `+ 1` for the 1-based `current` prop. The other cursor helpers are `form_flow_steps()`, `form_flow_next_step()`, `form_flow_previous_step()`, `form_flow_first_step()`, `form_flow_last_step()`, `form_flow_is_first_step()` and `form_flow_is_last_step()`. Two things to watch: - `field_name()` returns the field's full name, which for a `multiple` choice field already ends in `[]`, and `Questionnaire:Item` appends `[]` of its own when you set `multiple`. Strip one of them: `name="{{ field_name(form[step])|replace({'[]': ''}) }}" multiple`. - A `Questionnaire:Input` shares the name of its item so the controller can treat it as an alternative answer. Without the controller that empty input is still submitted and shadows the selected choice, so give it its own name here: ``. ### RTL To enable RTL support, set the `dir="rtl"` attribute on the root element. ```twig
ما الذي يجب أن يعمل عليه الوكيل؟ اختر المهمة التالية. إصلاح الاختبارات الفاشلة إعادة هيكلة طبقة البيانات تحديث دليل التكامل تأكيد על מה הסוכן צריך לעבוד? בחר את המשימה הבאה. תיקון הבדיקות שנכשלו שכתוב שכבת הנתונים עדכון מדריך האינטגרציה אישור
``` ## Accessibility - Each `Questionnaire:Item` renders a `
` and `Questionnaire:Title` renders its ``, so the choices are announced as a named group. Give every item a `Questionnaire:Title`. - An item that isn't the active one is rendered `hidden inert`, and an item marked `disabled` gets the native `disabled` attribute on its fieldset, so neither one is focusable or submitted. - `Questionnaire:Choice` is a `