Select and Multiselect inputs

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

These inputs are for values from a fixed or dynamic set of options. Useful for linking across pages, collections and data sets.

Select#

Single value select input for values from a set of options.

Select inputs are shown for inputs configured with the type select, or for input keys matching or ending with the singular form of a data set key (e.g. color or my_color for data set colors).

Naming convention

copied

color: Red
ssg: jekyll
_select_data:
  colors:
    - Red
    - Blue
  ssgs:
    jekyll: Jekyll
    hugo: Hugo
    11ty: Eleventy

Naming convention

copied

{
  "color": "Red",
  "ssg": "jekyll",
  "_select_data": {
    "colors": [
      "Red",
      "Blue"
    ],
    "ssgs": {
      "jekyll": "Jekyll",
      "hugo": "Hugo",
      "11ty": "Eleventy"
    }
  }
}

Naming convention

copied

color = "Red"
ssg = "jekyll"

[_select_data]
colors = [ "Red", "Blue" ]

  [_select_data.ssgs]
  jekyll = "Jekyll"
  hugo = "Hugo"
  11ty = "Eleventy"

Input configuration

copied

spare_part: Bolt
_inputs:
  spare_part:
    type: select
    options:
      values:
        - Bolt
        - Nut
        - Gear

Input configuration

copied

{
  "spare_part": "Bolt",
  "_inputs": {
    "spare_part": {
      "type": "select",
      "options": {
        "values": [
          "Bolt",
          "Nut",
          "Gear"
        ]
      }
    }
  }
}

Input configuration

copied

spare_part = "Bolt"

[_inputs.spare_part]
type = "select"

  [_inputs.spare_part.options]
  values = [ "Bolt", "Nut", "Gear" ]

Multiselect#

Multiple value select input for values from a set of options.

Multiselect inputs are shown for inputs configured with the type multiselect, or for input keys matching or ending with a data set key (e.g. colors or my_colors for data set colors).

Naming convention

copied

colors:
  - Red
ssgs:
  - hugo
  - 11ty
_select_data:
  colors:
    - Red
    - Blue
  ssgs:
    jekyll: Jekyll
    hugo: Hugo
    11ty: Eleventy

Naming convention

copied

{
  "colors": [
    "Red"
  ],
  "ssgs": [
    "hugo",
    "11ty"
  ],
  "_select_data": {
    "colors": [
      "Red",
      "Blue"
    ],
    "ssgs": {
      "jekyll": "Jekyll",
      "hugo": "Hugo",
      "11ty": "Eleventy"
    }
  }
}

Naming convention

copied

colors = [ "Red" ]
ssgs = [ "hugo", "11ty" ]

[_select_data]
colors = [ "Red", "Blue" ]

  [_select_data.ssgs]
  jekyll = "Jekyll"
  hugo = "Hugo"
  11ty = "Eleventy"

Input configuration

copied

spare_parts:
  - Bolt
_inputs:
  spare_parts:
    type: multiselect
    options:
      values:
        - Bolt
        - Nut
        - Gear

Input configuration

copied

{
  "spare_parts": [
    "Bolt"
  ],
  "_inputs": {
    "spare_parts": {
      "type": "multiselect",
      "options": {
        "values": [
          "Bolt",
          "Nut",
          "Gear"
        ]
      }
    }
  }
}

Input configuration

copied

spare_parts = [ "Bolt" ]

[_inputs.spare_parts]
type = "multiselect"

  [_inputs.spare_parts.options]
  values = [ "Bolt", "Nut", "Gear" ]

Choice#

Segmented controls input for selecting a single value from a set of options. Functionally equivalent to a Select input.

Choice inputs are shown for inputs configured with the type choice.

Input configuration

copied

spare_part: Bolt
_inputs:
  spare_part:
    type: choice
    options:
      values:
        - Bolt
        - Nut
        - Gear

Input configuration

copied

{
  "spare_part": "Bolt",
  "_inputs": {
    "spare_part": {
      "type": "choice",
      "options": {
        "values": [
          "Bolt",
          "Nut",
          "Gear"
        ]
      }
    }
  }
}

Input configuration

copied

spare_part = "Bolt"

[_inputs.spare_part]
type = "choice"

  [_inputs.spare_part.options]
  values = [ "Bolt", "Nut", "Gear" ]

Multichoice#

Segmented controls input for selecting multiple values from a set of options. Functionally equivalent to a Multiselect input.

Multichoice inputs are shown for inputs configured with the type multichoice.

Input configuration

copied

spare_parts:
  - Bolt
  - Gear
_inputs:
  spare_parts:
    type: multichoice
    options:
      values:
        - Bolt
        - Nut
        - Gear

Input configuration

copied

{
  "spare_parts": [
    "Bolt",
    "Gear"
  ],
  "_inputs": {
    "spare_parts": {
      "type": "multichoice",
      "options": {
        "values": [
          "Bolt",
          "Nut",
          "Gear"
        ]
      }
    }
  }
}

Input configuration

copied

spare_parts = [ "Bolt", "Gear" ]

[_inputs.spare_parts]
type = "multichoice"

  [_inputs.spare_parts.options]
  values = [ "Bolt", "Nut", "Gear" ]

Options#

Select, Multiselect, Choice and Multichoice input options are configured with options inside an _inputs entry.

Input configuration

copied

items:
  - P1
