Field types
How the addon maps Statamic fieldtypes to the types that
headquery generate writes:
| Statamic | TypeScript |
|---|---|
text, textarea, markdown, slug | string (| null unless required) |
integer, float, range | number |
toggle | boolean (never null) |
date | ISO string |
select, button_group, radio, checkboxes | HqOption<"a" | "b"> ({ key, value, label }; all null when empty) |
assets | HqAsset or HqAsset[] (max_files), see asset fields |
entries, terms, users | HqRelatedEntry, HqRelatedTerm, HqUser |
grid, replicator | arrays of typed rows/sets ([] when empty), sets as named types |
link | HqLinkUrl | HqLinkEntry | HqLinkAsset (never null), see Link |
bard | HTML string without sets; with sets an array of text items and typed sets ([] when empty), see Bard |
| unknown fieldtypes | unknown — 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)); // ReplicatorIf 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.
Link
A link field always returns an object, never a plain string:
| Value in the CMS | Type | Response |
|---|---|---|
URL, mailto:, relative path | HqLinkUrl | { 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 children | HqLinkUrl | { 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: booleanCMS 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.