Reference Tags

You are viewing documentation for an unreleased version of Craft CMS. Please be aware that some pages, screenshots, and technical reference may still reflect older versions.

Reference tags can be used to create references to specific elements in your site from any textual fields, including text cells within a Table field. Some field types automatically parse reference tags, and others may need to be explicitly parsed.

A reference tag usually takes this form:


Curly braces ({}) surround three segments, separated by colons (:):

  1. <Type> – The type of element you’re creating a reference to. This can be a fully-qualified element class name (e.g. craft\elements\Entry) or the element type’s “reference handle”.

    Core element types have the following reference handles:

    • Addresses: address
    • Assets: asset
    • Categories: category
    • Entries: entry
    • Global Sets: globalset
    • Tags: tag
    • Users: user
  2. <Identifier> – Either the element’s ID or a custom identifier supported by the element type.

    Entries support the following custom identifier:

    • sectionHandle/entry-slug

    Identifiers can also include the site ID, UUID, or handle that the element should be loaded from, using an @<Site> syntax.

  3. <Property> (optional) – The element property that the reference tag should return. If omitted, the element’s URL will be returned.

    You can refer to the element types’ class references for a list of available properties:

    Custom field handles are also supported, for field types with values that can be represented as strings.

# Examples

The following are all valid reference tag formats:

  • {asset:123:filename} – returns the filename of an asset with the ID of 123 (via craft\elements\Asset::getFilename() (opens new window)).
  • {entry:blog/whats-on-tap} – returns the URL of an entry in a blog section with the slug whats-on-tap.
  • {entry:blog/whats-on-tap@en:intro} – returns the value of an intro custom field on a blog section entry with the slug whats-on-tap, loaded from the site with the handle en.
  • {craft\commerce\Variant:123:price} – returns the price of a Commerce Variant object with the ID of 123.
  • {globalset:aGlobalSet:uid} – returns the UID of a global set with the handle aGlobalSet.

# Generating Tags

Some element types (assets, for instance) allow you to copy a basic reference tag from element indexes. Select a single row, then use the actions menu

to Copy reference tag. You can edit the copied tag to output a specific property—or let Craft decide the best representation (typically its URL).

# Parsing Reference Tags

You can parse any string for reference tags in your templates using the parseRefs filter:

{{ entry.body|parseRefs|raw }}

The equivalent function is available via craft\services\Elements (opens new window):

$parsed = Craft::$app->getElements()->parseRefs($text);

Both functions take an optional $siteId param, which will determine what site the references are assumed to be in, if a tag doesn’t explicitly declare one.

Do not pass untrusted user input through parseRefs! Reference tags allow access to arbitrary properties and can lead to exfiltration (opens new window) of private data.