An Input is an editing interface for structured data in your data files or the front matter of markup files. Inputs appear in the Data Editor, as well as in the sidebar and data panels of the Content and Visual Editors.
This article covers all keys available in CloudCannon for configuring your Inputs. For more information, please read our documentation on Inputs in general and configuring your Inputs.
All Inputs options are configured within the _inputs key in your CloudCannon configuration file.
This key defines which inputs are available at a given level of the configuration cascade.
The following nested keys are available for each input inside _inputs:
typelabelcommentcontexthiddendisabledinstance_valuecascadeoptions
This key has no default. If undefined at higher levels of the configuration cascade, _inputs will default to any values configured in the CloudCannon configuration file.
Show exampleHide example
In this example, we have configured the date_created Date input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.
_inputs:
date_created:
type: datetime
label: Date of article creation
comment: UTC +0 timezone
context:
open: false
title: Help
icon: help
content: This date field will automatically populate when you create an article.
hidden: false
disabled: true
instance_value: NOW
cascade: true
options:
timezone: Etc/UTC
{
"_inputs": {
"date_created": {
"type": "datetime",
"label": "Date of article creation",
"comment": "UTC +0 timezone",
"context": {
"open": false,
"title": "Help",
"icon": "help",
"content": "This date field will automatically populate when you create an article."
},
"hidden": false,
"disabled": true,
"instance_value": "NOW",
"cascade": true,
"options": {
"timezone": "Etc/UTC"
}
}
}
}In this example, we have configured the blog_tags Multiselect input for the blog Collection.
collections_config:
blog:
_inputs:
blog_tags:
type: multiselect
label: Blog type
comment: Select a blog type
context:
open: false
title: Help
icon: help
content: |
Blog tags help our users filter articles by topic.
options:
values:
- Opinion
- Feature
- Resource
{
"collections_config": {
"blog": {
"_inputs": {
"blog_tags": {
"type": "multiselect",
"label": "Blog type",
"comment": "Select a blog type",
"context": {
"open": false,
"title": "Help",
"icon": "help",
"content": "Blog tags help our users filter articles by topic.\n"
},
"options": {
"values": [
"Opinion",
"Feature",
"Resource"
]
}
}
}
}
}
}General input configuration keys#
These keys configure the appearance and functionality of all inputs, regardless of type.
This key changes the type of editing interface used for an input. Each input has a different appearance and functionality, processes and accepts different types of values, and has different configuration options.
Value can be one of the following: auto, checkbox, switch, code, color, datetime, date, time, file, document, image, number, range, object, array, select, multiselect, choice, multichoice, text, textarea, email, html, markdown, or url.
If the type or value of an input is misconfigured, CloudCannon will display an orange warning instead of an input. If type is not configured for an input, CloudCannon will attempt to determine input type based on value or key name conventions.
This key has no default.
Show exampleHide example
In this example, we have configured the page_description input as a markdown Rich Text Input using the type key.
_inputs:
page_description:
type: markdown
options:
show_count: true
{
"_inputs": {
"page_description": {
"type": "markdown",
"options": {
"show_count": true
}
}
}
}In this example, we have configured the related_links input as a URL Input using the type key.
_inputs:
related_links:
type: url
comment: Reference a different page
{
"_inputs": {
"related_links": {
"type": "url",
"comment": "Reference a different page"
}
}
}This key changes the bold title text above an input.
By default, CloudCannon generate the value for from the input key name, in title case (e.g., page_title will become "Page Title").
This key changes the subtitle text above an input. CloudCannon supports a limited selection of Markdown formatting for the value of this key: links, bold, italic, subscript, superscript, and inline code.
This key has no default.
This key enables you to define a context box for extra information about an input. The following nested keys are available:
opentitleiconcontent(required)
This key has no default.
This key determines whether the context box is open to display text content by default.
By default, this key is false (i.e., closed).
This key determines the title of the context box.
By default, this key value is "Context".
This key determines which icon appears next to the context box title. The value must match an icon name from Google’s Material Icons list.
This key has no default.
This key determines the text content inside the context box. CloudCannon supports a limited selection of Markdown formatting for the value of this key: links, headings, bold, italic, subscript, superscript, and inline code.
This key is required for the context object to function.
This key has no default.
This key determines the configuration specific to each input type. If this key and nested keys are not defined, CloudCannon will use the default configuration options for that input type.
This key has no default.
For more information on options, please read our documentation on each input type.
This key toggles the visibility of an input in the Data Editor or the sidebar of the Visual or Content Editor. Hidden inputs are useful when you want an input to exist, but not be visible or editable outside of the Source Editor.
Value can be a boolean or a string. A boolean value of true will hide the input.
A string value can hide an input based on the value of another input. You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key follows the input naming convention where key names beginning with an underscore are hidden true.
This key toggles whether the value of an input is editable in the Data Editor or the sidebar of the Visual or Content Editor. Disabled inputs are useful if you want CloudCannon to display the input value, but prevent team members from editing the value outside of the Source Editor.
The value of this key can be a boolean or a string. A boolean value of true will prevent team members from editing the value.
A string value can prevent team members from editing an input based on the value of another input. You can reverse the value with a ! character at the beginning.
publishedhides an input when the sibling inputpublishedis truthy!publishedhides an input when the sibling inputpublishedis falsy
For reverse values in YAML files, the string should be in ' or " quotation marks.
By default, this key is false (i.e., team members can edit input values).
Show exampleHide example
In this example, we have configured the date_created Date input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.
_inputs:
date_created:
type: datetime
label: Date of article creation
comment: UTC +0 timezone
disabled: true
instance_value: NOW
options:
timezone: Etc/UTC
{
"_inputs": {
"date_created": {
"type": "datetime",
"label": "Date of article creation",
"comment": "UTC +0 timezone",
"disabled": true,
"instance_value": "NOW",
"options": {
"timezone": "Etc/UTC"
}
}
}
}This key determines whether an input is automatically populated with a value when the input is created. This occurs when creating a new file, or adding array items containing this input.
Valid values are UUID or NOW.
UUIDgenerates a uuidv4 key (extremely unlikely to generate duplicates), useful for identifying unique items (e.g.6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)NOWgenerates the current datetime in the Site's configured timezone
This key has no default.
This key determines whether CloudCannon should merge this input configuration with any matching, less specific configurations elsewhere in the configuration cascade.
The configuration cascade works by finding the most specific _inputs entry. Usually, once an option is found in the cascade, there's no reason to keep looking. When this key is true, the cascade continues looking and each entry found is merged.
This key allows you to define some options globally while using specific options for other keys at different levels of the cascade. For example, define a comment globally, but use collection-specific label for inputs in different collections. You can stop the cascade at any point in the configuration cascade by setting cascade to false.
By default, this key is true (i.e., merges all configurations for an input in the cascade).
Specific input configuration keys#
These keys configure the appearance and functionality for specific input types.
Input validation#
Input validation is a feature coming in 2025. These keys do not currently work in CloudCannon.
Have feedback about this proposed feature? Check out our post on the CloudCannon Community.
These keys configure how CloudCannon determines a valid value before you can save changes.
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, 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.
_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
}
}
}
}This key defines the maximum numerical value CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from entering a greater numerical value. If the Input already contains a greater numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes.
Value can be any integer. If options.min is also configured, this key cannot be a lesser number.
This key has no default.
This key is available for Number Inputs.
Show exampleHide example
In this example, we want to add a rating out of five for each article in our travel blog using the rating Input. This Input limits you to a maximum rating of five.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
min: 1
{
"_inputs": {
"rating": {
"type": "number",
"comment": "How highly did you rate this experience?",
"options": {
"max": 5,
"min": 1
}
}
}
}This key defines the minimum numerical value CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from entering a lesser numerical value. If the Input already contains a lesser numerical value, CloudCannon will require you to enter a valid value to save your changes, or discard your unsaved changes.
Value can be any integer. If options.max is also configured, this key cannot be a greater number.
This key has no default.
This key is available for Number Inputs.
Show exampleHide example
In this example, we want to add a rating out of five for each article in our travel blog using the rating Input. This Input limits you to a minimum rating of one.
_inputs:
rating:
type: number
comment: How highly did you rate this experience?
options:
max: 5
min: 1
{
"_inputs": {
"rating": {
"type": "number",
"comment": "How highly did you rate this experience?",
"options": {
"max": 5,
"min": 1
}
}
}
}This key defines the maximum file size in kB that CloudCannon will allow you to upload. When configured, CloudCannon will prevent you from saving your changes until you select a valid file size, or discard your unsaved changes.
Value can be any positive integer.
This key has no default.
This key is available for File and URL Inputs.
Show exampleHide example
In this example, we want our team to upload an image using the feature_image Input. This Input limits you to a maximum file size of 750 kB.
_inputs:
feature_image:
type: image
comment: Select the feature image for the banner.
options:
max_file_size: 750
{
"_inputs": {
"feature_image": {
"type": "image",
"comment": "Select the feature image for the banner.",
"options": {
"max_file_size": 750
}
}
}
}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 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.
_inputs:
featured_posts:
type: array
options:
min_items: 2
max_items: 5
{
"_inputs": {
"featured_posts": {
"type": "array",
"options": {
"min_items": 2,
"max_items": 5
}
}
}
}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 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.
_inputs:
featured_posts:
type: array
options:
min_items: 2
max_items: 5
{
"_inputs": {
"featured_posts": {
"type": "array",
"options": {
"min_items": 2,
"max_items": 5
}
}
}
}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.
_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
}
}
}
}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.
_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
}
}
}
}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.
_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 ___@___.__"
}
}
}
}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.
_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 ___@___.__"
}
}
}
}This key defines the earliest date and time, inclusive, that CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from selecting an earlier date and time. If the Input already contains an earlier date and time, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be in ISO8601 format. If options.end_before is also configured, this key cannot be a later date and time.
This key has no default.
This key is available for Date and Time Inputs.
Show exampleHide example
In this example, we want our team to enter the date and time of an event in the 2022_event Input. This Input will only allow dates on or after January 1st, 2022.
_inputs:
2022_event:
type: datetime
options:
start_from: 2022-01-01T00:00:00.000Z
end_before: 2023-01-01T00:00:00.000Z
{
"_inputs": {
"2022_event": {
"type": "datetime",
"options": {
"start_from": "2022-01-01T00:00:00.000Z",
"end_before": "2023-01-01T00:00:00.000Z"
}
}
}
}This key defines the date and time, exclusive, that CloudCannon will allow in an Input. When configured, CloudCannon will prevent you from selecting a later date and time. If the Input already contains a later date and time, CloudCannon will require you to change it to a valid value to save your changes, or discard your unsaved changes.
Value must be in ISO8601 format. If options.start_from is also configured, this key cannot be an earlier date and time.
This key has no default.
This key is available for Date and Time Inputs.
Show exampleHide example
In this example, we want our team to enter the date and time of an event in the 2022_event Input. This Input will only allow dates before January 1st, 2023.
_inputs:
2022_event:
type: datetime
options:
start_from: 2022-01-01T00:00:00.000Z
end_before: 2023-01-01T00:00:00.000Z
{
"_inputs": {
"2022_event": {
"type": "datetime",
"options": {
"start_from": "2022-01-01T00:00:00.000Z",
"end_before": "2023-01-01T00:00:00.000Z"
}
}
}
}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, beginning with $.
This key has no default.
This key is available for Array and Multiselect Inputs.
Show exampleHide example
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.
_inputs:
related_articles:
type: array
options:
unique_on: $.path
{
"_inputs": {
"related_articles": {
"type": "array",
"options": {
"unique_on": "$.path"
}
}
}
}
related_articles:
- path: /articles/first-article.md
featured: true
- path: /articles/second-article.md
featured: false