Not every choice fits in a text reply. When the assistant needs the user to pick an output format, a plan tier, or a movie genre, OptionList renders the options as selectable cards with single or multi-select behavior. The selection feeds back as a tool result, and the chosen option stays visible as a receipt. No free-text parsing required. **Role:** Decision. For choices that return to the assistant. See [Design Guidelines](/docs/design-guidelines) for how component roles work. ## Getting Started Run this once from your project root. Render `OptionList` in your UI with tool-compatible props.

```tsx import { OptionList } from "@/components/tool-ui/option-list"; export function Example({ payload, }: { payload: React.ComponentProps; }) { return ; } ```

Register this renderer so tool results display as `OptionList`. ```tsx "use client"; // Frontend tool (recommended for decision surfaces like Option List): // - The model calls the tool with SerializableOptionList props as the args // - Your UI calls addResult(selection) from onAction when actionId is "confirm" import { type Toolkit } from "@assistant-ui/react"; import { OptionList } from "@/components/tool-ui/option-list"; import { safeParseSerializableOptionList, SerializableOptionListSchema, } from "@/components/tool-ui/option-list/schema"; export const toolkit: Toolkit = { selectFormat: { description: "Let the user choose an output format.", parameters: SerializableOptionListSchema, render: ({ args, toolCallId, result, addResult }) => { const parsedArgs = safeParseSerializableOptionList({ ...args, id: args?.id ?? `format-selection-${toolCallId}`, }); if (!parsedArgs) { return null; } return result ? ( ) : ( { if (actionId === "confirm") { void addResult?.(selection); } }} /> ); }, }, }; ``` ## Key Features Radio buttons for one choice, checkboxes for many Set minimum and maximum selection counts Confirm, cancel, and custom footer buttons Shows only the chosen option(s) as a read-only record ## Receipt State Pass a `choice` prop to render this component in its receipt state. See [Receipts](/docs/receipts) for the pattern. The receipt shows only the selected option(s) with a checkmark. Unselected options and action buttons are hidden. ## Props void", }, onAction: { description: "Action handler with post-action selection state", type: "(actionId: string, value: string | string[] | null) => void | Promise", }, onBeforeAction: { description: "Action guard with current selection state", type: "(actionId: string, value: string | string[] | null) => boolean | Promise", }, }} /> ## Option Schema ## Accessibility - Uses a semantic listbox + option pattern (`role="listbox"` with `role="option"` on each option button) - Exposes selection state with `aria-selected` and multi-select intent with `aria-multiselectable` - Implements roving tab focus with keyboard navigation (`ArrowUp/ArrowDown`, `Home/End`, `Enter`/`Space`, `Escape`) - Keeps footer actions keyboard-accessible through native button semantics ## Related - [Approval Card](/docs/approval-card): binary yes/no for a single consequential action - [Preferences Panel](/docs/preferences-panel): structured settings with switches and toggles - [Question Flow](/docs/question-flow): multi-step guided decisions where each answer shapes the next

Tool UI