Using object inputs to edit your data

Last modified: September 21st, 2023

Object inputs represent object data within the Data Editor. They are ideal for grouping related inputs, or hiding complicated or infrequently edited data.

By default, they appear as a button that opens a new level in the editor to the side, showing the inputs inside the object. This continues as you click into nested object inputs. Each object level has a back button to return to the parent scope.

Alternatively, object inputs can be configured to behave differently:

  1. Structured object, a switchable button that can be set from one or more values. Configured with the structures option.
  2. Mutable object, a list showing each entry. Each entry is shown as its own input, including nested objects. Configured with the subtype option.

Examples#

Here are a number of examples demonstrating how to use and configure object inputs.

Object#

Object inputs are shown for inputs configured with the type object, or for object data values.

Value convention
copied
seo:
  title: How to contact us
  image: /images/staff.png
  description: These are all the ways to contact us.
Value convention
copied
{
  "seo": {
    "title": "How to contact us",
    "image": "/images/staff.png",
    "description": "These are all the ways to contact us."
  }
}
Value convention
copied
[seo]
title = "How to contact us"
image = "/images/staff.png"
description = "These are all the ways to contact us."
Input configuration
copied
seo:
  title: How to contact us
  image: /images/staff.png
  description: These are all the ways to contact us.
_inputs:
  seo:
    type: object
Input configuration
copied
{
  "seo": {
    "title": "How to contact us",
    "image": "/images/staff.png",
    "description": "These are all the ways to contact us."
  },
  "_inputs": {
    "seo": {
      "type": "object"
    }
  }
}
Input configuration
copied
[seo]
title = "How to contact us"
image = "/images/staff.png"
description = "These are all the ways to contact us."

[_inputs.seo]
type = "object"

In the Data Editor, this example appears as a button with a preview of the data inside:

Screenshot of unopened object input field

Clicking that button opens a new level in the editor showing the inputs for the entries inside the object:

Screenshot of active Object input field

Object with configured preview#

An object input with configuration to adjust which data is used to generate the preview on the button.

Input configuration
copied
seo:
  title: How to contact us
  image: /images/staff.png
  description: These are all the ways to contact us.
_inputs:
  seo:
    type: object
    options:
      preview:
        text:
          - key: description
        subtext:
          - key: title
          - No title
        image: false
        icon: travel_explore
Input configuration
copied
{
  "seo": {
    "title": "How to contact us",
    "image": "/images/staff.png",
    "description": "These are all the ways to contact us."
  },
  "_inputs": {
    "seo": {
      "type": "object",
      "options": {
        "preview": {
          "text": [
            {
              "key": "description"
            }
          ],
          "subtext": [
            {
              "key": "title"
            },
            "No title"
          ],
          "image": false,
          "icon": "travel_explore"
        }
      }
    }
  }
}

Object with grouped inputs#

An object input with configuration to group related inputs together, creating a more focused editing experience.

Input configuration
copied
title: About
description: Everything about us is explained right here.
image: /staff.png
slug: about-us
sitemap: true
components: 
call_to_action: contact-us
_inputs:
  $:
    type: object
    options:
      place_groups_below: false
      groups:
        - heading: SEO
          comment: Values for search engines to read
          inputs:
            - title
            - description
            - image
        - heading: Advanced
          collapsed: true
          inputs:
            - slug
            - sitemap
Input configuration
copied
{
  "title": "About",
  "description": "Everything about us is explained right here.",
  "image": "/staff.png",
  "slug": "about-us",
  "sitemap": true,
  "components": null,
  "call_to_action": "contact-us",
  "_inputs": {
    "$": {
      "type": "object",
      "options": {
        "place_groups_below": false,
        "groups": [
          {
            "heading": "SEO",
            "comment": "Values for search engines to read",
            "inputs": [
              "title",
              "description",
              "image"
            ]
          },
          {
            "heading": "Advanced",
            "collapsed": true,
            "inputs": [
              "slug",
              "sitemap"
            ]
          }
        ]
      }
    }
  }
}

Structured object#

