Configure a Select input

Last modified: June 18th, 2025

Permissions required

Members of all Default Permission Groups, or Custom Permission Groups with the site:file:write permission, can configure inputs in all locations in the configuration cascade. You can limit permission to specific locations in the configuration using file globs.

A Select input is an editing interface for selecting values from predefined lists. By configuring your inputs, you can customize the appearance and functionality for a better editing experience.

A screenshot of the Select input in the Data Editor.

These instructions assume that you know what type of Select input you want to configure, how you want to populate the values of your input, and where in the configuration cascade. For more information, please read our documentation on Select inputs, inputs in general, populating a Select input, and the configuration cascade.

To configure a Select input:

  1. Open your website files in your local development environment, or log in to CloudCannon and select the Site for which you want to configure your input.
  2. Navigate to the location in the configuration cascade where you want to configure your input. This can be the root of your CloudCannon Configuration File, within the collections_config.* key in your CloudCannon Configuration File, a Schema file, a markup file, or anywhere you configure a Structure.
  3. Identify the _inputs key, or create one at that level of the configuration cascade.
  4. Add an input name key for your input under the _inputs key (a.k.a., _inputs.*). We recommend naming your input something simple that indicates the function or context.
  5. Add the type key under your input name key, with the value select, multiselect, choice, or multichoice.
  6. (Optional.) Add any other general configuration keys (e.g., label, comment, context) under your input name key.
  7. Add the values key under _inputs.*.options to define how CloudCannon should populate your input. The value must be a fixed data set, Collection, or data file.
  8. (Optional.) Add any other specific configuration keys under _inputs.*.options (e.g., preview, value_key, allow_empty).

CloudCannon will now apply this input configuration to all markup files that use your input name key, without needing to save your configuration. This allows you to make changes to your input configuration and see those changes affect inputs live.

When you are happy with your input configuration, you must save your input configuration.

cloudcannon.config.yaml
copied
_inputs:
  blog_author:
    type: select
  blog_tags:
    type: multiselect
  priority:
    type: choice
  theme_color:
    type: multichoice

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This Select input is called blog_author.

The value of the type key determines the input type. This is a select input.

This Multiselect input is called blog_tags.

The value of the type key determines the input type. This is a multiselect input.

This Choice input is called priority.

The value of the type key determines the input type. This is a choice input.

This Multichoice input is called theme_color.

The value of the type key determines the input type. This is a multichoice input.

cloudcannon.config.json
copied
{
  "_inputs": {
    "blog_author": {
      "type": "select"
    },
    "blog_tags": {
      "type": "multiselect"
    },
    "priority": {
      "type": "choice"
    },
    "theme_color": {
      "type": "multichoice"
    }
  }
}

All inputs are defined under the _inputs key, regardless of where they are in the configuration cascade.

This Select input is called blog_author.

The value of the type key determines the input type. This is a select input.

This Multiselect input is called blog_tags.

The value of the type key determines the input type. This is a multiselect input.

This Choice input is called priority.

The value of the type key determines the input type. This is a choice input.

This Multichoice input is called theme_color.

The value of the type key determines the input type. This is a multichoice input.

When you add your input key name to a data or markup file, your configured Select input will appear in the Data Editor, Visual Editor, or Content Editor.

blog.md
copied

---
blog_author: Author A
blog_tags:
  - Opinion
  - Resource
priority: high
theme_color:
  - Blue
  - Green
---

Content goes here.

Input configuration options#

General configuration options are available for all input types. You can define the label, comment, and context box for your Select input, whether it is hidden or disabled, and how CloudCannon should handle configuration at multiple levels of the configuration cascade.

Specific configuration options for Select inputs include defining the list of input options, the appearance of option previews, whether you can create new values, whether the input can be empty, and how CloudCannon handles empty values. You can also add input validation to require a value, specify the minimum and maximum number of items, and whether CloudCannon should require unique values.

Here is an example of a Select input using some of the most commonly used configuration keys.

cloudcannon.config.yaml
copied
_inputs:
  blog_author:
    type: select
    label: Blog Author
    comment: Select the author for this blog post
    options:
      values:
        - name: Karen Key
          role: Project Manager
          profile_picture: /staff/karen_key.jpg
        - name: Holly James
          role: Engineering Lead
          profile_picture: /staff/holly_james.jpg
      value_key: name
      preview:
        text:
          - key: name
        image:
          - key: profile_picture
      required: true
cloudcannon.config.json
copied
{
  "_inputs": {
    "blog_author": {
      "type": "select",
      "label": "Blog Author",
      "comment": "Select the author for this blog post",
      "options": {
        "values": [
          {
            "name": "Karen Key",
            "role": "Project Manager",
            "profile_picture": "/staff/karen_key.jpg"
          },
          {
            "name": "Holly James",
            "role": "Engineering Lead",
            "profile_picture": "/staff/holly_james.jpg"
          }
        ],
        "value_key": "name",
        "preview": {
          "text": [
            {
              "key": "name"
            }
          ],
          "image": [
            {
              "key": "profile_picture"
            }
          ]
        },
        "required": true
      }
    }
  }
}

