Skip to content
Home button
  • Pricing
Articles
Choose your preferred SSG:
Choose your preferred SSG:

Customizing your inputs in the Data Editor

We’ve recently changed the way you configure inputs. Check out our migration guide here.

The Data Editor uses a wide range of different inputs. Each input corresponds to a field in your front matter or data file, providing an editing interface for those values. Inputs have a type, label and a comment.

Diagram showcasing parts of a text input

Configuration

Use the _inputs configuration to change types, labels, comments, instance values, and specific type options. Some configuration (notably input type) is automatically set for you based on the input key.

Input configuration 
_inputs:
  my_custom_input:
    type: image
    label: Hero Image
    comment: Appears at the top of the page
    options:
      width: 720
      height: 480
      resize_style: cover

The above code shows the _inputs configuration set in the same file, but you can choose where to set this for inputs across your site in the configuration cascade.

Each key inside _inputs targets one or more inputs in the Data Editor. These keys can target inputs directly by key name, or the nested path to the input.

This configuration applies to title inputs:

Input configuration 
title: Main page title

_inputs:
  title:
    type: text
    comment: Large text at the top of the page

This configuration applies to date inputs at the root level of your data only:

Input configuration 
title: Main page title
nested:
  title: This input does not have the comment

_inputs:
  $.title:
    comment: Large text at the top of the page

This configuration applies to title inputs directly inside seo objects:

Input configuration 
title: This input does not have the comment
seo:
  title: Longer title for search engines

_inputs:
  seo.title:
    comment: Summary of this page for search engines

This configuration applies to image inputs inside card array items:

Input configuration 
cards:
  - image: /uploads/jane.png

_inputs:
  cards[*].image:
    type: image
    options:
      width: 100
      height: 100

This configuration applies to inline images array items:

Input configuration 
images:
  - /uploads/jane.png

_inputs:
  images[*]:
    type: image
    options:
      width: 100
      height: 100

Read more on configuring inline array inputs.

These selector-style keys can be as targeted as you need them to be:

  • author targets author inputs anywhere.
  • seo.another.title targets title inputs, directly inside another objects, directly inside seo objects.
  • $.blocks[*].author.title targets title inputs, directly inside author objects, directly inside blocks array items, where blocks is at the root level.

Options

Each entry in _inputs has the following options available:

type - String

Changes the editing interface for an input. Each input appears and behave differently, takes different options, and processes different values. See more details in the type section below.

For unknown types, or if the input contains an unsupported value (e.g. an array value in a text input), the disabled type is used instead.

label - String

Changes the text above an input. Defaults to generating the label from the input key (e.g. “Page Title” for page_title).

comment - String

Changes the subtext below the label. Has no default. Supports a limited set of Markdown: links, bold, italic, subscript, superscript and inline code elements are allowed.

Useful for adding reminders or additional context for your team members on a specific input.

options - Object

Configuration settings passed on to the input when displayed. These are specific to each input. The available types and their options are listed below.

instance_value - String

Controls if and how the value of this input is instantiated when created. This occurs when creating files, or adding array items containing the configured input. Has no default. Must be one of UUID or NOW.

  • UUID generates a uuidv4 (extremely unlikely to generate duplicates), useful for identifying unique items (e.g. 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b)
  • NOW generates the current datetime in the site’s configured timezone
hidden - Boolean or string

Toggles the visibility of this input. Useful for when you need an input to exist, but don’t want it edited or seen. Defaults to the naming convention, true for input keys starting with an underscore and false otherwise.

If set as a boolean, the input is hidden based if true.

If set as a string, the input is hidden based on the value of another input. This can start with a ! to reverse the value.

  • published hides an input when the sibling input published is truthy
  • !published hides an input when the sibling input published is falsy
cascade - Boolean

Specifies whether or not this input configuration should be merged with any matching, less specific configuration. Defaults to true.

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 is true, the cascade continues looking and each entry found is merged. This allows you to define a comment globally, then a different label for inputs in a collection without redefining the comment. You can stop the cascade at any given point by setting cascade to false.

Type

The type defines how inputs appear and behave. The type used for each field is based on (in order):

  1. type in _inputs for that key
  2. Value (e.g. boolean values show as a checkbox)
  3. Key name (e.g. color will give you a color picker)

This results in good defaults for unconfigured inputs, without hindering configured inputs. To change the type for an input you can use the _inputs configuration, or the naming conventions:

Input configuration 
my_custom_input:
_inputs:
  my_custom_input:
    type: image
Naming convention 
color: '#efefef'
some_text: Hello

The naming conventions support snake_case, camelCase, PascalCase and kebab-case.

Here are all the available input types, each with their own available options:

Was this article helpful? or Suggest an improvement >

Related articles

Using Text Inputs to edit your data Details for setting up and using different types of plain text inputs for editing your data.
Using Rich Text Inputs to edit your HTML and Markdown data These inputs give your editors ultimate control by allowing them to write markup directly into your data files.
Using Social Inputs to edit your data These inputs are for editing plain text in your data. Each input includes a specific brand icon.
Using Code Inputs to edit your data Code editor input for blocks of code or mono-space plain text.
Using Boolean Inputs to edit your data These inputs are for editing true/false values in your data. They can be triggered on or off.
Using Color Inputs to edit your data Color picker input with spectrum and transparency controls for editing color values in your data.
Using Number Inputs to edit your data These inputs are for editing numerical values in your data.
Using URL Inputs to edit your data Single line input for relative, absolute and fully qualified URLs. URL inputs show a preview of the target.
Using Date and Time Inputs to edit your data These inputs are for editing date and time values in your data.
Using file path inputs to edit your data These inputs allow editors to upload new files, select existing images, or link to external files.
Using Select inputs to edit your data These inputs are for values from a fixed or dynamic set of options. Useful for linking across pages, collections and data sets.
Using Object Inputs to edit your data Object inputs in your data show as a button in the data editor. This button opens a new editor to the side, showing the inputs inside that object. This continues as you click into nested Object inputs. Each object level has a back button to return to the parent scope.
Using Array Inputs to edit your data These inputs are for editing ordered lists of values in your data. Array inputs are grouped lists of inputs in the data editor. They are used for a wide range of use cases, ranging from small text lists to full component builders.
Using the configuration cascade CloudCannon offers different configuration options for each input and editor. Use this to improve the editing experience for your sites. Configuration can be set from a number of sources, from lowest priority to highest.