Product guide

Product configuration, explained

A product configuration is the recipe the customiser follows: which areas of your product shoppers can personalise, what they can put there, and how the result is previewed and printed. This guide walks through every part in plain English — no coding needed.

Where you’ll meet this: in your dashboard under Configurations, where every section below has its own visual editor. The same structure appears as JSON in the editor’s Import JSON box and JSON Preview tab — useful when copying a configuration between products or importing one we’ve prepared for you.
01

The big picture

Every product configuration is one document with six parts. Three are always there; the rest switch on extra features. Tap a card to jump to its section.
product configuration · the six parts
zonesRequired
Zones
The customisable areas — each becomes a step in the customiser.
mappingsRequired
Mappings
Colour dictionaries and the step order for each customisation type.
descriptionRequired
Description
A private note to help you identify this configuration in the dashboard.
threeDScenesOptional
3D scenes
The spinning 3D previews: teaser, colour selector and confirmation.
builderSpecOptional
Builder logic
Rules that adapt the config to what the shopper picked on the store page.
hostedPageOptional
Hosted page
The product page for Kastomise-hosted shops: price, gallery, options.
About the description: the top-level description is a private note (“Add a description to help identify this configuration”) — shoppers never see it. The shopper-facing product title is written by Builder logic or the Hosted page title instead.
02

Sizes & positions — everything is centimetres

Every size and position in a configuration describes the real printed product, measured in centimetres from the top-left corner. Get the centimetres right and the preview, and the final print, follow automatically.
one zone canvas · real print size, in centimetres
x: 0, y: 0x →y ↓width: 12 cmheight: 12 cmx: 4.5, y: 2.5
Positions describe the finished, printed product at true size — the widget scales everything to fit the shopper’s screen automatically.
originalSize
Print size (cm)
The width and height of the printable area, exactly as it will be produced. Every position inside the zone is measured against this.
e.g. { "width": 12, "height": 12 }
canvasOffset
Canvas offset (cm)
Nudges everything inside a zone (or a composite section) right (x) and down (y) as one group. Usually 0, 0.
e.g. { "x": 0, "y": 0 }
Three exceptions to remember: text line height is a multiplier of the font size (1 = single spacing), obstruction top/left anchors are percentages of the canvas, and 3D scene values use their own units (degrees, 3D coordinates).
03

Zones — the steps of the customiser

Zones define the customisable areas of your product. Each zone is one step in the customiser pop-up: a frame might have an image zone for photos, a text zone for engraved details, and a model-colour zone for picking colours in 3D.
zones → steps in the customiser pop-up
1
The Background
image zone
2
The Frame
text zone
3
Model Colour
model colour zone
Each zone’s title becomes the step’s heading. Which zones appear, and in what order, comes from Zone Order.

The four zone types

Imagetype: "image"
Photos & graphics — shoppers upload pictures into layout slots.
Texttype: "text"
Text content — shoppers type into fields you define and validate.
Compositetype: "composite"
Mixed image + text sections rendered together in one canvas, as one step.
Model Colourtype: "modelColour"
A 3D colour picker — shoppers recolour parts of the 3D model.

Settings every zone shares

zones.<key>
Zone keyManaged for you
The zone’s internal name (background, textArea, …). Auto-generated from the label when the zone is created, then locked — other parts of the config (Zone Order, 3D colour areas) refer to zones by this key.
type
Zone typeRequired
One of image, text, composite or modelColour — see the cards above.
title
LabelRequired
The step’s heading, shown to shoppers.
e.g. "The Background"
originalSize
Print size (cm)
Width × height of this zone’s printable area — see Sizes & positions.
backgroundColour
Background colour
The zone’s base colour. Usually filled in automatically from the colour mappings based on the shopper’s chosen product colour.
e.g. "#ffffff"
backgroundMasks
Background masks
SVG shapes drawn over the zone — see Background masks.
layoutOptions
Layout options
The arrangements shoppers can pick — image slots for image zones, text fields for text zones.
04

Background masks

A mask is an SVG shape drawn over a zone — the “window” or decorative frame that gives the printable area its outline. A zone can hold several masks and show the right one for what the shopper picked.
backgroundMasks · one shape per condition
condition: "default"
always shown as the fallback
condition: "3"
shown when the shopper picks 3
condition: "4"
shown when the shopper picks 4
Example from the demo frame: one mask per ribbon width, each cut with a wider notch. Only one mask per zone can be the default.
condition
When to show it
"default" marks the zone’s fallback mask — always shown unless a conditional mask matches. Any other value makes the mask conditional: it appears only when the shopper’s selection matches (typically an obstruction slider value, like a ribbon width of 2, 3 or 4). Only one mask per zone can be the default.
asset
SVG asset
The SVG code of the shape itself. The dashboard’s mask editor validates and previews it as you paste.
e.g. "<svg width=\"120\" …></svg>"
05

