Migrating to input configuration

Last modified: July 15th, 2025

How you configure inputs in CloudCannon has changed. We recommend updating, but the previous configuration will continue to work. There's now a consolidated key called _inputs that encompasses our previous keys:

  • _options
  • _comments
  • _instance_values
  • _select_data
  • _structures (renamed from _array_structures)

Having the configuration keys at the top level forced you to redefine your input key multiple times, and spread the configuration for an input across multiple places. This proved to be progressively harder to maintain as you configured more inputs.

The _inputs configuration flips the input and configuration keys from the previous convention, allowing you to define everything for an input in one place.

We've also introduced two new configuration settings, type and label. These let you choose which kind of input you want, and what label text is shown separately from the naming conventions.

Input configuration
copied
anything: 
_inputs:
  anything:
    type: markdown
    label: Main Content
Input configuration
copied
{
  "anything": null,
  "_inputs": {
    "anything": {
      "type": "markdown",
      "label": "Main Content"
    }
  }
}
Input configuration
copied
[_inputs.anything]
type = "markdown"
label = "Main Content"

Examples#

It's often easier to just see the before and after. Here are some examples covering the previous and current configurations:

Comments#

Now set with the comment key.

Old configuration
copied
brand_color: '#034ad8'
_comments:
  brand_color: Use a bold color here
Old configuration
copied
{
  "brand_color": "#034ad8",
  "_comments": {
    "brand_color": "Use a bold color here"
  }
}
Old configuration
copied
brand_color = "#034ad8"

[_comments]
brand_color = "Use a bold color here"
New configuration
copied
brand_color: '#034ad8'
_inputs:
  brand_color:
    comment: Use a bold color here
New configuration
copied
{
  "brand_color": "#034ad8",
  "_inputs": {
    "brand_color": {
      "comment": "Use a bold color here"
    }
  }
}
New configuration
copied
brand_color = "#034ad8"

[_inputs.brand_color]
comment = "Use a bold color here"

Options#

Now set with the options key.

Old configuration
copied
hero_image: /uploads/hero.png
_options:
  hero_image:
    width: 500
    height: 600
Old configuration
copied
{
  "hero_image": "/uploads/hero.png",
  "_options": {
    "hero_image": {
      "width": 500,
      "height": 600
    }
  }
}
Old configuration
copied
hero_image = "/uploads/hero.png"

[_options.hero_image]
width = 500
height = 600
New configuration
copied
hero_image: /uploads/hero.png
_inputs:
  hero_image:
    options:
      width: 500
      height: 600
New configuration
copied
{
  "hero_image": "/uploads/hero.png",
  "_inputs": {
    "hero_image": {
      "options": {
        "width": 500,
        "height": 600
      }
    }
  }
}
New configuration
copied
hero_image = "/uploads/hero.png"

[_inputs.hero_image.options]
width = 500
height = 600

Instance Values#

Now set with the instance_value key.

Old configuration
copied
_instance_values:
  _uuid: UUID
  created_at: NOW
Old configuration
copied
{
  "_instance_values": {
    "_uuid": "UUID",
    "created_at": "NOW"
  }
}
Old configuration
copied
[_instance_values]
_uuid = "UUID"
created_at = "NOW"
New configuration
copied
_inputs:
  _uuid:
    instance_value: UUID
  created_at:
    instance_value: NOW
New configuration
copied
{
  "_inputs": {
    "_uuid": {
      "instance_value": "UUID"
    },
    "created_at": {
      "instance_value": "NOW"
    }
  }
}
New configuration
copied
[_inputs._uuid]
instance_value = "UUID"

[_inputs.created_at]
instance_value = "NOW"

Select data#

There are no changes to _select_data itself:

Input configuration
copied
animal: Cow
_select_data:
  animals:
    - Cat
    - Cow
Input configuration
copied
{
  "animal": "Cow",
  "_select_data": {
    "animals": [
      "Cat",
      "Cow"
    ]
  }
}
Input configuration
copied
animal = "Cow"

[_select_data]
animals = [ "Cat", "Cow" ]

You can now choose the select values (separately from the naming convention) for a Select input with values. Either define the values directly:

Input configuration
copied
animal: Cow
_inputs:
  animal:
    type: select
    options:
      values:
        - Cat
        - Cow
Input configuration
copied
{
  "animal": "Cow",
  "_inputs": {
    "animal": {
      "type": "select",
      "options": {
        "values": [
          "Cat",
          "Cow"
        ]
      }
    }
  }
}
Input configuration
copied
animal = "Cow"

[_inputs.animal]
type = "select"

  [_inputs.animal.options]
  values = [ "Cat", "Cow" ]

Or reference _select_data defined anywhere in the configuration cascade:

Input configuration
copied
animal: Cow
_inputs:
  animal:
    type: select
    options:
      values: _select_data.mammals
_select_data:
  mammals:
    - Cat
    - Cow
Input configuration
copied
{
  "animal": "Cow",
  "_inputs": {
    "animal": {
      "type": "select",
      "options": {
        "values": "_select_data.mammals"
      }
    }
  },
  "_select_data": {
    "mammals": [
      "Cat",
      "Cow"
    ]
  }
}
Input configuration
copied
animal = "Cow"

