Interfaces & Types
Button Box adds three object types to Craft’s GraphQL schema for the values of its fields. The other fields return scalar values. Queries shows how to request these values through Craft’s entry queries.
| Field | GraphQL Type |
|---|---|
| Visual Choice | ButtonBoxVisualOption |
| Visual Multi-Choice | [ButtonBoxVisualOption] |
| Position | ButtonBoxPosition |
| Width | String, with a label argument |
| Rating | Int |
Action Links fields aren’t included in the schema.
Field Value Types
A ! after a field’s type means it’s never null.
The ButtonBoxVisualOption Type
A Visual Choice field returns one ButtonBoxVisualOption, and a Visual Multi-Choice field returns a list of them. Each describes a choice and its visual metadata.
cardTreatment {
value
label
valid
icon
imageUrl
imageAlt
}{
"cardTreatment": {
"value": "featured",
"label": "Featured",
"valid": true,
"icon": "star",
"imageUrl": null,
"imageAlt": null
}
}The option’s category metadata, for templates and integrations.
A simple colour cue for the option.
The supporting text for the option.
Whether the option is unavailable for selection.
The reason a disabled option is unavailable.
A Craft, custom gallery or bundled icon identifier.
The alternative text for the option’s image.
The resolved URL of the option’s image.
The option’s configured label.
Whether the option is selected.
The option’s colour, dimension or typography metadata. See the ButtonBoxVisualSurface type.
Whether the value matches an enabled option in the field’s current options.
The option’s stored identity.
The ButtonBoxVisualSurface Type
ButtonBoxVisualSurface describes a visual option’s colour, dimensions or typography. Request it through an option’s surface field. Properties that don’t apply to the mode, or weren’t supplied, are null. Option Data lists the supported modes and their bounds.
The split or gradient direction in degrees.
The shape’s proportions, such as 1:1.
The first colour in a split or gradient, or the foreground colour.
The surface mode, such as solid, gradient or text. This is null when no surface is configured.
The shape’s corner radius in pixels.
The typography preview size in pixels.
The second colour in a split or gradient, or the background colour.
A colour, percentage or ratio, as a string.
The ButtonBoxPosition Type
A Position field returns a ButtonBoxPosition, describing the selected position and where it sits in the configured arrangement. Alignment is worked out from the standard named values, so a custom identity has null horizontal, vertical, x and y values.
focalPosition {
value
label
horizontal
vertical
}{
"focalPosition": {
"value": "bottom-right",
"label": "Bottom right",
"horizontal": "right",
"vertical": "bottom"
}
}The one-based column in the arrangement, or null when no configured option matches.
Whether the configured position is unavailable for selection.
The named horizontal alignment, left, center or right.
The position’s configured label.
The one-based row in the arrangement, or null when no configured option matches.
Whether the value is an enabled position or an empty selection.
The stored position identity.
The named vertical alignment, top, center or bottom.
The horizontal position, -1 for left, 0 for centre and 1 for right. These aren’t CSS percentages.
The vertical position, -1 for top, 0 for centre and 1 for bottom.