For a complete list of configuration keys available for inputs please read our inputs reference documentation.

These keys configure the appearance and functionality of Select inputs in CloudCannon.

allow_create — Boolean#

This key determines whether you are allowed to enter a new text value that does not appear in the data set. CloudCannon does not add new text values to the data set. Defaults to false.

allow_empty — Boolean#

This key toggles the presence of an empty option alongside the options listed under values. Defaults to true. When false, CloudCannon will use the first value in the data set by default.

This key has no effect on Multiselect inputs.

empty_type — string#

This key determines how CloudCannon handles an empty value. This key does not apply to existing empty values.

Value must be one of the following:

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

Available for Multiselect and Multichoice inputs.

preview — Object#

This key enables you to define the appearance of input values in the Data Editor or sidebar of the Visual or Content Editor. The following nested keys are available:

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

Defaults to:

cloudcannon.config.yml
copied
preview:
  text:
    - key: title
    - key: name
  icon:
    - key: icon

For more information about previews, please read our documentation on configuring card previews.

preview.text — Array, string or boolean#

This key determines the title text displayed for a value option. This key has no default, and has no effect unless the value option is an Object.

If set to false, no text is displayed.

preview.icon — Array, string or boolean#

This key determines the icon displayed for a value option. The value must match a name from the Material Icons list.

If set to false, no icon is displayed.

If image is defined, the image replace icon when loaded successfully.

Available for Choice and Multichoice inputs.

preview.image — array, string, or boolean#

This key determines the image displayed for a value option. This key has no default and, if the value option is an Object, falls back to thumbnail_image, thumbnail_image_path, image, and image_path in that order. If no image is found, icon is displayed instead.

If set to false, no image is displayed.

Available for Choice and Multichoice inputs.

values — Array, object or string#

This key defines which values are available for a Select or Multiselect input.

You must define this key for the Select or Multiselect input to function.

Value can be an array of options, or a string referencing a fixed data set, Collection, or data file.

This key has no default.

Show exampleHide example

In this example, CloudCannon will provide items in the posts Collection as values for the heathers_posts input. CloudCannon will also apply a filter, returning only files where the author structured data key is equal to "Heather".

cloudcannon.config.yaml
copied
_inputs:
  heathers_posts:
    type: multiselect
    label: Heather's Posts
    options:
      values: collections.posts[?(@.author == 'Heather')]
cloudcannon.config.json
copied
{
  "_inputs": {
    "heathers_posts": {
      "type": "multiselect",
      "label": "Heather's Posts",
      "options": {
        "values": "collections.posts[?(@.author == 'Heather')]"
      }
    }
  }
}
value_key — String or array of strings#

This key defines which key CloudCannon should use as the Select/Multiselect input value when a value option is an Object with multiple nested keys.

Defaults to ['id', 'uuid', 'path', 'title', 'name']. Has no effect unless values is an array of objects.

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

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

_inputs.*.options.required — Boolean#

This key toggles whether CloudCannon requires this Input to have a value. If set to true, CloudCannon will require you to enter a value to save your changes, or discard your unsaved changes.

By default, this key is false (i.e, CloudCannon does not require this Input to have a value).

This key is available for Array, Boolean, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

Show exampleHide example

In this example, we want to require our team to enter an author value for markup files with this Input.

cloudcannon.config.yaml
copied
_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true
cloudcannon.config.json
copied
{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true
      }
    }
  }
}
_inputs.*.options.max_items — Number#

This key defines the maximum number of items CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from adding more items to this Input. If the Input already contains more items, CloudCannon will require you to remove items until the Input contains a valid number to save your changes, or discard your unsaved changes.

Value can be any positive integer. If options.min_items is also configured, this key cannot be a lesser number.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

Show exampleHide example

In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of five array items.

cloudcannon.config.yaml
copied
_inputs:
  featured_posts:
    type: array
    options:
      min_items: 2
      max_items: 5
cloudcannon.config.json
copied
{
  "_inputs": {
    "featured_posts": {
      "type": "array",
      "options": {
        "min_items": 2,
        "max_items": 5
      }
    }
  }
}
_inputs.*.options.min_items — Number#

This key defines the minimum number of items CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from removing items from this Input below this value. If the Input already contains fewer items, CloudCannon will require you to add items until the Input contains a valid number to save your changes, or discard your unsaved changes.

Value can be any positive integer. If options.min_items is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Array and Multiselect or Multichoice Inputs.

Show exampleHide example

In this example, we want to add an array of filepaths to our homepage's featured_posts Input. This Input limits you to a maximum of two array items.

cloudcannon.config.yaml
copied
_inputs:
  featured_posts:
    type: array
    options:
      min_items: 2
      max_items: 5