Image zones — layouts and photo slots

An image zone offers up to three ready-made layouts. Each enabled layout defines its own photo slots — where each uploaded picture sits and how it fills its space.
layoutOptions · the three image layouts
Whole
Single full image
"whole"
holds 1 image
Two Column
Side by side
"two-column"
holds up to 2 images
Four Grid
2×2 grid layout
"four-grid"
holds up to 4 images
Enable any mix of the three; shoppers switch between them in the customiser. defaultLayout picks which one loads first.

Each photo slot — fields inside a layout

id · label
Slot name
id is the slot’s stable internal name (image-0, image-1, …); label is what shoppers see on the upload card (“Image 1”).
x · y · width · height
Position & size (cm)
Where the slot sits on the zone canvas and how big it is — measured from the top-left, in centimetres.
e.g. { "x": 6, "y": 0, "width": 6, "height": 6 }
containerSize
Container size (cm)
The visible window the photo is placed into — its own width, height and position. Usually matches the slot itself.
containerType
Fill behaviour
How the photo fills its window — cover crops to fill, contain fits inside. See below.
visibleImageIndices
Visible slotsManaged for you
Which slots the layout displays, in order. The dashboard keeps this in sync with the slot list for you.
xOffset · yOffset
Print nudges (cm)Advanced
Tiny corrections applied at print time. Almost always 0.
containerType · how a photo fills its slot
"cover"
The photo fills the whole slot — anything outside is cropped away. No empty edges.
"contain"
The whole photo stays visible inside the slot — it may leave empty space at the edges.
06

Text zones — what shoppers type, and what gets printed

A text zone offers one or more layouts — say “Standard” and “Custom” arrangements of the engraving. Every layout keeps two lists: input fields (the boxes shoppers type into) and display fields (the lines that actually land on the product).
input fields → display fields
What the shopper types · inputFields
PIP
12345
Location
LONDON
Date
12/04/2026
Distance (km)
42.2
Time
3:28:14
What lands on the product · displayFields
12345
standalone — mirrors the PIP field exactly
LONDON·12/04/2026
composite — Location + separator + Date
/ 42.2KM / 3:28:14
composite — separators only appear when their fields are filled in
Orange marks the separators — fixed text stitched between field values by a composite display field’s parts.

The layout itself

id · label
Layout name
label is the option shoppers pick (“Standard Layout”); id is its internal name. The first layout in the list is the default.
asset
Layout icon (SVG)
A small SVG preview of the arrangement, shown on the layout picker (a 96×21 viewBox works best).
inputFields
Input fields
What the shopper types — details below.
displayFields
Display fields
What appears on the product — details below.

Input fields — inputFields

id · label
Field name
label is shown above the box (“Location”); id is how display fields refer to it.
info
Help text
An optional hint under the box. Wrap a phrase in <highlight> to make it stand out.
e.g. "Accept format <highlight>dd/mm/yyyy</highlight> …"
validation
Validation rules
Keeps entries printable. Two kinds, told apart by the value: a number caps the length (with a live character counter); a pattern (text starting with ^) restricts which characters are allowed — numbers only, dates, times. Each rule’s message is the error shown to the shopper.
e.g. { "value": 6, "message": "PIP must be less than 6 characters" }

Display fields — displayFields

displayType
Standalone or composite
standalone mirrors one input field exactly (named by sourceFieldId). composite stitches several inputs into one printed line (listed in sourceFieldIds) using parts.
parts
Composite recipe
An ordered list of pieces: a field part inserts an input’s value; a separator part inserts fixed text (value) that only appears when the fields named in showIf are filled in — so “LONDON 12/04/2026” never shows a stray space when the date is empty.
e.g. { "type": "separator", "value": " ", "showIf": ["location", "date"] }
fontSize · lineHeight
Text size
Font size is in centimetres — the printed capital-letter height. Line height is a multiplier of the font size (1 = single spacing).
e.g. "fontSize": 1.6, "lineHeight": 1
alignmentOptions
Alignment anchors
The alignments shoppers can toggle between — each an anchor point: a type (left, center or right) plus the x · y position (cm) the text aligns to. defaultAlignment picks the starting one.
e.g. { "type": "left", "x": 2.4195, "y": 0.95 }
strokeAvailable
Outline toggle
Lets shoppers add an outline (stroke) around the text — useful for keeping text readable on photos.
defaultTextColour · defaultStrokeColour
Starting coloursOptional
Optional fixed defaults. Usually left out — colours then come from the colour mappings for the shopper’s chosen product colour.
printOutputData
Print fine-tuningAdvanced
Calibration for the printed file: outline thickness (strokeWidth), vertical anchor (baseline: top / middle / bottom) and tiny xOffset / yOffset corrections (some scale with the font size via fontSizeMultiplier). Set once per product during setup — fine to leave alone.
07

