Reference field

Search and link entries from another collection.

Use when one content type needs to point to another collection (posts -> authors, products -> categories).

reference is collection-backed. It searches another configured collection and saves the selected entry value.

Options

Key Description
collection Target collection name (e.g. "authors").
multiple If true, allows many references.
min Minimum number of selected references when multiple is enabled.
max Maximum number of selected references when multiple is enabled.
search Comma-separated fields used for lookup (e.g. "name,email").
value Template for the stored value (e.g. "{path}").
label Template for the displayed label (e.g. "{name}").

Template tokens

value and label support template strings.

Token Description
{path} Entry path.
{name} Entry name.
{primary} Primary field value from the referenced collection. Uses view.primary, otherwise title, otherwise the first field.
{fields.<path>} Field value from the referenced entry. Nested paths are supported, for example {fields.author.name}.
{<path>} Shorthand alias for {fields.<path>} when no direct token resolves, for example {author.name}.

Pages CMS resolves reference templates in this order:

  1. Try the token as written.
  2. If nothing resolves, try the same token under fields.*.

Examples

Basic reference

- name: author
  type: reference
  options:
    collection: authors

Multiple references

- name: categories
  type: reference
  options:
    collection: categories
    multiple: true
    min: 1
    max: 5

Search across multiple fields

- name: author
  type: reference
  options:
    collection: authors
    search: "name,email,fields.role"

Custom stored value and label

- name: author
  type: reference
  options:
    collection: authors
    value: "{primary}"
    label: "{primary}"

This stores and displays the referenced entry's primary field value.

Multiple references with nested labels

- name: speakers
  type: reference
  options:
    collection: people
    multiple: true
    search: "name,fields.profile.title,fields.company.name"
    value: "{path}"
    label: "{profile.name} ({company.name})"