An object input with controls to remove the value, and then replace it with one of two predefined values.

Input configuration
copied
feature_section:
  image: /uploads/cat.png
  caption: Tabby cat jumping off a wooden fence.
_inputs:
  feature_section:
    type: object
    options:
      structures: _structures.gallery
_structures:
  gallery:
    values:
      - label: Image
        icon: image
        value:
          image: 
          caption: 
      - label: External link
        icon: link
        value:
          url: 
          title:
Input configuration
copied
{
  "feature_section": {
    "image": "/uploads/cat.png",
    "caption": "Tabby cat jumping off a wooden fence."
  },
  "_inputs": {
    "feature_section": {
      "type": "object",
      "options": {
        "structures": "_structures.gallery"
      }
    }
  },
  "_structures": {
    "gallery": {
      "values": [
        {
          "label": "Image",
          "icon": "image",
          "value": {
            "image": null,
            "caption": null
          }
        },
        {
          "label": "External link",
          "icon": "link",
          "value": {
            "url": null,
            "title": null
          }
        }
      ]
    }
  }
}
Input configuration
copied
[feature_section]
image = "/uploads/cat.png"
caption = "Tabby cat jumping off a wooden fence."

[_inputs.feature_section]
type = "object"

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

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

  [_structures.gallery.values.value]

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

  [_structures.gallery.values.value]

structures applies to the object, while entries.structures applies to the entries of an object.

Mutable object#

An object with entries shown in a list, with controls to add, remove, rename, and reorder.

Adding a new entry clones the value from the previous entry, and prompts you to enter the new key. At least one entry must exist to clone from, otherwise this input is invalid. This input prevents you removing the last entry.

Input configuration
copied
staff:
  john:
    name: John Doe
    image: /images/john.png
    age: 28
  jane:
    name: Jane Doe
    image: /images/jane.png
    age: 34
_inputs:
  staff:
    type: object
    options:
      subtype: mutable
Input configuration
copied
{
  "staff": {
    "john": {
      "name": "John Doe",
      "image": "/images/john.png",
      "age": 28
    },
    "jane": {
      "name": "Jane Doe",
      "image": "/images/jane.png",
      "age": 34
    }
  },
  "_inputs": {
    "staff": {
      "type": "object",
      "options": {
        "subtype": "mutable"
      }
    }
  }
}
Input configuration
copied
[staff.john]
name = "John Doe"
image = "/images/john.png"
age = 28

[staff.jane]
name = "Jane Doe"
image = "/images/jane.png"
age = 34

[_inputs.staff]
type = "object"

  [_inputs.staff.options]
  subtype = "mutable"

entries.allowed_keys can be used in combination with subtypes and entries.structures to control both the keys and the values for this object.

Mutable object with subtype#

An object with entries shown in a list, with controls to add, remove, rename, and reorder.

Adding a new entry creates an empty time input, and prompts you to enter the new key. This object can have no entries, since the type is configured for the entries. Object subtypes are configured using the .* selector.

Input configuration
copied
timeline:
  start_time: 9:00 am
  lunch_time: 12:00 pm
  snack_time: 3:00 pm
  home_time: 5:00 pm
_inputs:
  timeline:
    type: object
    options:
      subtype: mutable
  timeline.*:
    type: time
Input configuration
copied
{
  "timeline": {
    "start_time": "9:00 am",
    "lunch_time": "12:00 pm",
    "snack_time": "3:00 pm",
    "home_time": "5:00 pm"
  },
  "_inputs": {
    "timeline": {
      "type": "object",
      "options": {
        "subtype": "mutable"
      }
    },
    "timeline.*": {
      "type": "time"
    }
  }
}
Input configuration
copied
[timeline]
start_time = "9:00 am"
lunch_time = "12:00 pm"
snack_time = "3:00 pm"
home_time = "5:00 pm"

[_inputs.timeline]
type = "object"

  [_inputs.timeline.options]
  subtype = "mutable"

[_inputs."timeline.*"]
type = "time"

Mutable object with set keys#

