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. Array inputs give your editors:
- Drag and drop reordering
- Configurable add options at any index
- Intuitive editing
- Easy removal of items
Array#
Grouped list of inputs with controls to add, remove and reorder items.
Array inputs are shown for inputs configured with the type array, or for array input values.
Inline values#
Inline values in Array inputs are displayed and edited with inputs directly in the list. By default, text, number and boolean values are displayed inline as text, number and checkbox inputs.
staff:
- Karen
- Billy
- Holly
{
"staff": [
"Karen",
"Billy",
"Holly"
]
}staff = [ "Karen", "Billy", "Holly" ]
sections:
_inputs:
sections:
type: array
{
"sections": {
"_inputs": {
"sections": {
"type": "array"
}
}
}
}[sections._inputs.sections]
type = "array"
You can configure arrays to use different inputs for inline values with input configuration. Each value is still stored as either a text, number or boolean value — but is now edited with a more suitable input.
Here's an example for an array of Image File inputs:
gallery:
- /uploads/mountain.png
- /uploads/beach.png
_inputs:
gallery:
type: array
gallery[*]:
type: image
{
"gallery": [
"/uploads/mountain.png",
"/uploads/beach.png"
],
"_inputs": {
"gallery": {
"type": "array"
},
"gallery[*]": {
"type": "image"
}
}
}gallery = [ "/uploads/mountain.png", "/uploads/beach.png" ]
[_inputs.gallery]
type = "array"
[_inputs."gallery[*]"]
type = "image"
Here's another example for an array of Select inputs, populated from a posts collection:
other_posts:
- /posts/top-10-things.md
- /posts/yesterday-i-found.md
_inputs:
other_posts:
type: array
other_posts[*]:
type: select
options:
values: collections.posts
{
"other_posts": [
"/posts/top-10-things.md",
"/posts/yesterday-i-found.md"
],
"_inputs": {
"other_posts": {
"type": "array"
},
"other_posts[*]": {
"type": "select",
"options": {
"values": "collections.posts"
}
}
}
}other_posts = [ "/posts/top-10-things.md", "/posts/yesterday-i-found.md" ]
[_inputs.other_posts]
type = "array"
[_inputs."other_posts[*]"]
type = "select"
[_inputs."other_posts[*]".options]
values = "collections.posts"
Structured or nested values#
Array inputs containing object or array values are shown as a list of Object inputs. Team members add, remove or reorder items directly on this input. Item values are edited after opening each item.
This allows your team members to intuitively manage complex data. When your data can be deeply nested, there is no end to what can be achieved. Rendering the array value from this input with a loop on your site creates powerful editing opportunities for your team members.
quotes:
- name: Betty Jefferson
position: Jamstack Developer
image: /images/betty.svg
quote_markdown: “This quotation can be edited via the front matter textarea input.”
- name: Jamie Mills
position: Jamstack Developer
image: /images/jamie.svg
quote_markdown: “You can also reorder quotations via the front matter arrays input.”
{
"quotes": [
{
"name": "Betty Jefferson",
"position": "Jamstack Developer",
"image": "/images/betty.svg",
"quote_markdown": "“This quotation can be edited via the front matter textarea input.”"
},
{
"name": "Jamie Mills",
"position": "Jamstack Developer",
"image": "/images/jamie.svg",
"quote_markdown": "“You can also reorder quotations via the front matter arrays input.”"
}
]
}[[quotes]]
name = "Betty Jefferson"
position = "Jamstack Developer"
image = "/images/betty.svg"
quote_markdown = "“This quotation can be edited via the front matter textarea input.”"
[[quotes]]
name = "Jamie Mills"
position = "Jamstack Developer"
image = "/images/jamie.svg"
quote_markdown = "“You can also reorder quotations via the front matter arrays input.”"
Options#
Array inputs are configured with options inside an _inputs entry.
page_sections:
_inputs:
page_sections:
type: array
options:
structures: _structures.components
preview:
text:
- key: name
subtext:
- key: description
image:
- key: my_image
icon: article
{
"page_sections": null,
"_inputs": {
"page_sections": {
"type": "array",
"options": {
"structures": "_structures.components",
"preview": {
"text": [
{
"key": "name"
}
],
"subtext": [
{
"key": "description"
}
],
"image": [
{
"key": "my_image"
}
],
"icon": "article"
}
}
}
}
}[_inputs.page_sections]
type = "array"
[_inputs.page_sections.options]
structures = "_structures.components"
[_inputs.page_sections.options.preview]
icon = "article"
[[_inputs.page_sections.options.preview.text]]
key = "name"
[[_inputs.page_sections.options.preview.subtext]]
key = "description"
[[_inputs.page_sections.options.preview.image]]
key = "my_image"
Array inputs have the following options available:
Set how an 'empty' value will be saved. Does not apply to existing empty values. Can be one of the following:
array- 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.
The preview definition for changing the way data within an Array input's items are previewed before being expanded. The options available for Array inputs are:
textsubtexticonimage
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 for those items.
Controls the icon shown on the unopened item inputs. Must match a Material Icon name. Defaults checking the keys thumbnail_image, thumbnail_image_path, image, and image_path in that order, 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 item inputs. 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 supporting text shown on the unopened item inputs. 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.
Controls the main text shown on the unopened item inputs. Has no default, falls back to the first value found (prioritizing text-based values).
If set to false, no text is displayed.
Provides options for creating new items. When adding a new item, team members are prompted to choose from a number of values you have defined. Defaults to fetching from _structures using the naming convention (e.g. _structures.blocks for an input key blocks).
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.