Skip to content
Formspace Docs

Matrix Column Schema

Matrix column objects define the fields shown across each row in matrixdropdown and matrixdynamic questions.

Minimal Shape

Section titled “Minimal Shape”
{
  "name": "quantity",
  "title": "Quantity",
  "cellType": "text",
  "inputType": "number",
  "isRequired": true
}

Properties

Section titled “Properties”

name

Section titled “name”
  • Type: string
  • Required: Yes

Stored key for this column inside each matrix row value.

title

Section titled “title”
  • Type: string
  • Localizable: Yes

Visible column label.

cellType

Section titled “cellType”
  • Type: string
  • Allowed values: dropdown, checkbox, radiogroup, tagbox, text, comment, boolean, expression, rating, slider

Question type used inside cells for this column. Overrides the matrix-level cellType.

choices

Section titled “choices”
  • Type: choiceitem[]

Choices for dropdown, checkbox, radiogroup, or tagbox cells.

inputType

Section titled “inputType”
  • Type: string

Input type for text cells, for example text, number, email, or date.

expression

Section titled “expression”
  • Type: expression

Expression used by columns with cellType: "expression". Use row-scoped placeholders such as {row.quantity} and {row.unitPrice}.

isRequired

Section titled “isRequired”
  • Type: boolean

Requires a value in this column.

isUnique

Section titled “isUnique”
  • Type: boolean

Requires each row to provide a unique value in this column.

visibleIf

Section titled “visibleIf”
  • Type: condition

Controls column visibility.

totalType

Section titled “totalType”
  • Type: string
  • Allowed values: none, sum, count, min, max, avg

Aggregation method used to calculate this column’s footer total.

totalExpression

Section titled “totalExpression”
  • Type: expression

Expression used to calculate the column total. Overrides totalType.

totalFormat

Section titled “totalFormat”
  • Type: string

Display pattern for a column total. Use {0} as the total value placeholder.

totalDisplayStyle

Section titled “totalDisplayStyle”
  • Type: string
  • Allowed values: none, decimal, currency, percent

Number format used for the calculated total.

totalCurrency

Section titled “totalCurrency”
  • Type: string

Currency code used when totalDisplayStyle is currency.

totalMinimumFractionDigits

Section titled “totalMinimumFractionDigits”
  • Type: number

Minimum number of decimal digits for the total.

totalMaximumFractionDigits

Section titled “totalMaximumFractionDigits”
  • Type: number

Maximum number of decimal digits for the total.

totalAlignment

Section titled “totalAlignment”
  • Type: string
  • Allowed values: left, center, right, auto

Alignment for the calculated total.

width

Section titled “width”
  • Type: string

Column width in CSS units.

minWidth

Section titled “minWidth”
  • Type: string

Minimum column width in CSS units.

Example

Section titled “Example”
{
  "type": "matrixdynamic",
  "name": "lineItems",
  "title": "Line items",
  "columns": [
    { "name": "item", "title": "Item", "cellType": "text", "isRequired": true },
    { "name": "quantity", "title": "Quantity", "cellType": "text", "inputType": "number" },
    { "name": "unitPrice", "title": "Unit price", "cellType": "text", "inputType": "number" },
    {
      "name": "lineTotal",
      "title": "Line total",
      "cellType": "expression",
      "expression": "{row.quantity} * {row.unitPrice}",
      "totalType": "sum",
      "totalDisplayStyle": "currency",
      "totalCurrency": "USD"
    },
    {
      "name": "priority",
      "title": "Priority",
      "cellType": "dropdown",
      "choices": ["Low", "Medium", "High"]
    }
  ]
}