Reference Field Type | Netlify Create Docs

Control Type

Reference preview with controls to open the editor for the referenced document, along with the ability to add and remove the reference.

Stored Value

API CMS: Uses built-in mechanisms to link records in the CMS to one another.

Git CMS: A string path to the referenced file.

Supported Models

Models must of type page or data. More on this in required properties below.

Supported Sources

Works with most content sources.

Usage Example#

Here is an example that shows a featuredPages field, referring to other page objects.

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

export default {
  references: {
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        {
          name: 'featuredSection',
          type: 'reference',
          fields: [
            {
              name: 'heading',
              type: 'string',
            },
            {
              name: 'backgroundImage',
              type: 'image',
            },
          ],
        },
      ],
    },
  },
}

This will render a preview of the referenced item, with support for adding, editing, and removing.

Clicking on the preview will drill down in to the editor for that embedded reference.

New vs Existing References#

Because we're simply linking to other content and not embedding directly in the page or component, you have the option to create or add an existing reference.

Required Properties#

Reference fields require that you specify one or more models that can be added to this field. You can do this using either the models or groups property, but not both.

groups

An array of group names pulled that match one or more groups on a model definition. Only models of type page or data will be available.

models

An array of models of type page or data to be referenced for the field value.

Choosing Multiple Models#

You have the option to choose from multiple models. Consider a scenario in which your page has a list of related pages or posts. You could use the groups or models property to achieve this.

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

export default {
  models: {
    Post: {
      fields: [
        // ...
      ],
    },
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        {
          name: 'relatedPages',
          type: 'reference',
          models: ['Page', 'Post'],
        },
      ],
    },
  },
}

When choosing to populate that field, you'll first be able to choose which model you'd like to use.

And, like mentioned above, you'll then be able to create a new reference or link to an existing reference. You can always delete the content to switch to a different model.

Choosing Multiple Reference Values#

When using on its own, this field type only accounts for adding a single reference to the field. If you want to store an array of multiple references on a single field, use a list field.

Similarities to Other References#

Reference fields are similar to object and model fields, with key differences for each scenario.

Object vs Reference#

object fields define the shape of the content directly within the field definition, while reference fields refer to another model or groups of models.

object fields also store content embedded in the parent, while reference fields leave a reference to the content, the result of which differs depending on your content source.

Model vs Reference#

model fields store content embedded in the parent, while reference fields leave a reference to the content, the result of which differs depending on your content source.