Skip to Content
CMSStatamicField types

Field types

How the addon maps Statamic fieldtypes to the types that headquery generate writes:

StatamicTypeScript
text, textarea, markdown, slugstring (| null unless required)
integer, float, rangenumber
toggleboolean (never null)
dateISO string
select, button_group, radio, checkboxesHqOption<"a" | "b"> ({ key, value, label }; all null when empty)
assetsHqAsset or HqAsset[] (max_files), see asset fields
entries, terms, usersHqRelatedEntry, HqRelatedTerm, HqUser
grid, replicatorarrays of typed rows/sets ([] when empty), sets as named types
linkHqLinkUrl | HqLinkEntry | HqLinkAsset (never null), see Link
bardHTML string without sets; with sets an array of text items and typed sets ([] when empty), see Bard
unknown fieldtypesunknown — see custom fieldtypes

Bard

A Bard field without sets returns its content as an HTML string (null when empty). With sets, Statamic returns an array instead: the text between the sets as HqBardText items ({ type: "text", text } with the HTML of the paragraphs) and one object per set, with the set’s fields, its id and the set handle as type (named types). Disabled sets are left out. Narrow on type to render each item:

function ({ , }: CalloutSet) { return < ={.}>{}</>; } function ({ , }: QuoteSet) { return < ={ ?? }>{}</>; } function ({ }: { : BlogEntry["body"] }) { return .((, ) => { switch (.) { case "text": return < ={} ={{ : . }} />; case "callout": return < ={. ?? } {...} />; case "quote": return < ={. ?? } {...} />; case "image": return . && < ={. ?? } ={..} ={.. ?? ""} />; } }); }

With save_html: true, Bard stores HTML, so the field is typed as a string even if it has sets.

Sets

Every Bard and Replicator set is exported as an interface named after its handle: callout → CalloutSet, text_image → TextImageSet. It has the set’s fields plus id (null for sets saved without one) and type, the set handle. A set used in several fields (copied, or imported from a fieldset) is one type, so one component renders it wherever it appears:

const = (: QuoteSet) => `${.} — ${.}`; declare const : BlogEntry; ..(() => (. === "quote" ? () : null)); // Bard ..(() => (. === "quote" ? () : null)); // Replicator

If sets with the same handle have different fields in different places, no ImageSet is generated. Each variant is named after where it’s used instead: {Collection}{Blueprint}{Field}{Set}Set, e.g. BlogBodyImageSet and PagesLandingBlocksImageSet. The blueprint is only part of the name for collections with several blueprints. Adding such a conflicting set renames the existing type, which shows up as a type error.

A link field always returns an object, never a plain string:

Value in the CMSTypeResponse
URL, mailto:, relative pathHqLinkUrl{ url: "https://…" }
Entry, or @child (first child page)HqLinkEntry{ id, title, url, permalink, api_url }
Asset (only with a container in the field config)HqLinkAsset{ id, url, permalink, api_url, alt }
Empty, deleted entry, @child without childrenHqLinkUrl{ url: null }

All of them have url, so link.url is enough for an href. To tell them apart, check for title (entry) or alt (asset):

function ({ }: { : BlogEntry["source"] }) { if (!.) return null; const = "title" in ? . : "alt" in ? (. ?? "Download") : .; return < ={.}>{}</>; }

A link to an unpublished entry still returns the entry: Statamic resolves links without checking the publish status.

Several blueprints

A collection can have several blueprints, and Statamic only returns the fields of an entry’s own blueprint. Codegen therefore emits one type per blueprint and a union for the collection, e.g. PagesEntry = PagesLandingEntry | PagesPageEntry. Each type has its blueprint’s handle in blueprint.handle. TypeScript doesn’t narrow a union on a nested property, so narrow with isBlueprint():

const = await .("pages").("contact").(); if ( && (., "landing")) { ..
PagesLandingEntry.show_hero: boolean

CMS field type: toggle

show_hero
;
}

To fetch only entries of one blueprint, use .whereBlueprint(), which narrows the result without isBlueprint().

The same field can have different types in different blueprints (summary is a textarea in page and an integer in landing); before narrowing, it’s the union of both. Collections with one blueprint get a single type, e.g. BlogEntry.

.fields([...]) accepts the fields of every blueprint. Statamic returns a requested field that isn’t in an entry’s blueprint as null, and the result type says so.

Terms don’t include their blueprint, so a taxonomy with several blueprints gets one type: fields that only some blueprints have are optional, and differing types are combined.

Asset fields

Asset fields (and links to assets) return a shallow asset: Statamic only includes id, url, permalink, api_url and alt. To get more keys of the asset, e.g. width, height and focus_css for an image loader, extend the shallow keys in a service provider:

// app/Providers/AppServiceProvider.php use Headquery\Statamic\Assets\ShallowAsset; public function register(): void { ShallowAsset::extend(['width', 'height', 'focus_css']); }

This binds Statamic’s asset class to one that adds the keys. If your project already binds its own asset class, extend() leaves it alone; add the HasExtendedShallowKeys trait to that class instead:

use Headquery\Statamic\Assets\HasExtendedShallowKeys; use Statamic\Assets\Asset as StatamicAsset; class Asset extends StatamicAsset { use HasExtendedShallowKeys; }

The schema export lists the extra keys (assetKeys), whichever way they were added, and codegen adds them to HqAsset and HqLinkAsset. Blueprint fields of an asset container are typed from that container’s asset type (tone: AssetsAsset["tone"]; with several containers the union, plus null when a container doesn’t have the field), so the container must be enabled in the API (resources.assets). Other keys of the full asset are typed from HqAssetBase (width: number | null), anything else as unknown.

System fields

System fields Statamic adds to every entry, term, global set and asset (id, url, status, permalink, …) come from HqEntryBase, HqTermBase, HqGlobalBase and HqAssetBase. Blueprint fields with the same handle take precedence.

An entry’s mount is the collection mounted on it ({ title, handle }, null for every other entry). Localizations carry their origin’s mount.

Filterable fields

Fields listed in allowed_filters (see Getting started) are marked filterable in the schema. Only those are accepted by .where().

Allowed filters that aren’t blueprint fields, such as an entry’s date or an asset’s basename and folder, are exported as systemFilters and accepted by .where() too.

Last updated on