An object with entries shown in a list, with controls to add, remove, rename, and reorder.

The keys available when adding new entries and renaming existing entries are limited to the entries.allowed_keys list. No entries can be added once all entries.allowed_keys are in use. Entries with keys not included in entries.allowed_keys can exist, but if removed/renamed, cannot be re-added.

Input configuration
copied
menu:
  main:
    weight: 1
  footer:
    weight: 5
_inputs:
  menu:
    type: object
    options:
      subtype: mutable
      entries:
        allowed_keys:
          - main
          - footer
          - sidebar
Input configuration
copied
{
  "menu": {
    "main": {
      "weight": 1
    },
    "footer": {
      "weight": 5
    }
  },
  "_inputs": {
    "menu": {
      "type": "object",
      "options": {
        "subtype": "mutable",
        "entries": {
          "allowed_keys": [
            "main",
            "footer",
            "sidebar"
          ]
        }
      }
    }
  }
}
Input configuration
copied
[menu.main]
weight = 1

[menu.footer]
weight = 5

[_inputs.menu]
type = "object"

  [_inputs.menu.options]
  subtype = "mutable"

    [_inputs.menu.options.entries]
    allowed_keys = [ "main", "footer", "sidebar" ]

Mutable object with set values#

An object with entries shown in a list, with controls to add, remove, rename, and reorder.

When adding a new entry here, you are given the option of two predefined values: Image and External Link.

Input configuration
copied
gallery:
  cat:
    image: /uploads/cat.png
    caption: Tabby cat jumping off a wooden fence.
  dog:
    url: https://example.com/
    title: Website all about dogs.
_inputs:
  gallery:
    type: object
    options:
      subtype: mutable
      entries:
        structures: _structures.grid_items
_structures:
  grid_items:
    values:
      - label: Image
        icon: image
        value:
          image: 
          caption: 
      - label: External link
        icon: link
        value:
          url: 
          title:
Input configuration
copied
{
  "gallery": {
    "cat": {
      "image": "/uploads/cat.png",
      "caption": "Tabby cat jumping off a wooden fence."
    },
    "dog": {
      "url": "https://example.com/",
      "title": "Website all about dogs."
    }
  },
  "_inputs": {
    "gallery": {
      "type": "object",
      "options": {
        "subtype": "mutable",
        "entries": {
          "structures": "_structures.grid_items"
        }
      }
    }
  },
  "_structures": {
    "grid_items": {
      "values": [
        {
          "label": "Image",
          "icon": "image",
          "value": {
            "image": null,
            "caption": null
          }
        },
        {
          "label": "External link",
          "icon": "link",
          "value": {
            "url": null,
            "title": null
          }
        }
      ]
    }
  }
}
Input configuration
copied
[gallery.cat]
image = "/uploads/cat.png"
caption = "Tabby cat jumping off a wooden fence."

[gallery.dog]
url = "https://example.com/"
title = "Website all about dogs."

[_inputs.gallery]
type = "object"

  [_inputs.gallery.options]
  subtype = "mutable"

    [_inputs.gallery.options.entries]
    structures = "_structures.grid_items"

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

  [_structures.grid_items.values.value]

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

  [_structures.grid_items.values.value]

entries.structures applies to the entries of an object, while structures applies to the object.

Mutable object with set keys and set values specific to keys#

An object with entries shown in a list, with controls to add, remove, rename, and reorder.

When adding a new entry here, you are given the option of two predefined values: Image and External Link. The keys available when adding new entries and renaming existing entries are limited to the entries.allowed_keys list. No entries can be added once all entries.allowed_keys are in use. Entries with keys not included in entries.allowed_keys can exist, but if removed/renamed, cannot be re-added.

Input configuration
copied
details:
  image:
    image: /uploads/cat.png
    caption: Tabby cat jumping off a wooden fence.
  link:
    url: https://example.com/
    title: Website all about dogs.
_inputs:
  details:
    type: object
    options:
      subtype: mutable
      entries:
        structures: _structures.detail_items
        allowed_keys:
          - image
          - link
          - link_or_image
        assigned_structures:
          link:
            - link_detail
          image:
            - image_detail
          link_or_image:
            - image_detail
            - link_detail
