List Field

This is an advanced-use feature, and likely not something you'll need to configure. What you probably want is the content types reference!

The List Field represents an array of primitive values — specifically strings or numbers.

Use this field when you want to support multiple entities that all output a single value. Each entity will appear in a list where you can edit, add and delete them. Fields that can be used to edit the array of primitive values in the list are: text, textarea, number & select.

Options

REQUIRED
component
'list'

The name of the plugin component. Always 'list'.

REQUIRED
name
string

The path to some value in the data being edited.

REQUIRED
field
{ component: 'text' | 'textarea' | 'number' | 'select' }

The field that will render to edit each list item. Component Options: 'text', 'textarea', 'number', or 'select'

label
string

A human readable label for the field. Defaults to the name.

description
string

Description that expands on the purpose of the field or prompts a specific action.

default​Item
string | number | (() => string | number)

Provides the list items with default data upon being created. Returns an empty string if no value is provided.

item​Props
(item: object) => { key?: string }

A function that generates props for each list item. It takes the item as an argument. It returns an object containing, key: This property is used to optimize the rendering of lists. If rendering is causing problems, use defaultItem to generate a new key, as is seen in this example. Feel free to reference the React documentation for more on keys and lists.

All properties marked as REQUIRED must be specified for the field to work properly.

This interface only shows the keys unique to the list field. Visit the Field Config docs for a complete list of options.

Definition

Below are some examples of how a list field could be defined in a form.

With the text field

For example, if we had a list of lunch options in the frontmatter of a Markdown file:

example data

Our list field config could look like this:

Note: The above configuration would look the same for the textarea field.

With the number field

Below is an example using the number field if we had an array of 'Pinball Scores' to manage.

example data

The list field config could look like this:

With the select field

Below is an example using the select field if we wanted to rank the best Beatles Albums.

example data

The list field config could look like this: