Matrix / Grid Field

Collect structured responses using a grid of rows and columns, useful for rating multiple items or comparing options.

Overview

The matrix field type creates a grid layout where users select options for multiple items in one question. It works well for satisfaction surveys, skill assessments, and anywhere you need the same response type across several items. Matrix fields are validated by the SelectFieldValidator.

Basic Usage (Single Selection)

Use addMatrix() to create a matrix field. Define the rows (items to rate) in settings and the columns (rating options) via the options() method.

app/Actions/CreateSurveyForm.php

Rows and Columns

The rows setting defines the left-side labels (what you're rating), while options() defines the column headers (the rating scale). Users pick one option per row by default.

Multiple Selection Matrix

Set allow_multiple to true to let users pick multiple options per row. This switches the inputs from radio buttons to checkboxes.

app/Actions/CreateAssessmentForm.php

Available Settings

Setting	Type	Default	Description
`rows`	array	[]	Array of row labels. Each row represents an item to be rated.
`columns`	array	null	Array of column labels. If not set, uses the field's options array.
`allow_multiple`	boolean	false	Allow multiple selections per row (checkboxes) instead of single selection (radio buttons).

Validation

The SelectFieldValidator checks:

All required rows have at least one selection (if the field is required)
Selected values match the defined options
Multiple selections per row are only allowed when allow_multiple is true
Response structure is valid (object with row keys and value/array values)

Mobile Considerations

Matrix fields can be hard to use on small screens. Keep columns to 3-5 and row labels short for better mobile usability.

Common Use Cases

Customer satisfaction surveys (rating multiple aspects of service)
Employee performance evaluations
Product feature comparisons
Skills or competency assessments
Multi-item Likert scales
Priority ranking of features or topics

Response Data Structure

Matrix submissions are stored as an object where each key is a row identifier and the value is the selected option(s):

{
  "Customer Support": "Satisfied",
  "Product Quality": "Very Satisfied",
  "Delivery Speed": "Neutral",
  "Value for Money": "Satisfied"
}

For multiple selection matrices, each value is an array:

{
  "JavaScript": ["Intermediate", "Advanced"],
  "PHP": ["Beginner"],
  "Python": ["Advanced", "Expert"],
  "SQL": ["Intermediate"]
}

Signature Repeater