---
title: "Matrix"
description: "Repeat several row questions across one shared set of column choices."
group: "Build forms"
order: 13
type: "reference"
parent: "fields"
keywords:
  - "matrix"
  - "grid"
  - "rows"
  - "columns"
updated: "2026-07-14"
---

The matrix field renders a row-by-column grid and stores one selected column ID for each answered row.

## Options and value shape

| Option | Type | Behavior |
| --- | --- | --- |
| `rows` | `SelectOption[]` | Declares the questions down the grid |
| `columns` | `SelectOption[]` | Declares the answer choices across the grid |
| `required` | `boolean` | Requires an answer for every row |

The stored object maps row IDs to column IDs, and unknown rows or columns are rejected. An optional matrix can contain only the rows the respondent answered.

## Add a matrix field

In the dashboard, select **Add block**, choose **Matrix**, then edit the rows and columns separately.

```ts
const experienceField = {
  id: "experience",
  kind: "matrix",
  label: "Rate each part of setup",
  rows: [
    { id: "docs", label: "Documentation" },
    { id: "install", label: "Installation" },
  ],
  columns: [
    { id: "poor", label: "Poor" },
    { id: "ok", label: "OK" },
    { id: "great", label: "Great" },
  ],
  required: true,
} as const;
```

## Related

- [Rating](/docs/fields/rating): Ask one compact score question.
- [Linear scale](/docs/fields/linear-scale): Add clear labels to a numbered range.
- [Custom UI](/docs/custom-ui): Replace the built-in grid while keeping the same value shape.