List Field Type

Control Type

A list of items of another type, with control for adding, deleting, and reordering. See configuring items.

Certain item types offer additional control types for this field. See control types below for more information.

Stored Value

An array of chosen items, stored as they would be based on the items property for this field definition.

Usage Example#

Here is an example that shows a list of tags on a page:

1
2
3
4
5
6
7
8
9
10

export default {
  models: {
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        { name: 'tags', type: 'list' },
      ],
    },
  },
}

By default, these will be a series of string fields that you can add, remove, and reorder.

Configuring List Items#

Unless you want an array of string values, you'll have to set the items property.

items

An object specifying the type of item to be stored, along with any other necessary attributes. See below for more information.

Default: { type: 'string' }

Simple List Types#

For simple fields, specifying the type is enough.

1
2
3
4
5
6
7
8
9
10

export default {
  models: {
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        { name: 'images', type: 'list', items: { type: 'image' } },
      ],
    },
  },
}

This will render a list of images.

The simple types include all models other than those mentioned in the advanced types section.

Advanced List Types#

Some types require additional properties.

enum

options: As specified in dropdown control type. Note that there is also support for a checkbox control type, shown below.

model

models: An array of model names to be embedded.

groups: An array of group names from which to pull models.

object

fields: Field definitions for a standalone object.

reference

models: An array of model names to be linked to.

groups: An array of group names from which to pull models.

Adding a Static Label#

Notice that the label is filled in by default for each item. You can control this with a label property, just like any other field.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

export default {
  models: {
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        {
          name: 'images',
          type: 'list',
          items: { type: 'image', label: 'Image' },
        },
      ],
    },
  },
}

Now the label will appear statically next to each image.

List of Images Field Control with Labels

Control Types#

By default, the control type is inherited from the type attribute set on the items object. However, some types allow for additional control types.

Note that the controlType field should be placed on the primary field definition, not within the items object.

`checkbox`#

Supported Types

enum

Required Properties

items.options should match the expected shape from the dropdown control type

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

export default {
  models: {
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        {
          name: 'colors',
          type: 'list',
          controlType: 'checkbox',
          items: {
            type: 'enum',
            options: [
              { label: 'Primary', value: 'primary' },
              { label: 'Secondary', value: 'secondary' },
            ],
          },
        },
      ],
    },
  },
}

These options are rendered as checkboxes, rather than individual controls.