Portal Community
Atlas Forms

Select Dropdown

The select type renders a single-selection dropdown. Options can be defined statically in the schema or loaded from an API. The control supports search filtering, option grouping, custom rendering, and dynamic option filtering based on other field values.

Minimal Example

{
  "id": "status",
  "type": "select",
  "label": "Status",
  "required": true,
  "width": "half",
  "settings": {
    "options": [
      { "value": "active", "label": "Active" },
      { "value": "inactive", "label": "Inactive" },
      { "value": "pending", "label": "Pending Review" }
    ]
  },
  "binding": {
    "source": "$json",
    "path": "record.status"
  }
}

Settings Reference

SettingTypeDefaultDescription
optionsOption[]—Static option list: [{ value, label, description?, disabled?, group? }]
optionsSourceApiSource—API configuration to load options dynamically
searchablebooleanfalseEnable type-to-filter search box in the dropdown
clearablebooleantrueShow × button to clear the selection
placeholderstring"Select..."Placeholder shown when no option is selected
groupBystring—Option property name to use as group header
valueKeystring"value"Property of each option to use as the stored value
labelKeystring"label"Property of each option to display as the label
minSearchLengthnumber0Minimum characters typed before search is applied

Option Object Format

interface SelectOption {
  value: string | number | boolean;
  label: string;
  description?: string;   // Secondary text shown below label in dropdown
  disabled?: boolean;     // Greyed out, cannot be selected
  group?: string;         // Groups options under a header
  icon?: string;          // Icon class or URL (if supported by theme)
}

Searchable Dropdown

For dropdowns with many options (10+), enable search to allow keyboard filtering:

{
  "id": "country",
  "type": "select",
  "label": "Country",
  "settings": {
    "searchable": true,
    "clearable": true,
    "placeholder": "Search countries...",
    "options": [
      { "value": "AU", "label": "Australia" },
      { "value": "BR", "label": "Brazil" },
      { "value": "CA", "label": "Canada" },
      { "value": "DE", "label": "Germany" },
      { "value": "FR", "label": "France" },
      { "value": "GB", "label": "United Kingdom" },
      { "value": "US", "label": "United States" }
      // ... 190+ more countries
    ]
  }
}

Grouped Options

{
  "id": "region",
  "type": "select",
  "label": "Region",
  "settings": {
    "options": [
      { "value": "us-east", "label": "US East", "group": "Americas" },
      { "value": "us-west", "label": "US West", "group": "Americas" },
      { "value": "eu-central", "label": "EU Central", "group": "Europe" },
      { "value": "eu-west", "label": "EU West", "group": "Europe" },
      { "value": "ap-southeast", "label": "AP Southeast", "group": "Asia Pacific" }
    ]
  }
}

// Rendered dropdown:
// — Americas —
//   US East
//   US West
// — Europe —
//   EU Central
//   EU West
// — Asia Pacific —
//   AP Southeast

API-Loaded Options

Load options from an API endpoint using optionsSource. The response must be an array of option objects or an array that can be mapped:

{
  "id": "department",
  "type": "select",
  "label": "Department",
  "settings": {
    "searchable": true,
    "optionsSource": {
      "url": "/api/v1/departments",
      "method": "GET",
      "valueKey": "id",
      "labelKey": "name",
      "params": {
        "tenantId": "{{context.tenantId}}"
      }
    }
  },
  "binding": {
    "source": "$json",
    "path": "employee.departmentId"
  }
}

Cascading Dropdowns

Filter the options of one select based on the value of another using params with template expressions:

// Step 1: Country selector
{
  "id": "country-id",
  "type": "select",
  "label": "Country",
  "settings": {
    "optionsSource": { "url": "/api/countries", "valueKey": "id", "labelKey": "name" }
  }
},

// Step 2: State/Province — filtered by country
{
  "id": "state-id",
  "type": "select",
  "label": "State / Province",
  "settings": {
    "optionsSource": {
      "url": "/api/states",
      "params": { "countryId": "{{values.country-id}}" }
    }
  },
  "visibilityRule": "values['country-id'] != null"
}

Disabled Options

{
  "id": "plan",
  "type": "select",
  "label": "Subscription Plan",
  "settings": {
    "options": [
      { "value": "free", "label": "Free", "description": "Up to 5 users" },
      { "value": "pro", "label": "Pro", "description": "Up to 50 users" },
      { "value": "enterprise", "label": "Enterprise", "description": "Unlimited users", "disabled": true }
    ]
  }
}
← Date + Time Picker Next: Multi-Select →