Reference Tags

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:

{<Type>:<Identifier>(@<Site>):<Property>}

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: my-entry-slug, or mySection/my-entry-slug
    • Categories: my-category-slug or myGroup/my-category-slug
    • Global sets: setHandle

    Identifiers can also include the ID, UUID, or handle of a site 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. Note that no formatting will be applied to the price!
  • {globalset:siteInfo:description} — returns the value of a description field on a global set with the handle siteInfo.

# 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.

# Safety

Any time you allow dynamic references to other resources, it’s important to acknowledge some risks.

# Recursion

Reference tags are parsed recursively—so supposing you had a field with a reference to itself (or any other multi-element cyclical reference), Craft would go back and forth, parsing them until it ran out of memory!

# Untrusted Input

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—as an example, an anonymous user could submit {user:1:email} to try and get admin user’s email address.

This also applies to the GraphQL directive of the same name.