Link
A Link represents one destination and its saved label, attributes and custom fields. Obtain one with entry.myLinkField.first() or by looping over a Hyper field. first() can return null; the field itself is a LinkCollection.
Rendering Links provides template examples. This page describes the individual object and its saved content.
Properties
Type: string
Link class name, such as verbb\hyper\links\Entry.
Type: verbb\hyper\base\LinkInterface|null
Settings prototype for the link’s configured handle.
Type: string|null
Resolved destination after applying the prefix, suffix and URL-policy checks. Returns null when the destination is absent or unavailable; a suffix alone does not create a destination. Stored destinations are literal text; environment-variable references and Craft aliases are not expanded.
Type: string|null
Display label using entered text, layout defaults and type-specific fallbacks. Ordinary links return null without a usable URL. Passive links can return a label without a URL.
Type: string|null
_blank when the link opens in a new window; otherwise null.
Type: bool|null
Saved new-window choice; target uses the resolved choice including applicable field defaults.
Type: string|null
Type-specific destination before prefix and suffix.
Type: string|null
URI of the resolved element, if available.
Type: mixed
Type-specific stored value: a URL string, element ID, site UID or embed metadata.
Type: string|null
Link Text with layout defaults and type-specific fallbacks.
Type: string|null
Only the editor-entered Link Text; null when blank.
Type: string|null
HTML aria-label value.
Type: string|null
Suffix such as a query string or fragment.
Type: string|null, title
HTML title value, not the title of a selected entry.
Type: string|null
HTML class value.
Type: array
Additional HTML attribute name/value pairs, subject to attribute-name validation.
Custom layout fields are accessible by their handles. Values on the selected destination are accessed through getElement() instead.
Methods
Returns: craft\base\ElementInterface|null · Return and Behaviour: Selected Craft element or null. Entry links default to live entries; other element types use their applicable enabled status.
Selected Craft element or null. Entry links default to live entries; other element types use their applicable enabled status.
Returns: bool · Return and Behaviour: Whether the selected element can be resolved with the requested status.
Whether the selected element can be resolved with the requested status.
Returns: Twig\Markup|null · Return and Behaviour: Twig markup for an anchor, or null without a usable URL. The special text key overrides its label. Ordinary strings are escaped; trusted Twig markup is preserved.
Twig markup for an anchor, or null without a usable URL. The special text key overrides its label. Ordinary strings are escaped; trusted Twig markup is preserved.
Returns: Twig\Markup|array · Return and Behaviour: Attribute array, or Twig markup containing the attribute string when asString is true.
Attribute array, or Twig markup containing the attribute string when asString is true.
Returns: string|null · Return and Behaviour: Editor-entered text only, or null when blank.
Editor-entered text only, or null when blank.
Returns: bool · Return and Behaviour: Whether the link resolves to no non-blank URL. Labels, attributes and custom fields do not make a destination-less link non-empty. Unavailable targets and Passive links are empty; stored content is still retained.
Whether the link resolves to no non-blank URL. Labels, attributes and custom fields do not make a destination-less link non-empty. Unavailable targets and Passive links are empty; stored content is still retained.
Element links also expose linkSiteId, the selected destination’s site ID. For efficient access to their fields, see Loading Links.
Embed Links
Returns: Twig\Markup|null · Return and Behaviour: Stored embed HTML as Twig markup, or null.
Stored embed HTML as Twig markup, or null.
Returns: string|null · Return and Behaviour: First iframe source in stored embed HTML, or null.
First iframe source in stored embed HTML, or null.
Returns: string|null · Return and Behaviour: Stored thumbnail/image URL, or null.
Stored thumbnail/image URL, or null.
Returns: string|null · Return and Behaviour: Stored provider name, or null.
Stored provider name, or null.
Returns: array|null
Available on Embed links.
Return and Behaviour: Embed metadata on an Embed link.
Embed metadata on an Embed link.
For example, a URL link’s linkValue is an address string, an Entry link identifies an element, and an Embed link can store an object containing url, title, code and other provider metadata. Available embed keys depend on the fetched result.
Saved Content
Hyper stores each link’s content on its owner rather than saving a Craft element row for each link. A LinkInstance carries supported values while Links::createLinkFromInstance($field, $instance) creates the runtime Link object using its configured type and layout.
The supported content includes linkTypeHandle, uid, linkValue, linkSiteId, newWindow, linkText, ariaLabel, urlSuffix, linkTitle, classes, customAttributes and fields. Empty optional values may be omitted. Custom field values are stored by their layout placement UID; normal programmatic input can supply them by handle.
Use linkTypeHandle when selecting an exact configured type in a content array. Input also accepts handle, or type containing a registered class name or built-in type key. Field settings and the content type identifier are separate contracts; do not put a complete type definition into each content row.
For conversions of raw values, use Managing Embedded Content. For normal element saves, follow Creating Links Programmatically.
Built-in Classes
All names below are in the verbb\hyper\links namespace. Types requiring another plugin are available only when their dependency is enabled.
| Class | Destination |
|---|---|
Asset | Craft asset. |
CalendarEvent | Calendar event. |
Category | Craft category. |
Custom | Custom address subject to the shared URI policy. |
Email | Email address. |
Embed | Remote URL and its embed metadata. |
Entry | Craft entry. |
FormieForm | Formie form. |
Passive | Label without a destination URL. |
Phone | Phone number. |
Product | Commerce product. |
ShopifyProduct | Shopify product. |
Site | Craft site. |
Url | Relative or absolute address. |
User | Craft user. |
Variant | Commerce variant. |