Choose your preferred SSG:
Choose your preferred SSG:

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

The array editor with draggable handles, editable text and an option to add new content.
Value convention
staff:
  - Bill
  - Ben
  - Badger
Input configuration
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:

Input configuration
gallery:
  - /uploads/mountain.png
  - /uploads/beach.png
_inputs:
  gallery:
    type: array
  gallery[*]:
    type: image
    

Here’s another example for an array of Select inputs, populated from a posts collection:

Input configuration
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

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.

The array editor with a list of staff members including their thumbnail image and name
The array editor with a list of staff members including their thumbnail image and name
Value convention
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.”'

Options

Array inputs are configured with options inside an _inputs entry.

Input configuration
page_sections:
_inputs:
  page_sections:
    type: array
    options:
      structures: _structures.components
      text_key: name
      subtext_key: description
      image_key: my_image
      icon: article

Array inputs have the following options available:

structures - String or object

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.

text_key - String

Controls what key within items with object values is used for the display text on item previews, and the heading for the opened item. Defaults to title, then name, otherwise uses the first value found (prioritizing text-based values). Has no effect on items with primitive values.

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

subtext_key - String

Controls what key within items with object value is used for the supporting text on item previews. Defaults to listing the label of each input inside the object value. Has no effect on items with primitive values.

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

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

image_key - String

Controls what key within items with object values is used to display a preview image on the item preview. Defaults to thumbnail_image, thumbnail_image_path, image, and image_path in that order. If no image is found, icon is displayed instead.

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

icon - String

Sets the icon shown when no image preview is available on the unopened input. Must match a Material Icon name. Defaults to notes.

Was this article helpful? or Suggest an improvement >

Related articles

Other Resources

  1. Material Icons