Obstructions — things that sit on top

Obstructions are placeholders for real objects that will cover part of the design — a medal and its ribbon on a frame. They appear on the canvas so shoppers design around them, and they come with their own controls: shape choices and sliders.
obstructions · real objects sitting over the design
Ribbon fixed
One set shape (a single SVG asset). Its width is adjusted with a slider.
Medal shape
The shopper chooses between shapes (Circle, Square, …) and sizes it with a slider.
Shoppers position their photos and text around the placeholders, so the finished print works with the real medal and ribbon in place.
label
Group heading
The title above the obstruction controls in the customiser.
e.g. "Medal Placeholder"
medal · ribbon
Obstruction groups
One group per object. Each group has its own label, an asset provider and its adjusters (below).
order
Two orders
input is the order shoppers fill in the controls; editor is the stacking order on the canvas preview. They can differ — the ribbon may be input #2 but drawn first, underneath the medal.
assetProvider
What is drawn
"shape" offers multiple options — each with a name, a picker icon (uiIcon) and the SVG drawn on the canvas (canvasAsset). "fixed" is a single set SVG with no choice. baseStyle anchors it: top / left as a percentage of the canvas, width / height in centimetres.
e.g. { "type": "shape", "options": [Circle, Square] }
adjusters
Sliders
Each adjuster is one slider — see the anatomy below. Its target names what it changes (width, height, or both at once for a proportional resize).
canvasDisplayFormula
Display formulaAdvanced
Optional maths converting a slider value into the drawn size on screen. Rarely needed.
adjusters · a slider the shopper drags
Ribbon Width2.5 cm
min: 2step: 0.5max: 4
label — the title
target — what it resizes
metadata — min · max · step · default · unit
From the demo frame: the medal offers Circle and Square shapes with a size slider of 5–9 cm (step 1); the ribbon is a fixed shape with a width slider of 2–4 cm (step 0.5, default 2). When the shopper has already purchased a ribbon width, Builder logic caps this slider to match.
08

Composite zones — several areas, one step

A composite zone is made of one or more image and text sections, all rendered inside a single canvas and edited as a single step — for products where the photo and the caption belong to one printed piece.
a composite zone · several sections, one canvas, one step
composite zone · originalSizeimage sectioncanvasOffset x·ytext section
Each section keeps its own size, masks and layouts; the section’s canvasOffset places it inside the parent canvas. The zone’s own offset moves the whole group at once.
sections
The section list
Each section is a self-contained image or text region — the same settings as an image zone or text zone (masks, layouts, obstructions on image sections), plus an id and its own canvasOffset placing it inside the parent canvas.
originalSize
The shared canvas (cm)
The composite’s overall print size. Sections position themselves within it; the zone’s own canvasOffset shifts the whole group at once.
backgroundColour
One background
The composite owns the background — sections don’t have their own.
09

Model Colour zones — recolour the 3D model

A Model Colour zone adds a step where shoppers pick colours directly on the spinning 3D model — tap a part, choose a swatch.
type · title
That’s all it holds
Just "modelColour" and the step’s heading. Everything else — which parts are selectable, their swatches and camera views — is configured in the Selector 3D scene’s colour areas, which this zone requires to be enabled.
10

Mappings — the dictionaries

Your store sells “Cream”, “Black”, “White” — the customiser needs exact colours and the right steps for each. Mappings are the lookup tables that translate those simple names, keyed by the shopper’s choices on the product page.

Background colours — colours

Colour name → the zone background it paints. The name matches your product’s colour option, lowercased.

"cream"#fff5ec
"black"#000000
"white"#ffffff

Text colours — textColours

The default text colour used on each background — dark text on cream, white text on black, so engravings stay readable.

"cream"#000000
"black"#ffffff

Stroke colours — strokeColours

