Interfaces & Types

A Hyper field returns a list of links, including a field configured for a single link. Every link implements the HyperLinkInterface interface, and each link type also has its own concrete type that adds the custom fields from its field layout. Queries shows how to request a Hyper field through Craft’s entry queries and set up the schema.

Interfaces

The HyperLinkInterface Interface

Select these fields directly on any Hyper field, without a link-type fragment. All of them are nullable.

{
  entries(section: "news", limit: 1) {
    ... on newsPost_Entry {
      resourceLinks {
        type
        text
        url
        target
        newWindow
        isElement
        element {
          id
          title
        }
      }
    }
  }
}

{
  "data": {
    "entries": [
      {
        "resourceLinks": [
          {
            "type": "verbb\\hyper\\links\\Entry",
            "text": "About Us",
            "url": "https://example.test/about",
            "target": null,
            "newWindow": false,
            "isElement": true,
            "element": {
              "id": "24",
              "title": "About Us"
            }
          }
        ]
      }
    ]
  }
}

Types

Concrete Link Types and Custom Fields

A concrete type is named {fieldHandle}_{PascalCaseLinkTypeHandle}_LinkType. For example, field resourceLinks and link type handle custom-url produce resourceLinks_CustomUrl_LinkType. Use the original handle from Settings → Fields, even when a layout gives that field an alias. The query uses the layout alias, while its concrete type keeps the original field handle so different fields remain distinct. The control-panel label does not determine the name.

Use a fragment on that concrete type to request its custom layout fields with their GraphQL types. Alternatively, fields returns permitted custom field values as a JSON string keyed by handle. Both forms respect the active schema’s field restrictions.

Names listed in HyperLinkInterface, such as text and url, always return Hyper’s link values. If a custom field’s layout handle matches one of these names, read its value from fields, or give it a unique layout handle to query it in a typed fragment.

Element links whose destinations are unavailable or outside the active schema are returned as null list items. Hyper does not resolve any interface or concrete-type fields for those items, so access to an owner entry does not grant access to its linked entry, category, asset, site, user or other element. Keep null items when list positions are significant to your client.

linkValue is JSON encoded, including scalar values. Embed links expose html, iframeSrc, embedImage and providerName so clients do not need to parse metadata for these common values. Those fields return null when the corresponding embed value is unavailable.

The custom-field example in Queries shows a fragment on a concrete type. Requesting fields instead returns a JSON string such as {"summary":"Opening hours and directions"}.

The HyperMissingLink Type

HyperMissingLink is the concrete type for a saved link whose link type is no longer available. It implements HyperLinkInterface, so request __typename to recognise it. Its saved label remains available through linkText, while url, text and link return null and fields returns the JSON string []. Hyper keeps the original content, so restoring the link type makes the link usable again.

resourceLinks(empty: null) {
  __typename
  linkText
  url
}

{
  "resourceLinks": [
    {
      "__typename": "HyperMissingLink",
      "linkText": "Old download",
      "url": null
    }
  ]
}

The ArrayType Scalar

ArrayType is a JSON scalar used by customAttributes. Request the field name on its own, and your client receives the attributes as structured data.