cloudcannon.config.json
copied
{
  "_inputs": {
    "featured_posts": {
      "type": "array",
      "options": {
        "min_items": 2,
        "max_items": 5
      }
    }
  }
}
_inputs.*.options.max_length — Number#

This key defines the maximum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too long. If the Input already contains a longer value, CloudCannon will require you to remove characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any non-negative integer. If this key is set to 0, CloudCannon requires the Input to be empty. If options.min_length is also configured, this key cannot be a smaller number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.

Show exampleHide example

In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input limits you to a maximum of 125 characters.

cloudcannon.config.yaml
copied
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
cloudcannon.config.json
copied
{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}
_inputs.*.options.min_length — Number#

This key defines the minimum string length, in characters, that CloudCannon will allow in an Input. When configured, CloudCannon will warn you when an Input value is too short. If the Input already contains a shorter value, CloudCannon will require you to add characters until the Input contains a valid string to save your changes, or discard your unsaved changes.

Value can be any positive integer. If options.max_length is also configured, this key cannot be a greater number.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.

Show exampleHide example

In this example, we want our team to enter a blog description using the Rich Text seo_description Input. This Input requires a minimum of 25 characters.

cloudcannon.config.yaml
copied
_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25
cloudcannon.config.json
copied
{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}
_inputs.*.options.pattern — String#

This key defines a regular expression that the Input value must match. When configured, CloudCannon will require you to enter a value that matches the REGEX pattern. If the Input already contains an invalid value, CloudCannon will require you to enter a valid string to save your changes, or discard your unsaved changes.

Value must be a valid REGEX string.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs. To use this key in a Select Input, allow_create must be set to true.

Show exampleHide example

In this example, we want our team to add an email address to the contact_email Input using the correct email format.

cloudcannon.config.yaml
copied
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: Please use the format ___@___.__
cloudcannon.config.json
copied
{
  "_inputs": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}
_inputs.*.options.pattern_message — String#

This key defines the message that explains which regular expression an Input will accept. This key requires you to define options.pattern.

This key has no default.

This key is available for Code, Color, File, Select, Text, Rich Text, and URL Inputs.

Show exampleHide example

In this example, we prompt our team to use the correct email format in the contact_email Input using a pattern message.

cloudcannon.config.yaml
copied
_inputs:
  contact_email:
    type: email
    options:
      pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'
      pattern_message: Please use the format ___@___.__
cloudcannon.config.json
copied
{
  "_inputs": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}
_inputs.*.options.unique_on — String#

This key defines the JSON Path selector that CloudCannon should use to determine if the value of an Input is unique. When configured, CloudCannon will require the value of the Input to be unique compared to the value defined on the JSON Path. If the Input already contains a non-unique value, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.

Value must be a valid JSON Path.

This key has no default.

Show exampleHide example

In this example, CloudCannon will provide items in the posts Collection as values for the heathers_posts input. CloudCannon will also apply a filter, returning only files where the author structured data key is equal to "Heather".

cloudcannon.config.yaml
copied
_inputs:
  heathers_posts:
    type: multiselect
    label: Heather's Posts
    options:
      values: collections.posts[?(@.author == 'Heather')]
cloudcannon.config.json
copied
{
  "_inputs": {
    "heathers_posts": {
      "type": "multiselect",
      "label": "Heather's Posts",
      "options": {
        "values": "collections.posts[?(@.author == 'Heather')]"
      }
    }
  }
}

Valid values#

Here are some examples of valid values for Select inputs.

Empty/null value:

  • select_value:

Single value (Select/Choice):

  • select_value: option1
  • select_value: "option1"

Multiple values (Multiselect/Multichoice):

multiselect_value:
  - option1
  - option2
  - option3

Single value (Select/Choice):

  • select_value = "option1"

Multiple values (Multiselect/Multichoice):

  • multiselect_value = ["option1", "option2", "option3"]

Empty/null value:

  • "select_value": null

Single value (Select/Choice):

  • "select_value": "option1"

Multiple values (Multiselect/Multichoice):

{
                                                          "multiselect_value": [
                                                            "option1",
                                                            "option2",
                                                            "option3"
                                                          ]
                                                        }

Unconfigured Select inputs#

In some cases, CloudCannon can still detect a Select input even if you have not configured it.

CloudCannon will interpret any key as a Select input if the key name ends in the singular form of a fixed data set you have defined under _select_data (e.g., author or blog_author for the fixed data set authors).

blog.md
copied

---
blog_author: Karen Key
---

Blog content goes here.

cloudcannon.config.yaml
copied
_select_data:
  authors:
    - Karen Key
    - Billy Mills
    - Holly James
cloudcannon.config.json
copied
{
  "_select_data": {
    "authors": [
      "Karen Key",
      "Billy Mills",
      "Holly James"
    ]
  }
}

This behavior is convenient if you have simple inputs or do not want to configure inputs. It is also beneficial for new websites on CloudCannon where you have yet to create any CloudCannon-specific configuration.

We recommend configuring your inputs for greater control over their functionality and appearance.

Open in a new tab