Configure a Select input

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 shows a text field and a dropdown menu.

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:

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.
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.
Identify the _inputs key, or create one at that level of the configuration cascade.
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.
Add the type key under your input name key, with the value select, multiselect, choice, or multichoice.
(Optional.) Add any other general configuration keys (e.g., label, comment, context) under your input name key.
Add the values key under _inputs.*.options to define how CloudCannon should populate your input. The value must be a fixed Dataset, Collection, or data file.
(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.

Copied to clipboard

_inputs:
  blog_author:
    type: select
  blog_tags:
    type: multiselect
  priority:
    type: choice
  theme_color:
    type: multichoice

{
  "_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.

Markdown

Copied to clipboard

---
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.

Copied to clipboard

_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

{
  "_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.

options.allow_createboolean#

This key toggles whether CloudCannon will allow new text values to be created at edit time.

Setting this key to true will allow new text values to be created at edit time.

Defaults to: false

Appears in: Select Input options, Multiselect Input options.

Show examplesHide examples

In this example, CloudCannon will allow users to add new values to a Select Input.

Copied to clipboard

_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
      allow_create: true

{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News"
        ],
        "allow_create": true
      }
    }
  }
}

options.empty_typestring#

This key defines how an 'empty' value will be saved. Does not apply to existing empty values.

Defaults to: null

Allowed values: null string

Appears in: Text Input options, Textarea Input options, Code Input options, Color Input options, URL Input options, Select Input options, Rich Text Input options, Date/Datetime Input options, Time Input options, File Input options, Choice Input options.

options.localestring#

This key defines the locale that CloudCannon uses to determine the number of words or graphemes in this Input, if you have max_words, min_words, max_graphemes, or min_graphemes configured.

options.max_graphemesnumber#

This key defines the maximum string length, in graphemes, 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.

options.max_graphemes_messagestring#

This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_graphemes.

options.max_itemsnumber#

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.

Appears in: Multiselect Input options, Multichoice Input options, Array Input options.

Show examplesHide examples

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.

Copied to clipboard

_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2

{
  "_inputs": {
    "featured_posts": {
      "type": "array",
      "options": {
        "max_items": 5,
        "max_items_message": "Cannot be more than 5",
        "min_items": 2,
        "min_items_message": "Cannot be less than 2"
      }
    }
  }
}

options.max_items_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.max_items.

This key requires you to define options.max_items.

This key has no default.

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

Appears in: Multiselect Input options, Multichoice Input options, Array Input options.

Show examplesHide examples

In this example, we prompt our team to enter a valid number of items using a custom message.

Copied to clipboard

_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2

{
  "_inputs": {
    "featured_posts": {
      "type": "array",
      "options": {
        "max_items": 5,
        "max_items_message": "Cannot be more than 5",
        "min_items": 2,
        "min_items_message": "Cannot be less than 2"
      }
    }
  }
}

options.max_lengthnumber#

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 examplesHide examples

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.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}

options.max_length_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.max_length.

This key requires you to define options.max_length.

This key has no default.

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

Show examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "max_length_message": "You are only allowed 125 characters.",
        "min_length": 25,
        "min_length_message": "Please write more than 25 characters."
      }
    }
  }
}

options.max_wordsnumber#

This key defines the maximum string length, in words, 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.

options.max_words_messagestring#

