Matrix Field

ProNew

A grid question for surveys and ratings: one row per statement, one column per answer, as native radios (or checkboxes), with per-row errors, a required check and a layout that scrolls on narrow screens.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/matrix-field

Usage

Set multiple for "select all that apply" grids. The value is { [rowId]: column value }, or a list per row when multiple.

Props

Prop	Type	Description
`legend`, `description`	`ReactNode`	The question and a hint.
`rows`	`{ id, label }[]`	The statements.
`columns`	`{ value, label, ariaLabel? }[]`	The answers. Use `ariaLabel` when `label` is an icon or a number.
`value` / `onChange`	`MatrixValue`	Answers by row id.
`multiple`	`boolean`	Checkboxes.
`errors`	`Record<rowId, string>`	Row messages.

Accessibility

A fieldset with a legend holds a real table: column headers are th scope="col", row labels are th scope="row".
Each input is named "Row: Column" (for example "Speed: Poor"), so it makes sense out of the table context in a screen reader's form list.
The radios of a row share one name: Arrow keys move and select within the row, Tab goes to the next row. In multiple mode each box is its own tab stop.
A row error is shown next to the row label (role="alert"), and the row inputs get aria-invalid and aria-describedby.
On narrow screens the table scrolls horizontally inside its container instead of collapsing the structure.

Testing

The component ships with a Testing Library test (matrix-field.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/matrix-field

Usage

Set multiple for "select all that apply" grids. The value is { [rowId]: column value }, or a list per row when multiple.

Props

Prop	Type	Description
`legend`, `description`	`ReactNode`	The question and a hint.
`rows`	`{ id, label }[]`	The statements.
`columns`	`{ value, label, ariaLabel? }[]`	The answers. Use `ariaLabel` when `label` is an icon or a number.
`value` / `onChange`	`MatrixValue`	Answers by row id.
`multiple`	`boolean`	Checkboxes.
`errors`	`Record<rowId, string>`	Row messages.

Accessibility

A fieldset with a legend holds a real table: column headers are th scope="col", row labels are th scope="row".
Each input is named "Row: Column" (for example "Speed: Poor"), so it makes sense out of the table context in a screen reader's form list.
The radios of a row share one name: Arrow keys move and select within the row, Tab goes to the next row. In multiple mode each box is its own tab stop.
A row error is shown next to the row label (role="alert"), and the row inputs get aria-invalid and aria-describedby.
On narrow screens the table scrolls horizontally inside its container instead of collapsing the structure.

Testing

The component ships with a Testing Library test (matrix-field.test.tsx) that covers: its main behaviour, the keyboard path and the error or empty states.