LinkCollection

A Hyper field returns a LinkCollection in both single-link and multiple-link mode. Use it to render the first link, loop over links, or select links by their type and custom fields. Enable Multiple Links controls authoring; the template API stays the same.

The examples below belong in an entry’s Twig template and assume a Hyper field with the handle myLinkField.

Render Links

Render the first non-empty link:

{{ entry.myLinkField.getLink() }}

Render every non-empty link in the saved order:

{% for link in entry.myLinkField %}
    {{ link.getLink() }}
{% endfor %}

A link is empty when it cannot resolve a non-blank URL. Labels, classes and custom fields alone do not give it a destination. Links to unavailable entries and Passive labels are empty under this definition. Hyper resolves the destination locally; it does not request an external website to check whether it exists.

Iteration, array access, first(), count(), exists() and rendering shortcuts all use the current selection. Loop metadata such as loop.length and loop.last describes that selection. With no matches, first() returns null, getLink() outputs nothing and a loop’s {% else %} branch runs.

Filter Links

Suppose you have a custom URL type with the handle externalResource, with a Lightswitch field called featured in its layout. Display only featured resources:

{% for link in entry.myLinkField.where({ handle: 'externalResource', featured: true }) %}
    {{ link.getLink() }}
{% endfor %}

handle identifies a configured link type, so two custom URL types can be selected independently. The native type attribute contains the PHP class name; for example, { type: 'verbb\\hyper\\links\\Url' } selects URL links across their configured handles.

Conditions can read native link attributes and normalised custom fields by handle. Prefix a custom field handle with fields. when it overlaps a native attribute, such as 'fields.title'. A field absent from a link’s layout reads as null. Comparisons support text, numbers, booleans and date values. Relation queries and complex field values need their own field APIs rather than scalar comparisons.

For example, with a Number field called priority on that type:

{% set resources = entry.myLinkField
    .where({ handle: 'externalResource' })
    .andWhere(['>=', 'priority', 10])
    .orderBy('priority DESC')
    .limit(3) %}

{% for link in resources %}
    {{ link.getLink() }}
{% endfor %}

Filters return a new selection and leave the original collection unchanged. where() replaces the ordinary conditions; andWhere() and orWhere() combine them. The empty-link scope is separate, so replacing conditions or adding an OR branch does not include empty links accidentally. Equal sort values keep their saved order, and overlapping OR branches return each occurrence once without collapsing repeated links.

You can iterate a selection directly. Call all() when another API needs an array; it returns the same links. No query() call is required.

Empty Links

Use empty() to control which destinations are included:

To inspect unfinished links and their entered labels:

{% for link in entry.myLinkField.empty(true) %}
    <p>{{ link.customLinkText ?? 'Unlabelled link' }}</p>
{% endfor %}

A selection containing empty links is still a non-empty collection: empty(true).isEmpty() answers whether that selection has any rows. On an individual Link, isEmpty() answers whether that link has a destination.

Passive labels also need explicit inclusion. Rendering Links shows a list containing both anchors and labels.

Condition Operators

Hash conditions combine attributes with AND. An array value is an IN condition: { handle: ['url', 'externalResource'] }. Operator conditions use an array beginning with the operator:

like checks for a case-insensitive substring; it does not use SQL wildcard syntax. Date comparisons accept date objects, for example ['>=', 'publishDate', now] when the selected type has a Date field named publishDate. These filters operate on this field’s links in memory, rather than searching links across entries.

Methods

{% set link = entry.myLinkField.first() %}
{% if link %}
    {{ link.getLink() }}
{% endif %}

Editing Stored Content

Selection methods affect reads. They never remove links from the editor or from saved content. Craft’s field-level storage emptiness check remains based on authored content, so first saves and propagation retain rows that have no destination. The following methods work on the complete stored collection, independently of its selection.

Array reads use zero-based selected positions. Replacing or unsetting a position changes that selected record; appending adds a stored link, which appears in the selection only if it matches. Selection objects share their Link objects, so editing a selected Link changes that object. Explicitly cloning a collection clones its Link objects as well.

Service code can type-hint LinkCollectionInterface for selection and stored-content methods. Creating Links Programmatically shows how to construct links and save the collection on an owner.