options

Description:

This key defines options that are specific to Multichoice Inputs.

Appears in:

└── _inputs
    └── *
        └── Multichoice Input
            └── options

_inputs
- *
  - Multichoice Input
    options

Type:

Object

Properties:

allow_emptyboolean#

⚠️ DEPRECATED: This key is deprecated. If you want to prevent empty values, we recommend setting _inputs.*.options.required to true instead.

This key toggles whether CloudCannon will accept empty values, and pre-select the first option if opened with an empty value.

Setting this key to true will allow CloudCannon to accept empty values.

Show examplesHide examples

In this example, CloudCannon will accept empty values for a Select Input.

Copied to clipboard

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

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

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 array

Show examplesHide examples

In this example, we have configured how empty array values will be saved.

Copied to clipboard

_inputs:
  tags:
    type: array
    options:
      empty_type: array

{
  "_inputs": {
    "tags": {
      "type": "array",
      "options": {
        "empty_type": "array"
      }
    }
  }
}

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.

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"
      }
    }
  }
}

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.

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"
      }
    }
  }
}

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.

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"
      }
    }
  }
}

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.

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"
      }
    }
  }
}

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.

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"
          }
        }
      ]
    }
  }
}

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

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"
      }
    }
  }
}

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.

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"
          }
        }
      ]
    }
  }
}

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

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

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 use 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."
      }
    }
  }
}

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.

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
    }
  ]
}

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.

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
    }
  ]
}

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.

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

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"
        ]
      }
    }
  }
}

viewstring#

This key defines how selected items are rendered.

Allowed values: card text gallery gallery-left

Examples:

In this example, we have configured Multichoice Input options including values.

Copied to clipboard

_inputs:
  categories:
    type: multichoice
    options:
      values:
        - technology
        - design
        - business

{
  "_inputs": {
    "categories": {
      "type": "multichoice",
      "options": {
        "values": [
          "technology",
          "design",
          "business"
        ]
      }
    }
  }
}

User Articles

User Guides

User Glossary

Developer Articles

Developer Guides

Developer Reference

`options`

Table of contents