☁️ Loving our new documentation website? Provide feedback in the CloudCannon Community! ✨

Developer Articles

Migrating to input configuration

Last modified: February 5th, 2026

Table of contents

  • Examples
  • Where to configure inputs
  • Other changes

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

    Copied to clipboard
    anything: 
_inputs:
  anything:
    type: markdown
    label: Main Content
    {
  "anything": null,
  "_inputs": {
    "anything": {
      "type": "markdown",
      "label": "Main Content"
    }
  }
}
    [_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.

    Copied to clipboard
    brand_color: '#034ad8'
_comments:
  brand_color: Use a bold color here
    {
  "brand_color": "#034ad8",
  "_comments": {
    "brand_color": "Use a bold color here"
  }
}
    brand_color = "#034ad8"

[_comments]
brand_color = "Use a bold color here"
    Copied to clipboard
    brand_color: '#034ad8'
_inputs:
  brand_color:
    comment: Use a bold color here
    {
  "brand_color": "#034ad8",
  "_inputs": {
    "brand_color": {
      "comment": "Use a bold color here"
    }
  }
}
    brand_color = "#034ad8"

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

    Options

    Now set with the options key.

    Copied to clipboard
    hero_image: /uploads/hero.png
_options:
  hero_image:
    width: 500
    height: 600
    {
  "hero_image": "/uploads/hero.png",
  "_options": {
    "hero_image": {
      "width": 500,
      "height": 600
    }
  }
}
    hero_image = "/uploads/hero.png"

[_options.hero_image]
width = 500
height = 600
    Copied to clipboard
    hero_image: /uploads/hero.png
_inputs:
  hero_image:
    options:
      width: 500
      height: 600
    {
  "hero_image": "/uploads/hero.png",
  "_inputs": {
    "hero_image": {
      "options": {
        "width": 500,
        "height": 600
      }
    }
  }
}
    hero_image = "/uploads/hero.png"

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

    Instance Values

    Now set with the instance_value key.

    Copied to clipboard
    _instance_values:
  _uuid: UUID
  created_at: NOW
    {
  "_instance_values": {
    "_uuid": "UUID",
    "created_at": "NOW"
  }
}
    [_instance_values]
_uuid = "UUID"
created_at = "NOW"
    Copied to clipboard
    _inputs:
  _uuid:
    instance_value: UUID
  created_at:
    instance_value: NOW
    {
  "_inputs": {
    "_uuid": {
      "instance_value": "UUID"
    },
    "created_at": {
      "instance_value": "NOW"
    }
  }
}
    [_inputs._uuid]
instance_value = "UUID"

[_inputs.created_at]
instance_value = "NOW"

    Select data

    There are no changes to _select_data itself:

    Copied to clipboard
    animal: Cow
_select_data:
  animals:
    - Cat
    - Cow
    {
  "animal": "Cow",
  "_select_data": {
    "animals": [
      "Cat",
      "Cow"
    ]
  }
}
    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:

    Copied to clipboard
    animal: Cow
_inputs:
  animal:
    type: select
    options:
      values:
        - Cat
        - Cow
    {
  "animal": "Cow",
  "_inputs": {
    "animal": {
      "type": "select",
      "options": {
        "values": [
          "Cat",
          "Cow"
        ]
      }
    }
  }
}
    animal = "Cow"

[_inputs.animal]
type = "select"

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

    Or reference _select_data defined anywhere in the configuration cascade:

    Copied to clipboard
    animal: Cow
_inputs:
  animal:
    type: select
    options:
      values: _select_data.mammals
_select_data:
  mammals:
    - Cat
    - Cow
    {
  "animal": "Cow",
  "_inputs": {
    "animal": {
      "type": "select",
      "options": {
        "values": "_select_data.mammals"
      }
    }
  },
  "_select_data": {
    "mammals": [
      "Cat",
      "Cow"
    ]
  }
}
    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:

    Copied to clipboard
    gallery: 
_structures:
  gallery:
    style: modal
    values:
      - label: Image
        icon: image
        value:
          image: /uploads/placeholder.png
          caption: 
      - label: External link
        icon: link
        value:
          url: 
          title:
    {
  "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
          }
        }
      ]
    }
  }
}
    [_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:

    Copied to clipboard
    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:
    {
  "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
              }
            }
          ]
        }
      }
    }
  }
}
    [_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:

    Copied to clipboard
    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:
    {
  "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
          }
        }
      ]
    }
  }
}
    [_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 Resources

    Open in a new tab