Multi-Select — Input Controls

Minimal Example

{
  "id": "tags",
  "type": "multiselect",
  "label": "Tags",
  "width": "full",
  "settings": {
    "options": [
      { "value": "urgent", "label": "Urgent" },
      { "value": "review", "label": "Needs Review" },
      { "value": "blocked", "label": "Blocked" },
      { "value": "done", "label": "Done" }
    ]
  },
  "binding": {
    "source": "$json",
    "path": "task.tags"
  }
}

// Stored value (if Urgent + Blocked selected): ["urgent", "blocked"]

Settings Reference

Setting	Type	Default	Description
`options`	Option[]	—	Static list: `[{ value, label, disabled? }]`
`optionsSource`	ApiSource	—	API configuration to load options dynamically
`maxSelections`	number	—	Maximum number of selections allowed
`minSelections`	number	—	Minimum required selections (for validation)
`searchable`	boolean	true	Enable type-to-filter search (on by default for multiselect)
`clearable`	boolean	true	Show × to clear all selections
`placeholder`	string	`"Select..."`	Placeholder shown when nothing is selected
`chipVariant`	`default` \| `outlined` \| `filled`	`filled`	Visual style of selected option chips
`groupBy`	string	—	Option property name to use as group header
`showSelectAll`	boolean	false	Show a "Select All" / "Clear All" button in the dropdown

Chip Display

Selected options appear as chips inside the input field. Each chip has an × remove button. When the number of chips overflows one line, the field expands vertically:

// Styling chip appearance:
{
  "id": "permissions",
  "type": "multiselect",
  "label": "Permissions",
  "settings": {
    "chipVariant": "outlined",
    "options": [
      { "value": "read", "label": "Read" },
      { "value": "write", "label": "Write" },
      { "value": "delete", "label": "Delete" },
      { "value": "admin", "label": "Admin" }
    ]
  }
}

Maximum Selections

Use maxSelections to limit how many options a user can pick. Options are greyed out once the limit is reached:

{
  "id": "preferred-categories",
  "type": "multiselect",
  "label": "Preferred Categories",
  "description": "Choose up to 3 categories",
  "settings": {
    "maxSelections": 3,
    "options": [
      { "value": "tech", "label": "Technology" },
      { "value": "finance", "label": "Finance" },
      { "value": "health", "label": "Healthcare" },
      { "value": "legal", "label": "Legal" },
      { "value": "hr", "label": "Human Resources" },
      { "value": "marketing", "label": "Marketing" }
    ]
  },
  "validation": {
    "required": true,
    "minSelections": 1,
    "maxSelections": 3
  }
}

Select All Pattern

For administrative forms where users often need to assign all permissions or all roles, enable the Select All button:

{
  "id": "roles",
  "type": "multiselect",
  "label": "Assigned Roles",
  "settings": {
    "showSelectAll": true,
    "searchable": true,
    "optionsSource": {
      "url": "/api/v1/roles",
      "valueKey": "roleId",
      "labelKey": "roleName"
    }
  }
}

Validation Rules

Rule	Type	Description
`required`	boolean	At least one selection must be made
`minSelections`	number	Minimum number of selections required
`maxSelections`	number	Maximum number of selections allowed

View Mode Rendering

In view and preview modes, the selected values are rendered as a comma-separated list of labels, or optionally as read-only chips:

// Edit mode: chip inputs (removable)
// View mode: "Urgent, Blocked" (comma-separated labels)

// To render as read-only chips in view mode:
{
  "id": "tags",
  "type": "multiselect",
  "settings": {
    "viewModeAs": "chips"   // default: "text"
  }
}

Full Example — Skill Assignment

{
  "id": "skills",
  "type": "multiselect",
  "label": "Skills",
  "description": "Select all skills that apply",
  "width": "full",
  "order": 5,
  "settings": {
    "searchable": true,
    "showSelectAll": false,
    "chipVariant": "filled",
    "options": [
      { "value": "js", "label": "JavaScript", "group": "Frontend" },
      { "value": "ts", "label": "TypeScript", "group": "Frontend" },
      { "value": "react", "label": "React", "group": "Frontend" },
      { "value": "csharp", "label": "C#", "group": "Backend" },
      { "value": "dotnet", "label": ".NET", "group": "Backend" },
      { "value": "sql", "label": "SQL", "group": "Database" },
      { "value": "psql", "label": "PostgreSQL", "group": "Database" }
    ]
  },
  "validation": {
    "required": true,
    "minSelections": 1
  },
  "binding": {
    "source": "$json",
    "path": "profile.skills"
  }
}

← Select Dropdown Next: Checkbox →