Content Field

Reference field

The reference field allows the editor to select other elements like entries or assets.

myReferenceField:
  type: reference
  elementType: entry

This field definition creates the following input in the control panel:

A reference field in the control panel

We provide several aliases of the reference field for asset and entry references, please see aliases.

Attributes

Property Description
criteria Specifies additional filter criteria for the selectable elements.
elementType Required. The element class selected by the field, e.g. :code:`craft\elements\Asset`.
group Starts a new field group.
instructions Additional instructions for this field in the control panel. Will be shown beneath the field label.
label The primary `label` of the input field in the control panel. When omitted, a label will be generated from the name of the field.
limit The maximum number of references allowed.
rules The validation rules of the field.
sources A list of sources the entry can be picked from.
viewMode The view mode the input should use in the control panel. Must be either :code:`large` or :code:`small`.
width The width of the field in the control panel.

criteria

Specifies additional filter criteria for the selectable elements. The available filter criteria depend on the selected element type, we only list the most commonly used criteria here.

kind

Allows you to specify the asset kind the user is allowed to select. Craft defines the following file kinds:

  • access
  • audio
  • compressed
  • excel
  • flash
  • html
  • illustrator
  • image
  • javascript
  • json
  • pdf
  • photoshop
  • php
  • powerpoint
  • text
  • video
  • word
  • xml
  • unknown
criteria:
  kind:
    - image
    - video

elementType

The element class selected by the field. This can be any valid element class, both from the core or from other plugins.

elementType: craft\elements\Asset

The Craft CMS defines the following element classes:

  • craft\elements\Asset
  • craft\elements\Category
  • craft\elements\Entry
  • craft\elements\GlobalSet
  • craft\elements\Tag
  • craft\elements\User

limit

The maximum number of references allowed.

limit: 1

sources

A list of sources the entry can be picked from. The available options depend on the selected :code:elementType. For entry elements this usually controls which sections are available, for assets it controls which folders are available.

sources:
  - section:560258d5-d8a0-4625-bcd2-11ed7ff1b225

The content field includes a utility page that lists all sources of the common entry types, in the control panel visit :code:Utilities > :code:Content field utilities > :code:Sources.

viewMode

The view mode the input should use in the control panel. Must be either :code:large or :code:small.

viewMode: small

Templating

The reference field behaves like an array within the template, you can iterate over the selected references and receive the elements.

label: Reference field demo
fields:
  referenceField:
    type: reference
    elementType: craft\elements\Asset
---
<ul>
  {% for reference in referenceField %}
    <li>{{ reference.title }}</li>
  {% endfor %}
</ul>

You can also access references based on their index:

{% if referenceField|length > 0 %}
  {{ referenceField[0].title }}
{% endif %}

first / getFirst

The first helper allows you to quickly receive the first element.

{% if referenceField.hasValue %}
  {{ referenceField.first.title }}
{% endif %}

imageTag

The image tag helper allows you to render an asset reference as an image tag. To learn more about how image tags work, see :doc:../advanced/image-tags.

  {{ referenceField.imageTag('image-config-name') }}

Aliases

The reference field provides several aliases for commonly used field configurations.

entry

Allows the editor to pick one entry.

entryField:
  type: entry

entries

Allows the editor to pick multiple entries.

entriesField:
  type: entries

file

Allows the editor to pick one file.

fileField:
  type: file

files

Allows the editor to pick multiple files.

filesField:
  type: files

image

Allows the editor to pick one image.

imageField:
  type: image

images

Allows the editor to pick multiple images.

imagesField:
  type: images

← Select field →