Matrix Choice Block - Flex Forms

The Matrix Choice block (MatrixChoiceField) allows you to group multiple related questions into a single, cohesive table. It is perfect for Likert scale surveys (e.g., “Rate the following aspects of our service from 1 to 5”) or bulk product selections.

Business Use Cases

Likert Surveys

“How satisfied are you with…” (Rows: Support, Product, Pricing | Cols: 1 to 5).

Bulk Order Forms

“Select your uniform sizes.” (Rows: Small, Medium, Large | Cols: Red, Blue, Green).

Feature Prioritization

“Rank these features by importance.” (Rows: Features | Cols: Must Have, Nice to Have, Do Not Build).

Configuration & Usage

Deploy to Canvas

Drag the Matrix Choice block from the Component Catalog onto the Canvas.

Define the Grid

Configure the Rows (the subjects or items being evaluated) and the Columns (the scale, answers, or rating options).

Choose the Mode

Decide if the user can pick only one answer per row (Radio mode) or multiple answers per row (Checkbox mode).

Technical Configuration Schemas

Grid Configuration
Visuals & UI
Advanced Locking Logic

array

required

The list of items to evaluate. Each row is defined as a key-value pair (e.g., cleanliness => “Cleanliness of the room”).

array

required

The scale or choices available for each row. Defined as a key-value pair (e.g., 5 => “Excellent”, 1 => “Poor”).

string

Defines the selection logic:

radio: Only one choice can be made per row.
checkbox: Multiple choices can be selected per row.

string

default:"md"

The visual size of the matrix table. Available options are sm, md, and lg.

string

The accent color used to highlight selected cells in the grid.

array

An array mapping column keys to Heroicon names. This displays an icon inside the column header (e.g., a star icon).

array

An array of row keys that are grayed out and unclickable.

array

An array of specific cells that cannot be selected (e.g., row_key:column_key).

array

A dynamic ruleset to lock a cell based on another answer within the matrix.

Data Payload Architecture

Because a Matrix is fundamentally a grid of questions, the data is saved as a JSON object where the keys are the rows, and the values are the selected columns.

{
  "submission_id": "sub_719",
  "data": {
    "hotel_survey": {
      "room_cleanliness": "5_stars",
      "staff_friendliness": "4_stars",
      "food_quality": "3_stars"
    }
  }
}

{
  "submission_id": "sub_719",
  "data": {
    "tshirt_order": {
      "size_large": ["color_red", "color_blue"],
      "size_small": ["color_green"]
    }
  }
}

Deep Dive: Complex Cell Locking

The Matrix Choice field supports complex, cell-level locking logic to prevent impossible combinations. If you are using a Matrix for an order form (Rows = Shirt Sizes, Columns = Colors), but you are out of stock for “Small Red” shirts, you can use the disabled_cells parameter to explicitly block the coordinate size_small:color_red. This prevents users from ordering inventory that doesn’t exist, maintaining data integrity without having to delete the row or column entirely.

Best Practices & FAQs

Width Limits

UX Rule: Do not add more than 7 columns to a Matrix. Anything beyond that becomes cognitively overwhelming for the user and visually cluttered on tablets, forcing horizontal scrolling.

​Business Use Cases

Likert Surveys

Bulk Order Forms

Feature Prioritization

​Configuration & Usage

​Technical Configuration Schemas

​Data Payload Architecture

​Deep Dive: Complex Cell Locking

​Best Practices & FAQs

Business Use Cases

Configuration & Usage

Technical Configuration Schemas

Data Payload Architecture

Deep Dive: Complex Cell Locking

Best Practices & FAQs