_structures:
  detail_items:
    values:
      - id: image_detail
        label: Image
        icon: image
        value:
          image: 
          caption: 
      - id: link_detail
        label: External link
        icon: link
        value:
          url: 
          title:
Input configuration
copied
{
  "details": {
    "image": {
      "image": "/uploads/cat.png",
      "caption": "Tabby cat jumping off a wooden fence."
    },
    "link": {
      "url": "https://example.com/",
      "title": "Website all about dogs."
    }
  },
  "_inputs": {
    "details": {
      "type": "object",
      "options": {
        "subtype": "mutable",
        "entries": {
          "structures": "_structures.detail_items",
          "allowed_keys": [
            "image",
            "link",
            "link_or_image"
          ],
          "assigned_structures": {
            "link": [
              "link_detail"
            ],
            "image": [
              "image_detail"
            ],
            "link_or_image": [
              "image_detail",
              "link_detail"
            ]
          }
        }
      }
    }
  },
  "_structures": {
    "detail_items": {
      "values": [
        {
          "id": "image_detail",
          "label": "Image",
          "icon": "image",
          "value": {
            "image": null,
            "caption": null
          }
        },
        {
          "id": "link_detail",
          "label": "External link",
          "icon": "link",
          "value": {
            "url": null,
            "title": null
          }
        }
      ]
    }
  }
}
Input configuration
copied
[details.image]
image = "/uploads/cat.png"
caption = "Tabby cat jumping off a wooden fence."

[details.link]
url = "https://example.com/"
title = "Website all about dogs."

[_inputs.details]
type = "object"

  [_inputs.details.options]
  subtype = "mutable"

    [_inputs.details.options.entries]
    structures = "_structures.detail_items"
    allowed_keys = [ "image", "link", "link_or_image" ]

      [_inputs.details.options.entries.assigned_structures]
      link = [ "link_detail" ]
      image = [ "image_detail" ]
      link_or_image = [ "image_detail", "link_detail" ]

[[_structures.detail_items.values]]
id = "image_detail"
label = "Image"
icon = "image"

  [_structures.detail_items.values.value]

[[_structures.detail_items.values]]
id = "link_detail"
label = "External link"
icon = "link"

  [_structures.detail_items.values.value]

Options#

Object inputs have the following options available within options inside an _inputs entry:

subtype - boolean#

Changes how this is object input is displayed and interacted with. Defaults to object.

If set to object, data entries appear as standard inputs, nested one layer deeper.

If set to mutable, data entries within an object input can be added, renamed, removed and reordered. This also changes the appearance of the input, by listing entries as a sequential group with controls for adding, removing, renaming and reordering.

entries.allowed_keys - array#

Defines a limited set of keys that can exist on the data within an object input. This set is used when entries are added and renamed with subtype: mutable. Defaults to [].

Has no effect if subtype anything but mutable. Only applies to mutable objects.

entries.structures - string or object#

Provides data formats when adding entries to the data within this object input. When adding an entry, team members are prompted to choose from a number of values you have defined. Has no default.

Has no effect if subtype anything but mutable. Only applies to mutable objects.

If set as an object, the structures value is used directly.

If set as a string, the structures value is fetched from the configuration cascade. This allows you to define _structures elsewhere and reference it from here.

This looks similar to, and shares same format as structures. However, entries.structures applies to the entries within the object, and structures applies to the object itself.

entries.assigned_structures - object#

Reduces the set of structure values available for entries with specific keys within a mutable object input. This set is used when entries are added with subtype: mutable. Structure values are referred to by their id.

Has no effect if subtype anything but mutable. Only applies to mutable objects.

entries.comment - text#

Used to supply help text above the key input when adding/renaming within a mutable object input. Has no default. Supports a limited set of Markdown: links, bold, italic, subscript, superscript and inline code elements are allowed.

Has no effect if subtype anything but mutable. Only applies to mutable objects.

entries.documentation - object#