This key defines the message that explains which maximum string length an Input will accept. This key requires you to define `options.max_words.

options.min_graphemesnumber#

This key defines the minimum string length, in graphemes, 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.

options.min_graphemes_messagestring#

This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_graphemes.

options.min_itemsnumber#

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.

Appears in: Multiselect Input options, Multichoice Input options, Array Input options.

Show examplesHide examples

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.

Copied to clipboard

_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2

{
  "_inputs": {
    "featured_posts": {
      "type": "array",
      "options": {
        "max_items": 5,
        "max_items_message": "Cannot be more than 5",
        "min_items": 2,
        "min_items_message": "Cannot be less than 2"
      }
    }
  }
}

options.min_items_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.min_items.

This key requires you to define options.min_items.

This key has no default.

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

Appears in: Multiselect Input options, Multichoice Input options, Array Input options.

Show examplesHide examples

In this example, we prompt our team to enter a valid number of items using a custom message.

Copied to clipboard

_inputs:
  featured_posts:
    type: array
    options:
      max_items: 5
      max_items_message: Cannot be more than 5
      min_items: 2
      min_items_message: Cannot be less than 2

{
  "_inputs": {
    "featured_posts": {
      "type": "array",
      "options": {
        "max_items": 5,
        "max_items_message": "Cannot be more than 5",
        "min_items": 2,
        "min_items_message": "Cannot be less than 2"
      }
    }
  }
}

options.min_lengthnumber#

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 examplesHide examples

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.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      min_length: 25

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "min_length": 25
      }
    }
  }
}

options.min_length_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.min_length.

This key requires you to define options.min_length.

This key has no default.

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

Show examplesHide examples

In this example, we prompt our team to enter a valid number of characters using a custom message.

Copied to clipboard

_inputs:
  seo_description:
    type: markdown
    comment: Enter a brief description of this blog.
    options:
      max_length: 125
      max_length_message: You are only allowed 125 characters.
      min_length: 25
      min_length_message: Please write more than 25 characters.

{
  "_inputs": {
    "seo_description": {
      "type": "markdown",
      "comment": "Enter a brief description of this blog.",
      "options": {
        "max_length": 125,
        "max_length_message": "You are only allowed 125 characters.",
        "min_length": 25,
        "min_length_message": "Please write more than 25 characters."
      }
    }
  }
}

options.min_wordsnumber#

This key defines the minimum string length, in words, 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.

options.min_words_messagestring#

This key defines the message that explains which minimum string length an Input will accept. This key requires you to define options.min_words.

options.patternstring#

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.

If your REGEX string includes a \ character and CloudCannon Configuration File is a .yml file, use single quotes ' around the string to avoid a build error.

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 examplesHide examples

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

Copied to clipboard

_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": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}

options.pattern_flagsObject#

This key defines the flags (e.g. case-insensitive searching) for the regular expression set in options.pattern.

Show examplesHide examples

In this example, we have configured pattern flags for a text input to enable case-insensitive searching.

Copied to clipboard

_inputs:
  search_term:
    type: text
    options:
      pattern: ^[a-z]+$
      pattern_flags:
        ignore_case: true

{
  "_inputs": {
    "search_term": {
      "type": "text",
      "options": {
        "pattern": "^[a-z]+$",
        "pattern_flags": {
          "ignore_case": true
        }
      }
    }
  }
}

options.pattern_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.pattern.

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 examplesHide examples

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

Copied to clipboard

_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": {
    "contact_email": {
      "type": "email",
      "options": {
        "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
        "pattern_message": "Please use the format ___@___.__"
      }
    }
  }
}

options.picker_viewstring#

This key defines how CloudCannon should render selectable options in the dropdown of a Select Input.

Allowed values: card text gallery gallery-left

Appears in: Select Input options, Multiselect Input options, Choice Input options, Multichoice Input options.

Show examplesHide examples

In this example, we have configured a Select Input to display options using the card view.

Copied to clipboard

_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
        - Events
      picker_view: card

{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News",
          "Events"
        ],
        "picker_view": "card"
      }
    }
  }
}

options.requiredboolean#

This key toggles whether CloudCannon requires this Input to have a value.

Setting this key to true 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, Code, Color, Date and Time, File, Number, Object, Select and Multiselect, Text, Rich Text, and URL Inputs.

Defaults to: false

Appears in: Text Input options, Textarea Input options, Code Input options, Color Input options, Number Input options, Range Input options, URL Input options, Select Input options, Rich Text Input options, Date/Datetime Input options, Time Input options, File Input options, Multiselect Input options, Choice Input options, Multichoice Input options, Object Input options, Array Input options.

Show examplesHide examples

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

Copied to clipboard

_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true

{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true
      }
    }
  }
}

options.required_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.required.

This key requires you to define options.required.

This key has no default.

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

Show examplesHide examples

In this example, we prompt our team to enter an Input value using a required message.

Copied to clipboard

_inputs:
  author:
    type: text
    comment: Enter the name of the author for this blog post.
    options:
      required: true
      required_message: You are not allowed to leave this blank.

{
  "_inputs": {
    "author": {
      "type": "text",
      "comment": "Enter the name of the author for this blog post.",
      "options": {
        "required": true,
        "required_message": "You are not allowed to leave this blank."
      }
    }
  }
}

options.unique_onstring#

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.

This key is available for Array inputs.

Appears in: Multiselect Input options, Multichoice Input options, Array Input options.

Show examplesHide examples

In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.

Copied to clipboard

_inputs:
  related_articles:
    type: array
    options:
      unique_on: $.path

{
  "_inputs": {
    "related_articles": {
      "type": "array",
      "options": {
        "unique_on": "$.path"
      }
    }
  }
}

Copied to clipboard

related_articles:
  - path: /articles/first-article.md
    featured: true
  - path: /articles/second-article.md
    featured: false

{
  "related_articles": [
    {
      "path": "/articles/first-article.md",
      "featured": true
    },
    {
      "path": "/articles/second-article.md",
      "featured": false
    }
  ]
}

options.unique_on_messagestring#

This key defines a custom error message that explains why a value has failed the validation criteria from options.unique_on. This key requires you to define options.unique_on.

This key has no default.

This key is available for Array inputs.

Appears in: Multiselect Input options, Multichoice Input options, Array Input options.

Show examplesHide examples

In this example, we want our team to add article filepaths to the related_articles Input. This Input requires all the filepaths to be unique.

Copied to clipboard

_inputs:
  related_articles:
    type: array
    options:
      unique_on: $.path
      unique_on_message: The value for path must be different for all items.

{
  "_inputs": {
    "related_articles": {
      "type": "array",
      "options": {
        "unique_on": "$.path",
        "unique_on_message": "The value for path must be different for all items."
      }
    }
  }
}

Copied to clipboard

related_articles:
  - path: /articles/first-article.md
    featured: true
  - path: /articles/first-article.md
    featured: false

{
  "related_articles": [
    {
      "path": "/articles/first-article.md",
      "featured": true
    },
    {
      "path": "/articles/first-article.md",
      "featured": false
    }
  ]
}

options.value_keystring#

This key 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 checking for "id", "uuid", "path", "title", then "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.

Appears in: Select Input options, Multiselect Input options, Choice Input options, Multichoice Input options.

options.valuesDataset Reference Values|Text Array Values|Text Object Values|Object Array Values|Object Values#

This key 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).

Appears in: Select Input options, Multiselect Input options, Choice Input options, Multichoice Input options.

Show examplesHide examples

In this example, we have configured a Select Input with custom values to choose from.

Copied to clipboard

_inputs:
  category:
    type: select
    options:
      values:
        - Blog
        - News
        - Events

{
  "_inputs": {
    "category": {
      "type": "select",
      "options": {
        "values": [
          "Blog",
          "News",
          "Events"
        ]
      }
    }
  }
}

options.viewstring#

This key defines how selected items are rendered.

Allowed values: card text gallery gallery-left

Appears in: Select Input options, Multiselect Input options, Choice Input options, Multichoice Input options.

picker_previewObject#

This key defines the appearance of a Card when choosing an item to create. This uses preview as a base, and keys inside this object are overrides.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

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

Appears in: Select Input options, Multiselect Input options, Choice Input options, Multichoice Input options, [*], Snippet.

Show examplesHide examples

In this example, we have configured the appearance of Cards in inputs using the Structure staff when adding items.

Copied to clipboard

_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        picker_preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        picker_preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face

{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

previewObject#

This key defines the appearance of a Card.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

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

Appears in: Select Input options, Multiselect Input options, Choice Input options, Multichoice Input options, Object Input options, [*], schemas.*, collections_config.*, Snippet.

Show examplesHide examples

In this example, we have configured the appearance of file Cards in the Collection browser.

Copied to clipboard

collections_config:
  blog:
    preview:
      text:
        - key: title
      subtext:
        - key: author
      icon: edit_note
      icon_color:
        - key: color
        - '#ff0000'
      image:
        - key: image
      metadata:
        - template:
            - url
        - icon: event
          text:
            - template: Published on {date|date_long}
      gallery:
        - key: featured_image

{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          }
        ],
        "subtext": [
          {
            "key": "author"
          }
        ],
        "icon": "edit_note",
        "icon_color": [
          {
            "key": "color"
          },
          "#ff0000"
        ],
        "image": [
          {
            "key": "image"
          }
        ],
        "metadata": [
          {
            "template": [
              "url"
            ]
          },
          {
            "icon": "event",
            "text": [
              {
                "template": "Published on {date|date_long}"
              }
            ]
          }
        ],
        "gallery": [
          {
            "key": "featured_image"
          }
        ]
      }
    }
  }
}

In this example, we have configured the appearance of Cards in inputs using the Structure staff.

Copied to clipboard

_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face

{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}

preview.iconArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the icon displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, text string, that results in one of Google's Material Symbols. When multiple entries are provided, CloudCannon will use them in order as fallback options.

For Cards in the Collection Browser, this key defaults to the value of collections_config.*.icon. Otherwise, this key has no default.

Appears in: preview, metadata[*], gallery, picker_preview.

Show examplesHide examples

In this example, we have configured the icon for Cards in the blog Collection to use the edit_note icon.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon: edit_note

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon": "edit_note"
      }
    }
  }
}

In this example, we have configured the icon for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of logo first, then fall back to the edit_note icon.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon:
        - key: logo
        - edit_note

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon": [
          {
            "key": "logo"
          },
          "edit_note"
        ]
      }
    }
  }
}

preview.icon_background_colorArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the background color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.

Appears in: preview, metadata[*], gallery, picker_preview.

Show examplesHide examples

In this example, we have configured the icon background color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of bg_color first, then fall back to the static hex color value.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon_background_color:
        - key: bg_color
        - text: '#f0f0f0'

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon_background_color": [
          {
            "key": "bg_color"
          },
          {
            "text": "#f0f0f0"
          }
        ]
      }
    }
  }
}

preview.icon_colorArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the color of the icon displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Color values can be hex codes (e.g., #ff0000), CSS color names, or reference a data key that contains a color value.

Appears in: preview, metadata[*], gallery, picker_preview.

Show examplesHide examples

In this example, we have configured the icon color for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of color first, then fall back to the static hex color value.

Copied to clipboard

collections_config:
  blog:
    preview:
      icon_color:
        - key: color
        - text: '#ff0000'

{
  "collections_config": {
    "blog": {
      "preview": {
        "icon_color": [
          {
            "key": "color"
          },
          {
            "text": "#ff0000"
          }
        ]
      }
    }
  }
}

preview.imageArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the image displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string that results in a file path or URL to an image file. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Appears in: preview, metadata[*], gallery, picker_preview.

Show examplesHide examples

In this example, we have configured the image for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of featured_image first, then the {thumbnail} template, and finally fall back to the static text value.

Copied to clipboard

collections_config:
  blog:
    preview:
      image:
        - key: featured_image
        - template: '{thumbnail}'
        - text: default-image.jpg

{
  "collections_config": {
    "blog": {
      "preview": {
        "image": [
          {
            "key": "featured_image"
          },
          {
            "template": "{thumbnail}"
          },
          {
            "text": "default-image.jpg"
          }
        ]
      }
    }
  }
}

In this example, we have configured the image for Structure Cards to display the profile_picture key.

Copied to clipboard

_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          profile_picture: 
        preview:
          image:
            - key: profile_picture

{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "profile_picture": null
          },
          "preview": {
            "image": [
              {
                "key": "profile_picture"
              }
            ]
          }
        }
      ]
    }
  }
}

preview.textArray Preview Entry|Raw Text Preview Entry|False Preview Entry#

This key defines the main text displayed on Cards in the Collection browser, Structures, and Snippets.

The value can be an array or a single value, and reference a key, template, or text string. When multiple entries are provided, CloudCannon will use them in order as fallback options.

Appears in: preview, metadata[*], gallery, picker_preview.

Show examplesHide examples

In this example, we have configured the main text for Cards in the blog Collection with an array of values to provide fallback options. CloudCannon will use the value of title first, then the {name} template, and finally fall back to the static text value.

Copied to clipboard

collections_config:
  blog:
    preview:
      text:
        - key: title
        - template: '{name}'
        - text: Untitled

{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          },
          {
            "template": "{name}"
          },
          {
            "text": "Untitled"
          }
        ]
      }
    }
  }
}

In this example, we have configured the main text for Cards in the blog Collection to display the title key.

Copied to clipboard

collections_config:
  blog:
    preview:
      text:
        - key: title

{
  "collections_config": {
    "blog": {
      "preview": {
        "text": [
          {
            "key": "title"
          }
        ]
      }
    }
  }
}

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#

When the Infer Select values from input key flag is enabled, 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 Dataset you have defined under _select_data (e.g., author or blog_author for the fixed Dataset authors).

Markdown

Copied to clipboard

---
blog_author: Karen Key
---

Blog content goes here.

Copied to clipboard

_select_data:
  authors:
    - Karen Key
    - Billy Mills
    - Holly James

{
  "_select_data": {
    "authors": [
      "Karen Key",
      "Billy Mills",
      "Holly James"
    ]
  }
}

CloudCannon no longer infers Select inputs by default, as the detection method for single and plural key names did not respect more complex plural suffixes (e.g., "-es") or non-English words.

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

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

Configure a Select input

On this page

Input configuration options#

Valid values#

Unconfigured Select inputs#

Related Resources

Configure a Select input

On this page

Input configuration options#

Valid values#

Unconfigured Select inputs#

Related Resources

What are inputs?

What is a Select input?

What is the Data Editor?