Choice matrix

Collect one or several answers for each row without losing the row context.

Preview

Installation

Install

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

Basic usage

123import { ChoiceMatrix } from "@/components/ui/choice-matrix";

<ChoiceMatrix selection="radio" columns={[{ id: "yes", label: "Yes" }]} rows={[{ id: "shipping", label: "Shipping" }]} defaultValue={{ shipping: "yes" }} aria-label="Shipping answers" />

Each row owns an independent answer. Use selection="radio" for one answer per row or selection="checkbox" when a row can contain several answers. Put the visible field label in Field, and pass stable id values for rows and columns.

Structures

Examples

Radio rows

Use one answer per row for a rating or comparison question.

Checkbox rows

Use several answers per row when more than one column can apply.

Empty, incomplete, and narrow rows

Pass an empty rows array for the empty state. required marks each row that has no answer, while invalid communicates an external validation result. The matrix keeps its minimum column context and scrolls horizontally when a narrow host cannot fit the supplied columns. The examples submit required radio and checkbox rows. Checkbox form data keeps all selected values in each row. Disabled rows or columns remain visible and cannot change.

API reference

ChoiceMatrix properties
Prop	Type	Description
`form`	`string`	External form ID for row controls.
`label`	`ReactNode`	Optional caption content. Field owns the visible question.
`selection`	`"radio" \| "checkbox"`	Chooses one value or several values per row.
`columns`	`readonly ChoiceMatrixColumn[]`	Stable column ids and visible labels.
`rows`	`readonly ChoiceMatrixRow[]`	Stable row ids, labels, and optional descriptions.
`value`	`ChoiceMatrixRadioValue \| ChoiceMatrixCheckboxValue`	Controlled row selections.
`defaultValue`	`ChoiceMatrixRadioValue \| ChoiceMatrixCheckboxValue`	Initial uncontrolled row selections.
`onValueChange`	`(value) => void`	Called with the complete row selection map after a change.
`name`	`string`	Form field prefix. Submitted controls use stable row and column ids.
`required`	`boolean`	Requires one selection in every row and exposes incomplete rows.
`invalid`	`boolean`	Marks the matrix as invalid when validation is owned by the caller.
`disabled`	`boolean`	Disables all rows and columns.

The component composes the canonical RadioGroup, CheckboxGroup, and their controls. Radio rows submit one value per row. Checkbox rows submit the selected column values for each row. Keyboard focus stays on the native Base UI control and the row and column names remain available to assistive technology.

Native div attributes and a div ref are supported on the root. Labels and business validation belong to the caller.