Visual Surface
A visual option’s surface property is a verbb\buttonbox\fields\data\VisualSurfaceData object describing colour, dimensions or typography. Obtain it with {% set surface = entry.brandSurface.surface %}. The object exists even when no surface is configured. Its mode is then null.
See Surface Definitions for supported modes, configuration keys and bounds. These describe authoring previews and do not impose frontend styles.
Properties
Properties that do not apply, or were not supplied, are null. Rendering defaults are not necessarily populated into the data object. See the ButtonBoxVisualSurface type for schema types.
The surface mode, such as solid, gradient or text, or null when the option has no surface. Surface Definitions lists every mode.
The surface’s single value, such as a colour for solid, a percentage for width or a ratio for ratio. This is null when the mode doesn’t use one.
The first colour in a split or gradient, or the foreground colour for foregroundBackground.
The second colour in a split or gradient, or the background colour for foregroundBackground.
The split or gradient direction in degrees.
The corner radius of a shape surface, in pixels.
The preview font size of a text surface, in pixels.
The proportions of a shape surface, such as 1:1.
For a Visual Choice field with handle brandSurface using the example option set, this entry-template snippet reports the selected gradient metadata:
{% set option = entry.brandSurface %}
{% if option.valid and option.surface.mode == 'gradient' %}
<p>{{ option.label }}: {{ option.surface.from }} to {{ option.surface.to }}, {{ option.surface.angle ?? 135 }} degrees.</p>
{% endif %}For public components, prefer mapping stable values to your project's classes or design tokens. Button Box does not provide a public rendering helper or load its control-panel CSS on your site.