[_inputs.animal]
type = "select"

  [_inputs.animal.options]
  values = "_select_data.mammals"

[_select_data]
mammals = [ "Cat", "Cow" ]

Structures#

Array Structures are now called Structures, and configured with _structures instead of _array_structures. Outside of this rename, there are no changes to the configuration itself:

Input configuration
copied
gallery: 
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        icon: image
        value:
          image: /uploads/placeholder.png
          caption: 
      - label: External link
        icon: link
        value:
          url: 
          title:
Input configuration
copied
{
  "gallery": null,
  "_structures": {
    "gallery": {
      "style": "modal",
      "values": [
        {
          "label": "Image",
          "icon": "image",
          "value": {
            "image": "/uploads/placeholder.png",
            "caption": null
          }
        },
        {
          "label": "External link",
          "icon": "link",
          "value": {
            "url": null,
            "title": null
          }
        }
      ]
    }
  }
}
Input configuration
copied
[_structures.gallery]
style = "modal"

  [[_structures.gallery.values]]
  label = "Image"
  icon = "image"

    [_structures.gallery.values.value]
    image = "/uploads/placeholder.png"

  [[_structures.gallery.values]]
  label = "External link"
  icon = "link"

    [_structures.gallery.values.value]

You can now choose the structures (separately from the naming convention) for an Array input with structures. Either define the values directly:

Input configuration
copied
gallery: 
_inputs:
  gallery:
    type: array
    options:
      structures:
        style: modal
        values:
          - label: Image
            icon: image
            value:
              image: /uploads/placeholder.png
              caption: 
          - label: External link
            icon: link
            value:
              url: 
              title:
Input configuration
copied
{
  "gallery": null,
  "_inputs": {
    "gallery": {
      "type": "array",
      "options": {
        "structures": {
          "style": "modal",
          "values": [
            {
              "label": "Image",
              "icon": "image",
              "value": {
                "image": "/uploads/placeholder.png",
                "caption": null
              }
            },
            {
              "label": "External link",
              "icon": "link",
              "value": {
                "url": null,
                "title": null
              }
            }
          ]
        }
      }
    }
  }
}
Input configuration
copied
[_inputs.gallery]
type = "array"

[_inputs.gallery.options.structures]
style = "modal"

  [[_inputs.gallery.options.structures.values]]
  label = "Image"
  icon = "image"

    [_inputs.gallery.options.structures.values.value]
    image = "/uploads/placeholder.png"

  [[_inputs.gallery.options.structures.values]]
  label = "External link"
  icon = "link"

    [_inputs.gallery.options.structures.values.value]

Or reference _structures defined anywhere in the configuration cascade:

Input configuration
copied
gallery: 
_inputs:
  gallery:
    type: array
    options:
      structures: _structures.media_items
_structures:
  media_items:
    style: modal
    values:
      - label: Image
        icon: image
        value:
          image: /uploads/placeholder.png
          caption: 
      - label: External link
        icon: link
        value:
          url: 
          title:
Input configuration
copied
{
  "gallery": null,
  "_inputs": {
    "gallery": {
      "type": "array",
      "options": {
        "structures": "_structures.media_items"
      }
    }
  },
  "_structures": {
    "media_items": {
      "style": "modal",
      "values": [
        {
          "label": "Image",
          "icon": "image",
          "value": {
            "image": "/uploads/placeholder.png",
            "caption": null
          }
        },
        {
          "label": "External link",
          "icon": "link",
          "value": {
            "url": null,
            "title": null
          }
        }
      ]
    }
  }
}
Input configuration
copied
[_inputs.gallery]
type = "array"

  [_inputs.gallery.options]
  structures = "_structures.media_items"

[_structures.media_items]
style = "modal"

  [[_structures.media_items.values]]
  label = "Image"
  icon = "image"

    [_structures.media_items.values.value]
    image = "/uploads/placeholder.png"

  [[_structures.media_items.values]]
  label = "External link"
  icon = "link"

    [_structures.media_items.values.value]

Where to configure inputs#

The _inputs configuration is set alongside the inputs in the examples above. You can set it anywhere in the configuration cascade, just as the previous keys allowed. The keys inside _inputs entries are merged across the cascade, allowing you to overwrite or combine more specific configurations (e.g. setting comments globally and options per file).

_select_data and _structures are defined in the configuration cascade as well, so you can set them with or separately to _inputs.

Other changes#

  • Color inputs have new format and alpha options, falling back to the naming convention if these options are not set.
  • Hiding inputs is now set with hidden in an _inputs entry rather than an option, since it's available for any input type. This key also supports a string where the input is hidden based on the value of another input. This can start with a ! to reverse the value.
  • Object structures are now supported. These allow you to configure objects between an empty state (null) and a selection of object formats. Useful if you have components with a limited number of sub-components.
  • Two new inputs: Range number input and a Switch boolean input. These are only available with the new inputs config. More input types coming soon, contact support if you have specific requests.
  • Comments now support a limited set of Markdown: links, bold, italic, subscript, superscript and inline code elements are allowed. Links in this block also support Editor Links.

Related Articles

Open in a new tab