Reference field
A reference field in Drupal stores a link from one entity to another, such as a recipe to its vendor, its taxonomy terms or the user who wrote it.
A reference field is a Drupal field that stores a relationship between one entity and one or more other entities. Instead of holding text, it holds a pointer, such as a recipe pointing to its vendor, a page pointing to its categories, or an article pointing to its author. The pointed-to entity can be of the same or a different entity type.
How reference fields work in Drupal 11
In core, the field type is called entity_reference, and its settings require a target_type: the entity type the field points at. Its default widget is entity_reference_autocomplete, and its default formatter is entity_reference_label. In the field creation screen it appears as Reference. The API description reads that you choose the content or configuration type to reference on the next screen.
The user guide describes three common cases:
- Content reference: a field on one content type that points to items of another content type.
- Taxonomy term reference: a field that attaches terms from a vocabulary to content.
- User reference: a field that points to user accounts.
Core uses the same mechanism internally. The parent of a taxonomy term, for instance, is stored in an entity_reference base field named parent.
Example
To let each Recipe point to a Vendor, go to Structure › Content types › Recipe › Manage fields and add a new field of the type Reference. Then choose these settings, as in the user guide:
- Type of item to reference: Content.
- Reference method: Default, with the content type set to Vendor.
- Sort by: Vendor name, in ascending order.
- Allowed number of values: limited to 1.
Editors then pick a vendor from a list instead of typing the vendor's name again on every recipe.
Common mistakes
- Typing the same value into a text field. A typed vendor name can be misspelled on every page. A reference keeps a single source of truth.
- Pointing at the wrong entity type. The type of item to reference is a required setting of the field, so decide it before you create the field.
- Leaving the number of values at the wrong limit. A single author needs one value; a list of ingredients needs unlimited. Pick deliberately under Allowed number of values.
- Letting editors create terms freely. The option Create referenced entities lets editors add new terms from the content form. That helps with tags, but a tidy category list may need it switched off, so decide for each field.
For marketing and content teams
When an edit form shows a box where you start typing and then pick a suggestion, you are probably using a reference field; autocomplete is its default widget. Choose the existing item rather than retyping it; that is what keeps authors, categories and related pages consistent across the site. If a choice you need is missing, ask whether the reference allows new items to be created from the form, or whether a developer or site builder must add the item first. A reference field that points at taxonomy terms is the usual way to categorize and tag content.