---
url: /en/docs/fields/select.md
description: Choose single or multiple options in Sveltia CMS from predefined lists.
---

# Select Field

The Select field type allows users to choose one or more options from a predefined list within the CMS entry form.

::: tip Alternative for dynamic or boolean selects

The options in a Select field are meant to be a static list of a small number of choices defined in the configuration file. If you need dynamic options based on other collections, consider using the [Relation](/en/docs/fields/relation) field type instead. See also our [how-to guide](/en/docs/how-tos#using-entry-tags-for-categorization) on using entry tags for categorization.

For a simple true/false choice, consider using the [Boolean](/en/docs/fields/boolean) field type. A Select field with `true` and `false` option values is useful when the choice needs custom labels or a third state, such as `null`. See the [example](#boolean-and-null-values) below.

:::

## User Interface

### Editor

Radio buttons (single select) or checkboxes (multi select) for choosing options. If there are many entries, a dropdown with search functionality will be used instead. Use the `dropdown_threshold` option to customize when to switch to the dropdown UI.

For multi-select options with many entries, a tag input UI will be used instead of checkboxes to save space. Items can be reordered by dragging and dropping or using right/left arrow keys. Items can also be removed by clicking the ✕ icon on each item.

### Preview

A string or a list of strings representing the selected option(s).

## Data Type

It depends on the `options`. Usually a string or an array of strings, depending on whether the `multiple` option is set to `true` or `false`, but can also be a number, boolean or `null`, or an array of them, if the options are defined as such.

If the `required` option is set to `false` and no option is selected, the value will be an empty array for multi select. For single select, it will be an empty string if the options are strings, or `null` if they are numbers or booleans.

## Data Validation

* If the `required` option is set to `true`, at least one option must be selected. An option with the value `null` or an empty string counts as a selection.
* If the `multiple` option is enabled, the number of selected options must be between the `min` and `max` limits, if specified.
* If the [`pattern`](/en/docs/fields#pattern) option is provided, the selected option value must match the regular expression. For multi select, the selected values joined with commas, e.g. `foo,bar,baz`, must match instead: as with Decap CMS, the pattern is tested against the whole selection rather than against each value, so use `^[a-z]+(,[a-z]+)*$` rather than `^[a-z]+$` to accept lowercase values only. Numbers are tested as strings, and the pattern is not tested while nothing is selected.

## Options

In addition to the [common field options](/en/docs/fields#common-options), the Select field supports the following options:

### Required Options

#### `widget`

* **Type**: `string`
* **Default**: `string`

Must be set to `select`.

#### `options`

* **Type**: `array`

An array of options for the select field. Each option can be defined as a string, number, boolean or `null`, or as an object with `label` and `value` properties. These options will be presented to the user in the UI. An empty list or a list with duplicate values is reported as a config validation error on the login screen.

TOML doesn’t support `null`, so an option with the value `null` can’t be defined in a TOML configuration file. In a TOML data file, a field with the value `null` is omitted.

The following are valid examples of the `options` configuration:

::: code-group

```yaml [YAML]
options:
  - London
  - Paris
  - New York
```

```toml [TOML]
options = ["London", "Paris", "New York"]
```

```json [JSON]
{
  "options": ["London", "Paris", "New York"]
}
```

```js [JavaScript]
options: ['London', 'Paris', 'New York'],
```

:::

::: code-group

```yaml [YAML]
options: [1, 2, 3]
```

```toml [TOML]
options = [1, 2, 3]
```

```json [JSON]
{
  "options": [1, 2, 3]
}
```

```js [JavaScript]
options: [1, 2, 3],
```

:::

::: code-group

```yaml [YAML]
options:
  - { label: Toronto, value: YYZ }
  - { label: Vancouver, value: YVR }
  - { label: Montreal, value: YUL }
```

```toml [TOML]
[[options]]
label = "Toronto"
value = "YYZ"
[[options]]
label = "Vancouver"
value = "YVR"
[[options]]
label = "Montreal"
value = "YUL"
```

```json [JSON]
{
  "options": [
    { "label": "Toronto", "value": "YYZ" },
    { "label": "Vancouver", "value": "YVR" },
    { "label": "Montreal", "value": "YUL" }
  ]
}
```

```js [JavaScript]
options: [
  { label: 'Toronto', value: 'YYZ' },
  { label: 'Vancouver', value: 'YVR' },
  { label: 'Montreal', value: 'YUL' },
],
```

:::

::: code-group

```yaml [YAML]
options:
  - { label: Red, value: 1 }
  - { label: Green, value: 2 }
  - { label: Blue, value: 3 }
```

```toml [TOML]
[[options]]
label = "Red"
value = 1
[[options]]
label = "Green"
value = 2
[[options]]
label = "Blue"
value = 3
```

```json [JSON]
{
  "options": [
    { "label": "Red", "value": 1 },
    { "label": "Green", "value": 2 },
    { "label": "Blue", "value": 3 }
  ]
}
```

```js [JavaScript]
options: [
  { label: 'Red', value: 1 },
  { label: 'Green', value: 2 },
  { label: 'Blue', value: 3 },
],
```

:::

### Optional Options

#### `default`

* **Type**: `string`, `number`, `boolean`, `null`, an object with `label` and `value` properties, or an array of them
* **Default**: an empty string, `null` or `[]`

The default value for the field. Should be a string, number, boolean or `null` for single select, or an array of them for multi select, depending on the `multiple` option. An option can also be copied as is from the `options` list, as an object with `label` and `value` properties, in which case only its `value` is saved. A value that isn’t one of the `options`, or an array with `multiple` off and a single value with `multiple` on, is reported as a config validation error on the login screen.

#### `dropdown_threshold`

* **Type**: `integer`
* **Default**: `5`

The number of options at which to switch from radio buttons/checkboxes to a dropdown UI. If the number of options exceeds this threshold, a dropdown with search functionality will be used.

#### `multiple`

* **Type**: `boolean`
* **Default**: `false`

Whether to allow selecting multiple options.

#### `min`

* **Type**: `integer`
* **Default**: `0`

The minimum number of options required. This enables validation to ensure that users select at least this many options. Ignored if `multiple` is set to `false`.

#### `max`

* **Type**: `integer`
* **Default**: `Infinity`

The maximum number of options allowed. This enables validation to prevent users from selecting more than this many options. Ignored if `multiple` is set to `false`.

## Examples

### Single Select

The following example shows a basic single select field for choosing a country.

::: code-group

```yaml [YAML]
- name: country
  label: Country
  widget: select
  options:
    - USA
    - Canada
    - Mexico
```

```toml [TOML]
[[fields]]
name = "country"
label = "Country"
widget = "select"
options = ["USA", "Canada", "Mexico"]
```

```json [JSON]
{
  "fields": [
    {
      "name": "country",
      "label": "Country",
      "widget": "select",
      "options": ["USA", "Canada", "Mexico"]
    }
  ]
}
```

```js [JavaScript]
{
  fields: [
    {
      name: 'country',
      label: 'Country',
      widget: 'select',
      options: ['USA', 'Canada', 'Mexico'],
    },
  ],
}
```

:::

Output example when “Canada” is selected:

::: code-group

```yaml [YAML]
country: Canada
```

```toml [TOML]
country = "Canada"
```

```json [JSON]
{
  "country": "Canada"
}
```

:::

### Custom Labels and Values

The `options` can be defined with custom labels and values. The following example shows a select field for choosing a color with specific hex values.

::: code-group

```yaml [YAML]
- name: color
  label: Color
  widget: select
  options:
    - { label: Red, value: '#FF0000' }
    - { label: Green, value: '#00FF00' }
    - { label: Blue, value: '#0000FF' }
```

```toml [TOML]
[[fields]]
name = "color"
label = "Color"
widget = "select"
[[options]]
label = "Red"
value = "#FF0000"
[[options]]
label = "Green"
value = "#00FF00"
[[options]]
label = "Blue"
value = "#0000FF"
```

```json [JSON]
{
  "fields": [
    {
      "name": "color",
      "label": "Color",
      "widget": "select",
      "options": [
        { "label": "Red", "value": "#FF0000" },
        { "label": "Green", "value": "#00FF00" },
        { "label": "Blue", "value": "#0000FF" }
      ]
    }
  ]
}
```

```js [JavaScript]
{
  fields: [
    {
      name: 'color',
      label: 'Color',
      widget: 'select',
      options: [
        { label: 'Red', value: '#FF0000' },
        { label: 'Green', value: '#00FF00' },
        { label: 'Blue', value: '#0000FF' },
      ],
    },
  ],
}
```

:::

Output example when “Green” is selected:

::: code-group

```yaml [YAML]
color: '#00FF00'
```

```toml [TOML]
color = "#00FF00"
```

```json [JSON]
{
  "color": "#00FF00"
}
```

:::

### Boolean and Null Values

Option values can be booleans or `null`, which is useful when a choice needs custom labels or a third state. The following example shows a required field with “Yes”, “No” and “Not relevant” options, stored as `true`, `false` and `null`. Since `null` is one of the options, it counts as a selection and passes the `required` validation.

TOML doesn’t support `null`, so this example is only available in YAML, JSON and JavaScript.

::: code-group

```yaml [YAML]
- name: accessible
  label: Wheelchair Accessible
  widget: select
  options:
    - { label: 'Yes', value: true }
    - { label: 'No', value: false }
    - { label: Not relevant, value: null }
  default: null
```

```json [JSON]
{
  "fields": [
    {
      "name": "accessible",
      "label": "Wheelchair Accessible",
      "widget": "select",
      "options": [
        { "label": "Yes", "value": true },
        { "label": "No", "value": false },
        { "label": "Not relevant", "value": null }
      ],
      "default": null
    }
  ]
}
```

```js [JavaScript]
{
  fields: [
    {
      name: 'accessible',
      label: 'Wheelchair Accessible',
      widget: 'select',
      options: [
        { label: 'Yes', value: true },
        { label: 'No', value: false },
        { label: 'Not relevant', value: null },
      ],
      default: null,
    },
  ],
}
```

:::

Output example when “No” is selected:

::: code-group

```yaml [YAML]
accessible: false
```

```toml [TOML]
accessible = false
```

```json [JSON]
{
  "accessible": false
}
```

:::

::: tip Quote `Yes` and `No` in YAML

In YAML 1.1, unquoted `yes` and `no` can be read as booleans by some parsers, so it’s safer to quote them when they are used as labels, as shown above.

:::

### Multi Select with Limits

The following example shows a multi select field for choosing fruits, with a minimum of 1 and a maximum of 3 selections.

::: code-group

```yaml [YAML]
- name: fruits
  label: Fruits
  widget: select
  options:
    - Apple
    - Banana
    - Cherry
    - Date
  multiple: true
  min: 1
  max: 3
```

```toml [TOML]
[[fields]]
name = "fruits"
label = "Fruits"
widget = "select"
options = ["Apple", "Banana", "Cherry", "Date"]
multiple = true
min = 1
max = 3
```

```json [JSON]
{
  "fields": [
    {
      "name": "fruits",
      "label": "Fruits",
      "widget": "select",
      "options": ["Apple", "Banana", "Cherry", "Date"],
      "multiple": true,
      "min": 1,
      "max": 3
    }
  ]
}
```

```js [JavaScript]
{
  fields: [
    {
      name: 'fruits',
      label: 'Fruits',
      widget: 'select',
      options: ['Apple', 'Banana', 'Cherry', 'Date'],
      multiple: true,
      min: 1,
      max: 3,
    },
  ],
}
```

:::

Output example when “Apple” and “Cherry” are selected:

::: code-group

```yaml [YAML]
fruits:
  - Apple
  - Cherry
```

```toml [TOML]
fruits = ["Apple", "Cherry"]
```

```json [JSON]
{
  "fruits": ["Apple", "Cherry"]
}
```

:::