_inputs:
  items:
    type: multiselect
    options:
      values: _select_data.inventory
      value_key: key
      preview:
        text:
          - key: display_name
_select_data:
  inventory:
    - key: P1
      display_name: Potion
      kind: consumable

Input configuration

copied

{
  "items": [
    "P1"
  ],
  "_inputs": {
    "items": {
      "type": "multiselect",
      "options": {
        "values": "_select_data.inventory",
        "value_key": "key",
        "preview": {
          "text": [
            {
              "key": "display_name"
            }
          ]
        }
      }
    }
  },
  "_select_data": {
    "inventory": [
      {
        "key": "P1",
        "display_name": "Potion",
        "kind": "consumable"
      }
    ]
  }
}

Input configuration

copied

items = [ "P1" ]

[_inputs.items]
type = "multiselect"

  [_inputs.items.options]
  values = "_select_data.inventory"
  value_key = "key"

[[_inputs.items.options.preview.text]]
key = "display_name"

[[_select_data.inventory]]
key = "P1"
display_name = "Potion"
kind = "consumable"

Select, Multiselect, Choice and Multichoice inputs have the following options available:

allow_create - Boolean#

Allows new text values to be created at edit time. Defaults to false.

allow_empty - Boolean#

Provides an empty option alongside the options provided by values. Defaults to true. Has no effect on multiselect inputs.

empty_type - string#

Multiselect and multichoice only.

Set how an 'empty' value will be saved. Does not apply to existing empty values. Can be one of the following:

array - an empty value for this input will be stored as [] (default).
null - an empty value for this input will be stored as a null value. This does not apply to TOML files.

preview - Object#

The preview definition for changing the way selected and available options are displayed. The options available for select-style inputs are:

text
icon (Choice/Multichoice only)
image (Choice/Multichoice only)

See the preview options documentation for detailed information on setting this option. Defaults to:

preview:
  text:
    - key: title
    - key: name
  icon:
    - key: icon

preview.text - Array, string or boolean#

Controls the main text shown for selected and available options. Has no effect unless the available or selected option is an object.

If the value is a primitive type, it is used directly.

If set to false, no text is displayed.

preview.icon - Array, string or boolean#

Controls the icon shown for selected and available options. Must match a Material Icon name.

If set to false, no icon is displayed.

Available to Choice and Multichoice inputs.

values - Array, object or string#

Defines the values available to choose from. Optional, defaults to fetching values from the naming convention (e.g. colors or my_colors for data set colors).

If set as an object or an array, the values are used directly.

If set as a string, the values are fetched from the referenced data set.

value_key - String or array of strings#

Defines the key used for mapping between saved values and objects in values. This changes how the input saves selected values to match. Defaults to ['id', 'uuid', 'path', 'title', 'name']. Has no effect unless values is an array of objects, the key is used instead for objects, and the value itself is used for primitive types.

If set as an array, keys are tried in order, until a non-empty value is found. If no keys are set for a value available, the value available is not included.

If set as a string, this key is used directly. Values available are excluded if they don't have a value for this key.

Sites created before 25 November 2021 have a different default for saving collection items in order to keep existing sites working. Create a new site, or use the Legacy Collections Value Key flag to update this for your site.

Data sets#

There are currently three sources for populating the options for a select or multiselect input:

Fixed data sets
Collection items
Data files

You can populate the available options for a Select, Multiselect, Choice or Multichoice input with a naming convention or set it explicitly with the input configuration options.values.

The saved value when an option is chosen in the editor depends on your data set and the value_key options.

Input configuration

copied

spare_part: Bolt
_inputs:
  spare_part:
    type: select
    options:
      values:
        - Bolt
        - Nut
        - Gear

Input configuration

copied

{
  "spare_part": "Bolt",
  "_inputs": {
    "spare_part": {
      "type": "select",
      "options": {
        "values": [
          "Bolt",
          "Nut",
          "Gear"
        ]
      }
    }
  }
}

Input configuration

copied

spare_part = "Bolt"

[_inputs.spare_part]
type = "select"

  [_inputs.spare_part.options]
  values = [ "Bolt", "Nut", "Gear" ]

In addition to having options.values contain values directly as seen above, you can refer to one of the three available sources. Here's how you can refer to a collection called bits_and_pieces:

Input configuration

copied

spare_part: Bolt
_inputs:
  spare_part:
    type: select
    options:
      values: collections.bits_and_pieces

Input configuration

copied

{
  "spare_part": "Bolt",
  "_inputs": {
    "spare_part": {
      "type": "select",
      "options": {
        "values": "collections.bits_and_pieces"
      }
    }
  }
}

Input configuration

copied

spare_part = "Bolt"

[_inputs.spare_part]
type = "select"

  [_inputs.spare_part.options]
  values = "collections.bits_and_pieces"

You can refer to fixed data sets and data files in a similar way by changing the prefix. For example: data.inventory and _select_data.spare_parts.

Fixed data sets#

Fixed data sets are defined in _select_data from the configuration cascade. Best suited when providing options that do not change as content is added or removed.

Collection items#

Collection items are files from your defined collections. Best suited when you need to select from pages or other content files created by team members.

Data files#

Data files are similar to collections, usually a reserved collection for your SSG. Best suited when you need the available options editable by team members.

Processed data file sets must be arrays of strings, or objects. The value saved is either the string for arrays, or the key for objects.

By default, CloudCannon does not read data files during your build. To use this option source, instruct CloudCannon to read it by defining your data.