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