The default text-outline colour per background, written as a hex with opacity (#FFFFFF00 = fully transparent). Tip from the dashboard: 0% opacity — no outline — is the common case.

Zone order — zoneOrderByType

The switchboard of the whole configuration: each customisation type your product offers maps to the zones it shows, in step order. The type comes from the product’s “Customisation” option (or the hosted page’s switcher); matching is forgiving — case-insensitive, partial.

zoneOrderByType · which steps each customisation type shows
"text on frame"1 textArea
"custom pictures"1 background
"text and pictures"1 background2 textArea
"custom"1 modelColour2 background3 textArea
The demo frame’s four customisation types. The shopper’s choice on the store page selects a row; the row decides the steps and their order.

3D themes — threeDThemes

Colour name → the list of colours applied to the 3D model’s themed parts, so the model matches the chosen product colour. The order matters: the first colour paints the model’s part number 0, the second part number 1, and so on.

11

3D scenes — the spinning previews

One 3D model of your product (modelStoragePath — a .glb file uploaded in the dashboard) is shared by up to three scenes, each shown at a different moment of the journey.
threeDScenes · one model, three moments
On the product page
Teaserteaser
A preview scene shown before customisation begins — a spinning first look.
During customisation
Selectorselector
The 3D colour selector for recolouring parts of the product. Powers Model Colour zones.
On the final step
Confirmationconfirmation
The main 3D preview shown on the review-and-confirm step, with the design applied.

Settings every scene shares

enabled
On / off
Whether the scene is shown at all.
backgroundMode · gradientConfig
Backdrop
solid for a flat colour or radialGradient for a soft glow — with a centre colour, an edge colour and the gradient’s shape (ellipse/circle), position and size.
e.g. { "centerColor": "#ffcfbb", "edgeColor": "#ffffff" }
rotation
Rotation limits
How far the model turns when shoppers drag it. Per axis: continuous spins freely; oscillate rocks back and forth within range degrees.
e.g. { "x": { "mode": "oscillate", "range": 90 } }
materialConfig
Surface look
roughness (0 shiny → 1 matte), metalness (0–1) and envMapIntensity (0–2) — how strongly the environment reflects off the product.
productScale
Size in frame
1 = no scaling; raise or lower to fill the frame.
camera
Camera overrideOptional
A viewing position (x, y, z) and field of view (fov, in degrees). Leave it out to use the camera baked into the .glb file.
controllers
Shopper controls
Buttons overlaid on the preview: placeholder (a show/hide toggle for a mock visual — e.g. a medal for scale — with its label and starting defaultValue) and, on teaser/confirmation, color (a quick colour picker with its own options list).
reuseSelectorSettings
Inherit from SelectorOptional
On teaser/confirmation: reuse the Selector scene’s backdrop, rotation and surface settings instead of repeating them.

Selector-only settings

colourAreas
Colour areas
The selectable parts of the model. Each has an id matching a group marked inside the 3D file, a shopper label, a defaultColour, its colourSwatches palette, an optional cameraView the camera flies to when tapped, and an optional texture naming a zone key — picking a colour then also recolours that zone’s background.
e.g. { "id": "frame", "label": "Frame Colour", "colourSwatches": ["#333333", …] }
ping
Ping hints
Animated pulsing indicators showing which parts of the model are tappable, in your chosen color.
positionReset
Reset view button
A button (or toggle) returning the camera to its default position and target after the shopper has dragged around.
defaultCameraView
Starting viewOptional
Camera position and target when no colour area is selected; leave empty to use the .glb camera.
Preparing the model: which meshes take artwork, which are recolourable and where cameras point is written into the .glb file itself as custom properties. The dashboard’s “How to prepare your model” guide (on the 3D Scenes tab) covers it step by step.
12

Builder logic — adapting to the shopper’s choices

One product page, many variants: black or cream, 2 cm or 4 cm ribbon, text-only or full custom. Builder logic (builderSpec) is the set of rules that reads those choices and tailors the configuration before the customiser opens — no code required.
builderSpec · from the shopper’s choices to a ready customiser
Shopper picks on the store page
Colour: BlackRibbon width: 3 cmType: Text & pictures
Builder logic applies the rules
  • reads each choice as a named input
  • picks the mask whose condition is “3”
  • caps the ribbon slider at 3 cm
  • looks up “black” in the colour mappings
  • writes the product title from a template
The customiser opens
black background, white text
3 cm ribbon cut-out mask
titled “Black / 12cm Frame / 3cm Ribbon Width”
inputs
Named inputs
The choices to read, each with a path to the value (e.g. metaData.ribbonWidth for a “Ribbon Width” product option), a type (string, number, boolean, raw) and a default used when the variant doesn’t supply one. Every other rule refers to inputs by name.
e.g. "ribbonWidth": { "path": "metaData.ribbonWidth", "type": "number", "default": 2 }
description
Product title template
The title shown to the shopper, with {placeholders} swapped for live values.
e.g. "{colourLabel} / {frameSize}cm Frame / {ribbonWidth}cm Ribbon Width"
consts · computed
Extra title valuesAdvanced
consts are fixed values usable in the template (like frameSize: 12); computed derives a label by matching an input against cases — e.g. show “Custom Colour” instead of the raw colour when the type is custom.
zones.<key>.mask
Pick the mask
by names an input; the zone shows the background mask whose condition matches that input’s value (ribbon width 3 → the “3” mask).
e.g. { "by": "ribbonWidth" }
zones.<key>.obstruction.clamp
Cap a slider
Pins an obstruction group’s slider maximum and default to a numeric input — the ribbon slider can’t exceed the width the shopper actually purchased.
e.g. { "group": "ribbon", "widthFrom": "ribbonWidth" }
zoneEmitOrder
Zone output orderAdvanced
The definitive order zones are produced in, as a list of zone keys.
colours · zoneOrder · threeD
Convention overridesAdvanced
Normally automatic: the engine looks up backgrounds, text and stroke colours by the chosen colour, the step list by the customisation type, and 3D themes — all from Mappings. These keys only exist to rewire that convention, via the JSON tab.
Good to know: on Shopify, the widget reads the variant’s options for you — “Colour” sets the colour input, “Customisation” sets the type, and every other option (like “Ribbon Width”) arrives as metaData for inputs to pick up. Kastomise-hosted shops feed the same inputs from the hosted page’s option fields.
13

Hosted page — your product page, hosted by Kastomise

For shops on the Kastomise-hosted integration, this section designs the product page itself: title, price, photo gallery and the option fields shoppers set before opening the customiser. Shops embedding the widget in their own store don’t use it.
title · basePrice
Product details
The page’s product name and its starting price.
e.g. "Marathon frame" · 30
images
Gallery
The photo gallery, shown in list order — drag to reorder in the dashboard.
fields
Option fields
The options rendered on the page, in order — six types shown below. Each has a label, optional helperText under it, and (for choice types) its options: a label, an auto-generated key, an optional price surcharge added to the base price, a color for swatches and a description for radio cards.
fields[].builderPath
Builder connectionOptional
Connects a field to the customiser: the selected value is handed to Builder logic — e.g. a “Frame colour” swatch driving backgroundColor (its labels must match colour mapping names, like “Black”).
extras
Extras
Toggleable add-ons, each with a required price added to the total when switched on — gift wrap, hanging kit. The group name is always "extra".
e.g. { "key": "giftWrap", "label": "Gift wrap", "price": 8 }
customisation
Customisation switcher
Lets shoppers choose which experience they’re buying. Each option’s key matches a Zone Order type and its label is what shoppers see; defaultKey applies when the page URL doesn’t preset one (?customisationType=…), and showOnPage shows the switcher on the page (it needs two or more options to appear).
hostedPage.fields · the six field types
Colour swatches"swatch"
each option carries a hex colour
Segmented buttons"segmented"
SML
a joined button bar
Radio cards"radio-cards"
Standard
Ready in 5 days
Express
options may carry a description line
Dropdown"dropdown"
30 cm
a compact select list
Slider (range)"range"
25 mm
min · max · step · defaultValue · unit
Text input"text"
Add a caption…
maxLength · placeholder
14

Cheat sheet

The whole document at a glance — every top-level key, where you edit it in the dashboard, and when you need it.
description
Config descriptionRequired
Private note identifying this configuration. Edited on the sidebar’s Description card.
zones
ZonesRequired
The customisable areas / steps. Edited per zone in the sidebar: Basic settings, Background masks, Layout options, Obstructions, Sections.
mappings
MappingsRequired
Colour dictionaries + zone order. Edited on the Mappings tab (Background, Text, Stroke, Zone Order, 3D Themes).
threeDScenes
3D scenesOptional
The shared model and the Teaser / Selector / Confirmation scenes. Edited on the 3D Scenes tab; availability depends on your plan.
builderSpec
Builder logicOptional
Rules mapping shopper selections onto the config. Edited on the Builder Logic tab (shown for Shopify-connected shops).
hostedPage
Hosted pageOptional
The hosted product page. Edited on the Kastomise Hosted tab (shown for hosted shops).
Stuck on a setting? Most configurations start from a template we prepare during onboarding — you’ll mainly touch labels, colours, validation messages and prices. For anything positional (alignments, print fine-tuning) or a brand-new product, email hello@kastomise.com and we’ll set it up with you.