Choice group

Choose one or several answers with composable rows and cards.

Preview

How should your assistant respond?

ConciseDetailedAsk first

Design guidance

Use Choice Group when all answers should be visible. Use Radio Group or Checkbox Group for simple controls with separate labels. Use Combobox when users need to search. Labels, descriptions, images and question validation stay in your application. Leading letter hints follow item order, including wrapped and disabled items. The first 26 choices support A–Z selection while the group has focus; later choices continue with AA/AB visual order hints. Standard radio and checkbox keyboard behavior stays available. Do not put links, buttons or text inputs inside a choice item.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/choice-group.json

Install fieldset or field as well when using the labelled example compositions.

Basic usage

123456import { ChoiceGroup, ChoiceItem } from "@/components/ui/choice-group";

<ChoiceGroup aria-label="Response style" defaultValue="concise">
  <ChoiceItem value="concise">Concise</ChoiceItem>
  <ChoiceItem value="detailed">Detailed</ChoiceItem>
</ChoiceGroup>

Structures

Examples

Simple answers

A short question with one answer.

Which model came first?

GPT-1GPT-2GPT-3

Multiple answers with a limit

A controlled set of permissions. Selected answers can be removed at the limit.

What can your assistant use?

Search the webFind current sources.Read project filesUse your workspace context.Run codeExecute code in a sandbox.

Choose up to 2. 1 selected.

Description cards

Use Content, Label and Description for a larger answer.

Focused reviewCheck the changed files and direct dependencies.Full reviewReview the project before a major release.

Media cards

Media accepts an image or your own preview. Give images useful alternative text.

ResearchCollect sources and insights. A document outline with a draft

WritingDraft and refine your work.

Without letter hints

Hide the leading hints in a compact settings surface.

ShortLong

Unavailable answers

Disable a specific answer without hiding it.

StandardAdvanced · unavailable

Validation feedback

Connect caller-owned error text with aria-describedby.

ConciseDetailed

Choose a response style to continue.

API reference

Prop	Type	Description
`type`	`"single" \| "multiple" = "single"`	Selects actual radio or checkbox semantics. It also determines the value type.
`value / defaultValue`	`string \| null (single); string[] (multiple)`	Controlled value or initial uncontrolled value. Uncontrolled form reset restores the default.
`onValueChange`	`(value) => void`	Receives the next selection with the type selected by type.
`max`	`number (multiple only)`	A non-negative whole-number cap. Selected answers remain removable.
`layout`	`"list" \| "grid" = "list"`	List rows or a responsive grid; control available width through native styles.
`showKeys`	`boolean = true`	Show leading A/B/C order hints and enable focused letter selection.
`name / form`	`string`	Forwarded to the semantic controls for native form submission.
`disabled / readOnly`	`boolean = false`	Blocks changes; disabled values are omitted from submission; readOnly values remain included.
`className / style / ref`	`native attributes`	Customize layout and connect the root. Content, labels and descriptions remain caller-owned.
`ChoiceItem / ChoiceGroup.Item`	`value: string; disabled?: boolean`	Semantic selectable surface. Content may contain Label, Description and Media. No nested interactive elements.
`Content / Label / Description / Media`	`native attributes / children / refs`	Layout and accessible text parts. Description stays separate from the label. Media accepts caller-owned React content.