> ## Documentation Index
> Fetch the complete documentation index at: https://agents.candu.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Wizard UI patterns: choices, forms, and reviews
> Build guided AI workflows with structured choice lists, input forms, review screens, and confirmation prompts that feel native to your product.
Wizards are not limited to free-text chat. They can show structured UI when the user needs to choose, provide details, review generated content, confirm an action, or copy output.
Think of these as interaction patterns. The wizard decides when a pattern is useful, then renders the right UI for that moment.
Use chips, single-choice lists, or multi-choice lists when the answer shape is known.
Use forms when the wizard needs structured fields such as emails, URLs, numbers, dropdowns, or longer notes.
Use editable reviews, summaries, and confirmations before important actions run.
## Pattern Reference
| Pattern | Use when the wizard needs to... | Underlying primitive |
| ------------------- | ------------------------------------------------------ | ---------------------- |
| Chips | Offer a few short choices | `showChips` |
| Single choice | Have the user choose exactly one option | `showSelectCards` |
| Multiple choice | Have the user choose more than one option | `showSelectCards` |
| Form | Collect structured fields | `showShortForm` |
| Editable review | Let the user amend generated content | `showRefineAndConfirm` |
| Read-only summary | Recap values before a final step | `showSummary` |
| Code block | Show copyable text, JSON, or code | `showCode` |
| Action confirmation | Ask the user to approve a confirmation-required action | System-generated |
In most wizard instructions, describe the pattern you want rather than the raw tool call. For example: "Show chips for Activation, Education, and Expansion" is usually better than pasting a full JSON schema into a stage booster.
## Sequencing UI
A wizard can show more than one structured UI surface in sequence. This is useful when a task has several distinct questions or review moments.
For example, a gifting wizard might:
1. Show a single-choice list of gift options.
2. Show a form for recipient details.
3. Show an editable review of the message.
4. Show a final confirmation before sending.
The user experiences this as a guided flow: question 1 of 3, question 2 of 3, review, confirm. The wizard can still carry context forward between each step.
Use sequential UI when:
* Each question has a different shape.
* Later questions depend on earlier answers.
* You want the user to review generated content before the final action.
* A required field appears only after a lookup or policy check.
Avoid combining everything into one large form when the user needs to make a meaningful choice first.
## Chips
Use chips for a few short choices that do not need descriptions.
Good examples:
* Yes / no
* Shorter / warmer / more professional
* Retry / skip / cancel
* Activation / Education / Expansion
Tell the wizard:
```md theme={null}
Show chips for the goal: Activation, Education, Expansion.
```
Best practices:
* Keep labels short.
* Use chips for 2-8 options.
* Do not use chips when options need descriptions or images.
* For risky choices, use a list or review screen instead.
## Single Choice
Use single choice when the user should pick exactly one option from a small set.
Good examples:
* Pick a segment to test
* Choose one matching contact
* Select an invoice type
* Choose a troubleshooting path
* Confirm which existing project the user meant
Tell the wizard:
```md theme={null}
Show a single-choice list of matching segments. Use the segment name as the label and include a short description of the criteria when available.
```
Best practices:
* Keep the list short.
* Put the most likely option first.
* Include descriptions when labels alone could be ambiguous.
* Use explicit radio-style selection when the choice should not submit on first tap.
* Use an additional option for escape hatches such as "Other", "None of the above", or "Add new".
* For long lists with very short labels, chips can still work. Otherwise use a searchable form dropdown.
## Multiple Choice
Use multiple choice when the user can select more than one option before submitting.
Good examples:
* Select locations to enable
* Pick checklist items to include
* Choose fields to map
* Select actions to add to a wizard
Tell the wizard:
```md theme={null}
Show a multiple-choice list of locations. Let the user select one or more, then continue.
```
Best practices:
* Use multiple choice only when more than one answer is valid.
* Keep option labels scannable.
* Use descriptions when the consequence of each choice is not obvious.
* Use an additional option for escape hatches such as "Other", "None of the above", or "Add new".
* For long lists with very short labels, chips can still work. Otherwise use a searchable multi-select dropdown.
## Forms
Use forms when the wizard needs structured input from the user.
Good examples:
* Email address
* Name and occasion
* URL to test
* Endpoint path and method
* Campaign name, owner email, and message notes
* Dropdown selection from a larger list
Tell the wizard:
```md theme={null}
Show a form to collect campaign name, owner email, and message notes. Campaign name and owner email are required. Message notes can be a longer text field.
```
Best practices:
* Ask for related fields together instead of one turn at a time.
* Use email fields for email addresses.
* Use number fields for numeric inputs.
* Use textarea fields for prose.
* Use code fields when the user needs to provide JSON, YAML, markdown, or configuration.
* Use searchable dropdowns for long known lists.
* Label fields by what the user should enter, not by what the system will do with it.
## Editable Review
Use editable review when the wizard has generated content and the user should inspect or amend it before continuing.
Good examples:
* Review an email draft
* Edit generated instructions
* Confirm a message before sending
* Tune an action description before saving
* Review a generated prompt before opening an editor
Tell the wizard:
```md theme={null}
Draft the message, then show an editable review screen. Let the user revise the message before continuing. Do not send until the user confirms.
```
Best practices:
* Use editable review after generation, not for initial data collection.
* Prefill the fields with the generated content.
* Wait for explicit confirmation before running the next write action.
* Do not auto-advance after a tone or content rewrite.
## Read-Only Summary
Use a read-only summary when the user needs to review final values but should not edit them in that surface.
Good examples:
* Gift name, recipient, and total cost
* Invoice client, line items, and total
* Segment name and criteria
* URL rule before updating a placement
* Quote details before submission
Tell the wizard:
```md theme={null}
Before creating the segment, show a read-only summary with the segment name, criteria, and matched user count if available.
```
Best practices:
* Include the values that matter for user trust.
* Do not show every internal field.
* Use editable review instead if the user should change values directly.
* Pair summaries with confirmation-required actions for creates, updates, deletes, sends, or submissions.
## Code Blocks
Use code blocks when the wizard needs to return copyable text, JSON, API details, or code.
Good examples:
* Installation snippet
* JSON schema
* cURL request
* Agent instruction block
* Markdown template
Tell the wizard:
```md theme={null}
Show the generated JSON schema as a copyable code block.
```
Best practices:
* Use code blocks for output the user should copy elsewhere.
* Use a form with a code field when collecting code from the user.
* Keep generated code self-contained.
## Action Confirmation
Action confirmation appears automatically when an action uses a confirmation-required execution policy.
Use this for actions that create, update, delete, send, submit, approve, or trigger an external effect. The user sees what will happen before anything changes.
Tell the wizard:
```md theme={null}
After the user reviews the summary, call the confirmation-required action. If the user declines, explain that nothing changed and ask how they want to adjust.
```
Best practices:
* Use Automatic for safe read actions.
* Use Confirm required for writes or external effects.
* Treat a declined confirmation as a valid user choice.
* Do not hide risky changes in chat text.
## Runtime Mapping
Most authors should describe the UI pattern they want. The runtime maps those patterns to primitives.
| Pattern | Primitive | Notes |
| ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Chips | `showChips` | Compact pill choices. No descriptions or thumbnails. |
| Single choice | `showSelectCards` | Set `multiSelect: false`. Use `showSelectAffordance: true` when the user should explicitly submit instead of tapping once. |
| Multiple choice | `showSelectCards` | Set `multiSelect: true`. Use `showSelectAffordance: true` to show checkbox affordances. |
| Form | `showShortForm` | Supports text, email, number, textarea, code, dropdown, searchable dropdown, and multi-select dropdown fields. |
| Editable review | `showRefineAndConfirm` | Uses the same field types as forms, but is for reviewing generated content. |
| Read-only summary | `showSummary` | Supports label-value pairs. Values can be strings or string arrays. |
| Code block | `showCode` | Read-only copyable text or code. |
| Action confirmation | System-generated | Appears when an action has Confirm required. |
For long option lists, prefer a searchable dropdown in a form over a long card list.
## Advanced Details
Use these details when writing low-level agent instructions or debugging a wizard runtime issue.
`showSelectCards` powers both single-choice and multiple-choice card lists.
| Behavior | Settings |
| ------------------------------ | --------------------------------------------------- |
| Immediate single choice | `multiSelect: false`, `showSelectAffordance: false` |
| Radio-style single choice | `multiSelect: false`, `showSelectAffordance: true` |
| Plain multiple choice | `multiSelect: true`, `showSelectAffordance: false` |
| Checkbox-style multiple choice | `multiSelect: true`, `showSelectAffordance: true` |
| Thumbnail grid | `presentation: "gridCards"` |
`verticalCards` is the default presentation. Use `gridCards` only when every option has `assetUrl`; otherwise the UI falls back to `verticalCards`.
Card options support optional `description`, `assetUrl`, `prefix`, and `selected` fields.
Use `prefix` only with `verticalCards`. If you use it, all options should use the same prefix type: `number`, `text`, or `icon`. Do not mix prefix types or add a prefix to only some options.
Use `selected: true` when re-showing a choice and you want an option to start selected. Put selected options at the start of the options array, keeping stable order within selected and unselected groups.
Use `additionalOption` for escape hatches such as "Other", "None of the above", or "Add new". Do not use it for free-text; collect free text with a form.
Forms support:
* Single-line text
* Email
* Number
* Textarea
* Code
* Dropdown
* Searchable dropdown
* Multi-select dropdown
Form fields are required by default unless marked optional.
`progressStage` advances to the next wizard step after the current step's completion criteria are satisfied.
`dismissModal` closes the wizard when it is running inside a modal shell. It is context-specific and should only be used after the task is complete or the user has been navigated to the next place.
`showCode` is read-only. Use it for generated output the user should copy.
To collect code from the user, show a form with a code field instead.
## Common Mistakes
The model already receives the runtime tool definitions. In most cases, tell the wizard which pattern to use and what content to show, rather than duplicating the full schema in the booster.
A wizard can only use the actions and UI patterns available in its current step. When you design or revise a step, check that the step has access to the data it needs and that the intended interaction pattern is supported there.
Tables are useful in docs, but they are usually a poor format for stage boosters. For agent instructions, prefer direct prose that keeps related conditions in the same sentence, such as "Return up to 12 gift options ranked best first, with the most relevant options first." Use line breaks sparingly when the relationship between ideas matters; a blank line can make two related instructions feel unrelated.
If the wizard needs the user to pick a known segment, contact, location, status, or action, use a list, chips, or dropdown. Free text creates unnecessary ambiguity.
Cards are best for short, meaningful choices. If the list is long, use a searchable dropdown.
If the wizard generated the content and the user is reviewing it, use editable review. Forms are for collecting input. Review screens are for confirming or amending generated output.
If the user is reviewing final values before a write action, use a read-only summary. If they need to change values, take them back to the previous collection or review step.
Only progress when the step's completion criteria are satisfied. If the wizard advances early, tighten the criteria or adjust the stage booster.
## Design Principle
The best wizard does not feel like a chatbot with occasional forms. It feels like a guided product workflow that uses conversation only where conversation is the right interface.
Use chat for intent, explanation, and recovery. Use structured UI for choices, forms, review, confirmation, and completion.