Provides a custom link for documentation for editors shown above the key input when adding/renaming within a mutable object input. Contains the following fields:

  • url for the href value of the link (String, required).
  • text for the visible text used in the link (String). Defaults to Documentation.
  • icon for the icon displayed next to the link. Must be a Material Icon name. Defaults to auto_stories.
_inputs:
  my_object:
    type: object
    options:
      subtype: mutable
      entries:
        documentation:
          url: 'https://example.com/documentation/'
          text: Read more about adding/renaming this key

Has no effect if subtype anything but mutable. Only applies to mutable objects.

empty_type - string#

Set how an empty value will be saved. Does not apply to existing empty values. Can be one of the following:

  • object - an empty value for this input will be stored as {} (default).
  • null - an empty value for this input will be stored as a null value. This does not apply to TOML files.
allow_label_formatting - boolean#

Controls whether or not labels on mutable object entries are formatted. Defaults to false.

Only applies to mutable objects.

groups - array of Group#

Allows you to group the inputs inside this object together without changing the data structure.

Groups are labelled with a heading and description. They can start collapsed or expanded (default). The inputs that belong to each group are referred to by key. Groups can only contain inputs inside this object.

Ungrouped inputs are displayed after the groups by default, but you can reverse this with place_groups_below.

Does not apply to mutable or structured objects.

groups[*].heading - text#

The main text displayed at the top of a group. Visible when open or collapsed.

groups[*].comment - text#

The supporting text displayed at the top of a group, below the heading. Visible when open or expanded.

groups[*].collapsed - boolean#

Whether the group starts open or collapsed. Defaults to false (open).

groups[*].inputs - array of string#

The input keys included in this group. These keys must reference keys within this object input's data. Defaults to [].

groups[*].documentation - object#

Provides a custom link for documentation for editors shown below the heading of the group. Contains the following fields:

  • url for the href value of the link (String, required).
  • text for the visible text used in the link (String). Defaults to Documentation.
  • icon for the icon displayed next to the link. Must be a Material Icon name. Defaults to auto_stories.
place_groups_below - boolean#

Controls which order input groups and ungrouped inputs appear in. Defaults to false. Inputs are grouped with the groups options.

preview - object#

The preview definition for changing the way data within an object input is previewed before being expanded. The options available for object inputs are:

  • text
  • subtext
  • icon
  • image

See the preview options documentation for detailed information on setting this option.

If the input has structures, the preview from the structure definition is used instead.

Object inputs now support the new preview option. Read our migration guide if you are still using the old options: text_key, subtext_key, image_key and icon.

preview.icon - array, string or boolean#

Controls the icon shown on the unopened input. Must match a Material Icon name. Defaults checking the icon key, then falls back to notes.

If set to false, no icon is displayed.

If image is set, it will cover icon when loaded successfully.

preview.image - array, string or boolean#

Controls the image shown on the unopened input. Has no default, falls back to thumbnail_image, thumbnail_image_path, image, and image_path in that order.

If set to false, no image is displayed.

If no image is found, icon is displayed instead.

preview.text - array, string or boolean#

Controls the main text shown on the unopened input. Has no default, falls back to the first value found (prioritizing text-based values).

If set to false, no text is displayed.

preview.subtext - array, string or boolean#

Controls the supporting text shown on the unopened input. Has no default, falls back to listing the label of each input inside the object value.

If set to false, no text is displayed.

Subtext is hidden if text and subtext is the same. If there's no text, subtext is used instead.

structures - string or object#

Provides data formats for value of this object. When choosing an item, team members are prompted to choose from a number of values you have defined. Has no default.

If set as an object, the structures value is used directly.

If set as a string, the structures value is fetched from the configuration cascade. This allows you to define _structures elsewhere and reference it from here.

This looks similar to, and shares same format as entries.structures. However, structures applies to the object itself, and entries.structures applies to the entries within the object.

Related Articles

Related links

Previous
Social
These inputs are for editing plain text in your data. Each input includes a specific brand icon.
Next
Array
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.

Open in a new tab