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:
- Structured object, a switchable button that can be set from one or more values. Configured with the
structures
option. - 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.
seo:
title: How to contact us
image: /images/staff.png
description: These are all the ways to contact us.
{
"seo": {
"title": "How to contact us",
"image": "/images/staff.png",
"description": "These are all the ways to contact us."
}
}
[seo]
title = "How to contact us"
image = "/images/staff.png"
description = "These are all the ways to contact us."
seo:
title: How to contact us
image: /images/staff.png
description: These are all the ways to contact us.
_inputs:
seo:
type: object
{
"seo": {
"title": "How to contact us",
"image": "/images/staff.png",
"description": "These are all the ways to contact us."
},
"_inputs": {
"seo": {
"type": "object"
}
}
}
[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:

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

Object with configured preview#
An object input with configuration to adjust which data is used to generate the preview on the button.
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
{
"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.
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
{
"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.
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:
{
"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
}
}
]
}
}
}
[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.
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
{
"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"
}
}
}
}
[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.
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
{
"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"
}
}
}
[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.
menu:
main:
weight: 1
footer:
weight: 5
_inputs:
menu:
type: object
options:
subtype: mutable
entries:
allowed_keys:
- main
- footer
- sidebar
{
"menu": {
"main": {
"weight": 1
},
"footer": {
"weight": 5
}
},
"_inputs": {
"menu": {
"type": "object",
"options": {
"subtype": "mutable",
"entries": {
"allowed_keys": [
"main",
"footer",
"sidebar"
]
}
}
}
}
}
[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.
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:
{
"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
}
}
]
}
}
}
[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.
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:
{
"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
}
}
]
}
}
}
[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:
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.
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.
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.
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.
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.
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 thehref
value of the link (String, required).text
for the visible text used in the link (String). Defaults toDocumentation
.icon
for the icon displayed next to the link. Must be a Material Icon name. Defaults toauto_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.
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.
Controls whether or not labels on mutable object entries are formatted. Defaults to false
.
Only applies to mutable objects.
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.
The main text displayed at the top of a group. Visible when open or collapsed.
The supporting text displayed at the top of a group, below the heading. Visible when open or expanded.
Whether the group starts open or collapsed. Defaults to false
(open).
The input keys included in this group. These keys must reference keys within this object input's data. Defaults to []
.
Provides a custom link for documentation for editors shown below the heading of the group. Contains the following fields:
url
for thehref
value of the link (String, required).text
for the visible text used in the link (String). Defaults toDocumentation
.icon
for the icon displayed next to the link. Must be a Material Icon name. Defaults toauto_stories
.
Controls which order input groups and ungrouped inputs appear in. Defaults to false
. Inputs are grouped with the groups
options.
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
.
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.
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.
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.
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.
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.