Link Fields New!

The link field replaced the URL field in Craft 5.3. Your existing fields will be automatically enhanced with the new UI. If you want to take advantage of the new features (like linking to assets, categories, and entries), check out the field’s settings screen.

Link fields provide a flexible way to link to on- and off-site resources, including assets, categories, entries, email addresses, phone numbers, or arbitrary URLs.

Screenshot of the link field interface in the Craft control panel

A link field’s value (when populated) is always suitable for use as an anchor tag’s href attribute:

<a href="{{ supportType.action }}">{{ supportType.title }}</a>

# Settings

my-craft-project.ddev.site/admin/settings/fields/new
Link field settings screen in the Craft control panel
Adding a new link field via the control panel.

In addition to the standard field options, Link fields have the following settings:

  • Allowed Link Types — The type of resource(s) that can be linked. Selecting more than one link type displays a dropdown menu for the author.
    • URL — The value must be a valid URL, beginning with http:// or https://.
    • Asset — Select an asset element.
    • Category — Select a category element.
    • Email — The value is automatically prepended with mailto:.
    • Entry — Select an entry element.
    • Phone — The value is automatically prepended with tel:.
  • Max Length – The maximum number of characters the field can contain. (Defaults to 255.)

When selecting a link type that references elements, Craft will display a set of checkboxes that allow you to limit selection to specific sources—and in the case of assets, the allowable file kinds.

# The Field

Link fields have—at minimum—an input specific to the allowed type of link. If more than one link type is allowed, a dropdown menu will be shown before the field, allowing the author to switch between them and use a specialized input to define a value.

# Development

Outputting a link field in a template will return a normalized value suitable for use in an anchor tag’s href attribute:

{% if entry.myLinkFieldHandle %}
  <h3>Link</h3>
  {{ tag('a', {
    text: 'Learn More',
    href: entry.myLinkFieldHandle
  }) }}
{% endif %}

# LinkData

The link field returns a craft\fields\data\LinkData (opens new window) object. When used as a string, its value is intelligently coerced to something URL-like—for element links, the element’s URL; for phone links, the number prefixed with tel:; and so on!

You can check what type of link the author selected, or access a selected element, directly:

{% if entry.myLinkFieldHandle.type == 'entry' %}
  {{ entry.myLinkFieldHandle.element.render() }}
{% else %}
  {{ entry.myLinkFieldHandle.link }}
{% endif %}

The valid type values are asset, category, email, entry, phone, and url.

Like elements, you can also render a complete anchor tag:

{{ entry.myLinkFieldHandle.link }}

Craft will figure out the best textual representation of the link—a selected element’s title, the URL (sans protocol), or the raw phone number, for example. That text—or label—can be retrieved via the LinkData model, in addition to the raw value:

<a href="{{ entry.myLinkFieldHandle.value }}">{{ entry.myLinkFieldHandle.label }}</a>

# Relations

When using an element in a link field, Craft makes the corresponding connections in its relations system. This means that you can query for elements via link fields, just like other relational fields:

{% set backlinks = craft.entries()
  .relatedTo({
    targetElement: post,
    field: 'myLinkField',
  })
  .all() %}

{# -> Returns other entries connected to the given `post` via a specific link field. #}

It is not currently possible to eager-load link field relationships, as their element type is not known until the field data is loaded.