Verbb
You are viewing beta documentation for Hyper 3.x. View the latest stable version (2.x) →
Developers

GraphQL

Hyper supports accessing Link objects via GraphQL. Be sure to read about Craft's GraphQL support (opens new window).

In order to query a link, you'll need to first query the element that the Hyper field is attached to.

Example

{
    entries (section: "news", limit: 1) {
        myLinkField {
            url
            text
        }
    }
}
{
    "data": {
        "entries": {
            "myLinkField": [
                {
                    "url": "http://my-site.test/some-url",
                    "text": "Some Text"
                }
            ]
        }
    }
}

Note that for consistency with the GraphQL spec, the value for a Hyper field will always be an array of LinkInterface's, regardless of whether your Hyper field is set to be a multi-link field or not.

The LinkInterface interface

This is the interface implemented by all links.

FieldTypeDescription
ariaLabelStringThe aria-label attribute for the link.
classesStringThe class attribute for the link.
elementElementThe element (if provided) for the link.
isElementBooleanWhether the chosen link value is an element.
isEmptyBooleanWhether a link has been set for the field.
linkStringThe HTML output for a <a> element.
linkTextStringThe resolved link label before layout defaults (custom Link Text if set; otherwise type-specific fallbacks such as element titles when the Link Text field is empty).
customLinkTextStringOnly the Link Text field value, with no fallbacks. Null when blank—use for explicit defaults in your API client.
linkUrlStringThe url for the link.
linkValueStringRaw link data as a JSON string (full embed metadata for Embed links).
htmlStringEmbed HTML (code) when this is an Embed link; otherwise null.
iframeSrcStringThe src of the first iframe in embed HTML, when present.
embedImageStringThumbnail/image URL from embed metadata, when present.
providerNameStringoEmbed provider name for Embed links (e.g. YouTube), when present.
fieldsStringCustom layout field values as a JSON object keyed by handle (no type cast required).
newWindowBooleanWhether the link should open in a new window.
targetStringThe target attribute for the link.
textStringThe fully derived link label (custom text, type fallbacks, then field placeholder or plugin default).
titleStringThe title attribute for the link.
typeStringThe link type.
urlStringThe url for the link.
urlPrefixStringThe url prefix for the link.
urlSuffixStringThe url suffix for the link.
linkUriStringThe link URI, if an element-based link.
customAttributesArrayTypeThe custom attributes for the link.

Custom Fields

Custom fields on a link type are available in two ways:

  1. Typed fragments — cast to the concrete *_LinkType for typed GraphQL fields.
  2. fields JSON bag — read all layout field values without knowing the link type (useful for headless clients that branch in application code).
myLinkField {
    url
    text
    type
    fields

    ... on myLinkField_Url_LinkType {
        plainText
    }

    ... on myLinkField_CustomUrl_LinkType {
        anotherField
    }
}

For Embed link types, prefer the dedicated interface fields over parsing linkValue:

myLinkField {
    url
    text
    html
    iframeSrc
    embedImage
    providerName
    linkValue
}

iframeSrc extracts the first iframe src from the stored embed HTML. linkValue remains the full JSON metadata blob for advanced use.

For typed fragments, use PascalCase of the link type handle (not the CP label). For example, handle custom-url becomes myLinkField_CustomUrl_LinkType.

Last updated: July 22, 2026, 11:43:55 AM
Previous Events Next Guides