# imagine.io Configurator Platform — full documentation
> Everything on https://configurator-platform.imagine.io in one file: the product overview, the complete SDK documentation and the admin guide, as Markdown. Generated 2026-11-17 from the published pages. The short index is https://configurator-platform.imagine.io/llms.txt.
How to use this file: each page is a level-1 heading with its Source URL; the page's own sections follow as level-2/3/4 headings, and every section that has an anchor on the site carries a "Permalink" line you can cite. Code is fenced; tables are Markdown tables; images are reduced to their alt text.
## Quick facts
- imagine.io Configurator Platform is a 3D product configurator platform for any product with options — sofas, chairs, beds and mattresses, kitchens and cabinetry, doors, mirrors, frames, lighting. Rules, constraints, pricing and quotes run on the server; the browser only renders.
- Three ways to go live, all on the same catalog: a no-code share link, an iframe embed on any website, or the SDK for React 18 and 19 (npm: `@imagineio/configurator-sdk`, one `mount()` call).
- Installing the SDK (version 0.1.6 and later): on React 19, `npm install @imagineio/configurator-sdk`. On React 18, name the React 18 versions in the same command: `npm install @imagineio/configurator-sdk react@^18.2 react-dom@^18.2 three@~0.159.0 @react-three/fiber@^8.15 @react-three/drei@^9.88 @react-three/postprocessing@^2.16 postprocessing@~6.36.0`, then `npm install -D @types/react@^18.2 @types/react-dom@^18.2`.
- Free to build: unlimited configurators, products, variants and materials, the full rules and pricing engine, the dashboard and API keys. A paid plan is needed to go live on a commercial site; plans and prices are in the dashboard at https://admin-configurator.imagine.io/.
- Authentication: a server-side API key (header `X-Api-Key`, prefix `ck_`, read-only `ck_ro_`) is exchanged for a 30-minute browser session token (`Authorization: Bearer`), optionally bound to one system and one origin.
- Every change is evaluated by the engine: HTTP 200 = applied (returns `resolvedState`, `pricing`, `warnings`), 409 = catalog changed (SDK refetches and replays), 422 = rejected by a constraint (previous state kept, `errors[]` carries the reason).
- Sample project: https://github.com/Live-Furnish/imagine-configurator-sdk-boilerplate (sofa and kitchen sample catalogs). Live demo: https://configurator-platform.imagine.io/demo/index.html.
## Contents
- **Overview** — https://configurator-platform.imagine.io/
- Share a link today. Embed it on your site. Build it in when you are ready.
- Sell configurable products without the enterprise complexity.
- One call on your side. Everything else is the engine’s job.
- Everything a configurator needs, already modelled.
- Your key stays on your server. The browser gets a short-lived token.
- Build the whole thing before you pay for anything.
- Frequently asked questions
- Your catalog can be live this week.
- **SDK documentation** — https://configurator-platform.imagine.io/sdk/index.html
- Quickstart
- Customise the UI
- Embed a public link
- The e-commerce bridge
- Events & rules
- Rule & constraint evaluation
- Guides
- Customize Theme & Layout
- Override Button Functionality
- Add a Custom Button
- Add Custom 3D Functionality
- Customize or Create Quote Templates
- Integrate with E-Commerce Platforms
- Add Custom Popups
- Integrate Custom APIs
- Work with Custom Rules and Constraints
- Work with Placement Logic
- Customize the Loading Screen
- Adding Custom Dimension Code
- API reference
- Troubleshooting
- **Admin guide** — https://configurator-platform.imagine.io/admin-guide/index.html
- Your organization, your team, and where to find help.
- A count of everything in the catalog.
- Ask it where things are. Or ask it to do them.
- Set up a configurator: each step uses the one before it.
- Everything you can pick, and what to write when the dropdowns run out.
- One configurator, sold through many storefronts.
- Saved projects, quotes and generated images.
- Branding is your organization. A theme is the configurator.
- Import a catalog instead of entering it screen by screen.
- Free to build and evaluate. Upgrade to sell.
- Six things that catch people out.
- Hand it to a developer.
- **Launch post** — https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html
- Bring your product catalog into 3D
- A constraints engine, not just rules
- Start without code. Customize with code.
- One catalog, multiple sales channels
- Connect the configuration to pricing, quotes and commerce
- Take the configured product beyond the browser
- AI in the dashboard and in the configurator
- Build and evaluate for free
- Frequently asked questions
- **SDK quickstart** — https://configurator-platform.imagine.io/sdk/quickstart/index.html
- Nine steps
- What next
- Frequently asked questions
- **Guides** — https://configurator-platform.imagine.io/docs/guides/index.html
- Three routes, one engine
- Related
- **Guide** — https://configurator-platform.imagine.io/docs/guides/shopify/index.html
- The embed code
- Step by step
- Hand the configuration to your cart
- Frequently asked questions
- Troubleshooting
- Other platforms
- Related
- **Guide** — https://configurator-platform.imagine.io/docs/guides/wordpress/index.html
- The embed code
- Step by step
- Hand the configuration to your cart
- Frequently asked questions
- Troubleshooting
- Other platforms
- Related
- **Guide** — https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html
- The embed code
- Step by step
- Hand the configuration to your cart
- Frequently asked questions
- Troubleshooting
- Other platforms
- Related
- **Guide** — https://configurator-platform.imagine.io/docs/guides/webflow/index.html
- The embed code
- Step by step
- Hand the configuration to your cart
- Frequently asked questions
- Troubleshooting
- Other platforms
- Related
- **Guide** — https://configurator-platform.imagine.io/docs/guides/react/index.html
- The whole integration
- Step by step
- Hand the configuration to your cart
- Other platforms
- Frequently asked questions
- Troubleshooting
- Related
- **Sample catalogs** — https://configurator-platform.imagine.io/docs/sample-catalogs/index.html
- The two bundles
- Import it in five steps
- What lands in your catalog
- Licence
- Frequently asked questions
- Related
- **Documentation** — https://configurator-platform.imagine.io/docs/index.html
- Start here
- Add it to your site one page per platform
- Understand the engine
- Resources
- **Concept** — https://configurator-platform.imagine.io/docs/concepts/server-side-constraint-and-rule-evaluation/index.html
- The request
- Four steps, in order
- Three answers
- Why on the server
- Reading it in code
- Related
- Frequently asked questions
- **Concept** — https://configurator-platform.imagine.io/docs/concepts/rules-vs-constraints/index.html
- A constraints engine, not just rules
- Side by side
- What a rule looks like
- What a constraint looks like
- Which one to write
- Related
- Frequently asked questions
- **Concept** — https://configurator-platform.imagine.io/docs/concepts/per-channel-pricing/index.html
- What a channel holds
- How the configurator picks the channel
- What the engine does with it
- Related
- Frequently asked questions
- **Concept** — https://configurator-platform.imagine.io/docs/concepts/session-tokens/index.html
- The API key
- The token route
- The page
- The flow
- Related
- Frequently asked questions
- Troubleshooting
- **Engine response** — https://configurator-platform.imagine.io/docs/errors/409-catalog-changed/index.html
- Why it happens
- What to do
- The response
- Related
- Frequently asked questions
- **Engine response** — https://configurator-platform.imagine.io/docs/errors/422-rejected-by-constraint/index.html
- Why it happens
- What to do
- The response
- Related
- Frequently asked questions
- **Free 3D product configurator** — https://configurator-platform.imagine.io/free-3d-product-configurator/index.html
- What the free plan includes
- What needs a paid plan
- How to start in fifteen minutes
- Frequently asked questions
- Related
- **A 3D configurator with live pricing and quotes** — https://configurator-platform.imagine.io/configurator-with-live-pricing-and-quotes/index.html
- How prices are set
- Per-channel pricing
- Quotes and the bill of materials
- How the price reaches your cart
- Frequently asked questions
- Related
---
# Overview — what the platform is, how to go live, pricing, FAQ
Source: https://configurator-platform.imagine.io/
## Make your catalog configurable in 3D
Your products, materials, rules, constraints and prices live in one dashboard. Publish a link and customers are configuring and pricing the same day, with a constraints engine checking every change on the server so only valid configurations ever reach the cart. Embed it on your site, or mount it with the SDK when you want full control. Free to build. Products, rules, constraints and prices in one dashboard. A constraints engine keeps every build valid. Publish a link, embed it, or use the SDK. Free to build.
[See the engine at work →](https://configurator-platform.imagine.io/demo/index.html)
[Read the SDK docs →](https://configurator-platform.imagine.io/sdk/index.html)
[Book a walkthrough →](https://configurator-platform.imagine.io/#book-a-walkthrough)
[GitHub](https://github.com/Live-Furnish/imagine-configurator-sdk-boilerplate)
[npm](https://www.npmjs.com/package/@imagineio/configurator-sdk)
[For brands: no-code guide →](https://configurator-platform.imagine.io/admin-guide/index.html)
[Launch post: introducing the platform →](https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html)
[Image: The sofa sectional configurator: a 3D sofa beside its option sidebar]
Three ways to go live
### Share a link today. Embed it on your site. Build it in when you are ready.
Permalink: https://configurator-platform.imagine.io/#paths
All three run the same configurator against the same catalog, so nothing is rebuilt when you move from one to the next.
#### Share a link No code
For brands, no code
- Build the catalog, rules, constraints and prices in the dashboard, then create a shareable link for the system.
- Send it to customers, put it behind a button, add it to quotes. Switch it off any time.
[Read the admin guide](https://configurator-platform.imagine.io/admin-guide/index.html)
#### Embed it on your website iframe
For any website
- Paste one tag into any page. The same link runs inside your site, in your branding.
- Add your website to the link's allowed domains in the dashboard, and it is live.
- Works on any platform that lets you add HTML, with nothing to install.
```
```
Step by step for [Shopify](https://configurator-platform.imagine.io/docs/guides/shopify/index.html), [WordPress](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html), [WooCommerce](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html) and [Webflow](https://configurator-platform.imagine.io/docs/guides/webflow/index.html).
#### Build it into your own code SDK
For developers
- Install the SDK and mount the same configurator into any page with one call.
- Restyle or replace any part of the interface. Add your own buttons, 3D and checkout.
- Listen to every event and save projects, quotes and renders into your own systems.
Running in fifteen minutes: the [SDK quickstart](https://configurator-platform.imagine.io/sdk/quickstart/index.html), or the [React guide](https://configurator-platform.imagine.io/docs/guides/react/index.html).
[Read the SDK docs](https://configurator-platform.imagine.io/sdk/index.html)
For brands
### Sell configurable products without the enterprise complexity.
Permalink: https://configurator-platform.imagine.io/#brands
Furniture, kitchens, modular storage, manufacturing: if it comes in options, it can be configured, priced and quoted here, and you do not need a developer to start. No 3D models yet? imagine.io builds them from your photos and drawings and sets up the catalog with you, the same service our visualisation customers already use.
Your shoppers
#### See it, price it, keep it
Configure in 3D, see a live itemised price, save projects, and view the exact piece in AR on their phone.
Your sales team
#### Quotes that match the build
Branded quote PDFs, dealer and marketplace channels with their own prices. No more mis-quoted orders.
Your team
#### One dashboard, every channel
Products, materials, rules and prices in one place. Publish a new catalog version and every channel updates.
**Typical setup:** catalog in the dashboard this week, link live the same day. Want us to build the models and the catalog?
[Start now →](https://admin-configurator.imagine.io/)
[Book a walkthrough](https://configurator-platform.imagine.io/#book-a-walkthrough)
For developers
### One call on your side. Everything else is the engine’s job.
Permalink: https://configurator-platform.imagine.io/#developers
None of this is code you write. `mount()` loads the system, sends each shopper action to the engine and draws what comes back. Constraints, rules and pricing all run on the server, inside the constraints engine, so only valid configurations are ever built, and a shared link, an embed and an SDK page give the same result for the same clicks.
Step by step: the [fifteen-minute quickstart](https://configurator-platform.imagine.io/sdk/quickstart/index.html), or the [platform guides](https://configurator-platform.imagine.io/docs/guides/index.html) for Shopify, WordPress, Webflow and React. [Full documentation](https://configurator-platform.imagine.io/docs/index.html).
The whole integration
```
# npm install @imagineio/configurator-sdk
import { mount } from "@imagineio/configurator-sdk";
// Your server swaps the API key for a 30-minute session token.
// The SDK calls this route again before expiry, and once on a 401.
const app = mount("#root", {
systemId: 90,
getToken: async () => (await fetch("/configurator-token", { method: "POST" })).json(),
});
// That is the whole integration. Later: app.unmount();
```
1 · Check
#### Is the catalog current?
Every action carries the catalog version the page booted with. If your team published a new version mid-session, the engine answers 409 before touching anything, and the SDK refetches and retries.
2 · Apply
#### The action lands
Pick an option, add or remove a module, swap a variant, load a preset. Unpicked selections are filled from their defaults, so rules always see a complete state.
3 · Rules
#### Matching rules fire, in priority order
Swap every leg in a run, hide a component, narrow an option set, load a material. Effects are written as overrides on top of the base configuration. The catalog itself never changes.
4 · Constraints
#### The constraints engine re-checks the result
Max counts, adjacency, mutual exclusion, compatibility, custom limits. Anything the result breaks is refused with a reason the shopper can read.
5 · Resolve
#### One response, fully resolved
Visibility, materials, component swaps, effective selections and which options remain available are baked in. The SDK diffs it against the last frame and updates the scene.
#### What comes back 200
The shopper's click sent one action. The pick lands in `selections`; everything the engine did in response (swapped components, hidden parts, re-skinned materials) lands in `overrides`. The catalog never changes, so you can always separate what was chosen from what the engine derived.
```
{
"catalogVersion": 14,
"resolvedState": {
"selections": { "60": 645 }, // leg style: Beinramme (what was chosen)
"placements": [{
"id": "p-1", "variantId": 375, // 1-seater, as placed
"overrides": { "componentSlots": { "sofa_leg": 1272 } }, // what the engine did
…
}]
},
"pricing": { "grandTotal": …, "currency": … },
"warnings": []
}
```
#### What you can rely on
- **Nothing is decided in the browser.** Rules, constraints and prices run on the server, so a custom interface cannot drift from the catalog.
- **Rules can chain, you still get one response.** An effect can trigger another rule. The engine keeps going inside the same request until nothing else matches. A cycle is rejected with a 422 that names the rules involved.
- **Changes are deltas.** Effects are overrides layered on the placed variant, never edits to the catalog, so undo, presets and share links stay exact.
- **Pricing is itemised.** Each option carries its own price change and a sales channel can override base prices. The live breakdown is the same one the quote PDF prints.
- **Your team can extend the logic without you.** Custom rules and constraints are authored in the dashboard as plain JSON with bounded evaluation. They run through the same pipeline and reach you as the same response.
200
**Applied.** The state updates. Any warnings ride along and the shopper can carry on.
409
**Catalog changed.** Your team published a new version while a shopper was mid-session. The SDK picks up the new version and replays the action; the shopper never notices.
422
**Refused by the constraints engine.** The previous state stays and the shopper sees the reason, which you can restyle or replace.
The platform
### Everything a configurator needs, already modelled.
Permalink: https://configurator-platform.imagine.io/#build
Bring your own 3D models, or have imagine.io build them: our team turns product photos and drawings into configurator-ready 3D assets and sets up your catalog for you. Other configurators have a rules engine. Ours is a constraints engine: every change is checked on the server against the limits you set, so only valid configurations are ever built. Rules still shape the result, hide, swap, load, price, but they can never produce something that breaks a constraint.
#### Catalog and components
Components, anchor points, groups, materials and variants, scoped to your organization or to one system.
#### 3D models and catalog setup, done for you
No models yet? imagine.io's 3D team builds configurator-ready models from your photos and drawings, and sets up products, options, rules and prices with you.
#### A constraints engine, not just rules
Always-enforced limits plus trigger-and-action rules, authored in the panel. Every change is checked on the server, so an invalid build is refused with the reason.
#### Live pricing
Prices live on the options that load each variant, so a quote follows the resolved state. Per-channel overrides for dealers.
#### Saved projects and quotes
Persist a shopper’s build behind a share token, attach renders, and hand back a branded quote PDF from your templates.
#### Sales channels and your storefront
One configurator, many storefronts. Each channel carries its own prices, defaults and theme; a message bridge lets your page drive it.
#### AI imagery of the exact configuration
Silo and lifestyle images of the piece the shopper built, rendered on demand. Metered per plan, stored with your other assets.
#### AR on the shopper's phone
An AR link and QR code for the current build. The shopper scans it and sees the exact piece, full size, in their own room.
#### An AI assistant inside the configurator
A shopper asks in plain words, “show me the three-seat layout in black”, and it answers or makes the change.
#### An AI-native dashboard
The dashboard has its own assistant: ask it to create materials, products, option sets, rules and constraints from a description or a file, fix an import, or explain a setting. [What the assistant does](https://configurator-platform.imagine.io/admin-guide/index.html#assistant).
#### Themes, layouts and your own components
Theme tokens, plain CSS, component overrides, slots and whole layouts. Every surface has a working default; change only what you want.
For developers · Authentication
### Your key stays on your server. The browser gets a short-lived token.
Permalink: https://configurator-platform.imagine.io/#auth
Every request is scoped to your organization by the credential that made it. There is one long-lived secret, and it never ships to a page.
#### Server API key
- Created in the dashboard under Settings, then API Keys. Prefix `ck_`.
- Sent as `X-Api-Key`. Read-write by default.
- Fine for quick starts and server-to-server calls. Never embed it in a page.
```
POST /api/v1/auth/token/
X-Api-Key: ck_…
{ "scope": "session", "system_id": 90,
"origin": "https://your-site.com" }
```
#### Browser Session token
- Minted by your server from the key. Lives 30 minutes. Sent as `Authorization: Bearer`.
- `session` scope can save projects and upload renders. `catalog` scope is read and price only, for public embeds.
- Optionally bound to one system and one origin, so a token lifted from your page is useless elsewhere.
```
201 {
"access_token": "eyJ…",
"token_type": "Bearer",
"expires_in": 1800,
"scope": "session"
}
```
Getting started is free
### Build the whole thing before you pay for anything.
Permalink: https://configurator-platform.imagine.io/#plans
Every organization starts on the free plan with no card and no sales call. Unlimited configurators, products, variants and materials, the full constraints, rules and pricing engine, the dashboard, API keys and your whole team.
Free includes
- Everything needed to build and test a configurator end to end
- Rules, constraints, live pricing, presets and themes
- API keys, session tokens and an AI image allowance
Going live adds
- A commercial licence and no watermark
- Running on your own domain and storefront
- Sales channels, saved projects with quotes, higher limits
Plans and current pricing are in the dashboard, where you can upgrade whenever you are ready. [What the free plan includes](https://configurator-platform.imagine.io/free-3d-product-configurator/index.html), in detail.
[See plans and pricing](https://admin-configurator.imagine.io/settings/billing)
FAQ
### Frequently asked questions
Permalink: https://configurator-platform.imagine.io/#faq
Everything you need to know before you build your first configurator: plans, platforms, the engine and the SDK.
**What is a 3D product configurator?**
An interactive 3D tool, on a website or in an app, where a customer picks options (size, modules, fabric, finishes) and sees the exact product in 3D with a live price. On imagine.io the rules, constraints and pricing run on the server, so the picture and the price are always the ones the catalog allows.
**What kinds of products can I configure?**
Anything built from options: sofas and sectionals, chairs, beds and mattresses, kitchens and cabinetry with their appliances, doors, mirrors, frames, lighting: any product line with variants, materials and rules. One organization can hold several configurable systems, each with its own catalog, constraints, rules and prices; the sample data ships a sectional sofa and a kitchen.
**Is there a free plan?**
Yes. Every organization starts on the free plan with no card and no sales call: unlimited configurators, products, variants and materials, the full constraints, rules and pricing engine, the dashboard, API keys and your whole team. Going live adds a commercial licence, no watermark, sales channels, saved projects with quotes and higher limits. Plans and current pricing are in the dashboard.
**What are the different ways to share the configurator?**
Three, and all of them run the same catalog. Share a link: publish the system and send the link, put it behind a button on your site, or add it to a quote. Embed it: paste one iframe tag into your own website, in your branding, on any platform that lets you add HTML. Build it in: install the SDK and mount the configurator inside your own code, then deploy it as part of your site. Nothing is rebuilt when you move from one to the next, and a link can be switched off at any time.
**Do I need a developer to launch a configurator?**
No. Build the catalog, rules, constraints and prices in the dashboard, then create a shareable link, or paste one iframe tag into any page that lets you add HTML. The SDK is for teams that want to restyle or replace parts of the interface, or add their own buttons, 3D or checkout.
**Does it work with my website platform?**
Yes. Shopify, WordPress, Webflow, Squarespace, Wix and any custom site can run it, because the configurator is embedded with one iframe tag and every platform lets you add an HTML tag. Add your website to the link's allowed domains in the dashboard, paste the tag, and it is live in your branding with nothing to install. If your site is built in React, you can use the npm SDK instead for a deeper integration.
**Where do the rules, constraints and pricing run?**
On the server. Every change a shopper makes is sent to the engine, which applies matching rules in priority order, re-checks every constraint, prices the result and returns one fully resolved state. Nothing is decided in the browser, so a custom interface cannot drift from the catalog.
**What is a constraints engine, and how is it different from a rules engine?**
The difference is whether an invalid configuration can get through. A rules engine reacts: when the shopper picks this, do that. It only covers the cases someone wrote a rule for, so a combination nobody foresaw can still reach the cart. A constraints engine holds the limits that must always be true, like at most 50 bars per power supply, and re-checks every one of them after every change, so an invalid configuration is refused with the reason. Other configurators have a rules engine. The imagine.io engine is a constraints engine: every change is checked on the server against the limits you set, so only valid configurations are ever built. Rules still shape the result, hide, swap, load, price, but they can never produce something that breaks a constraint. On this platform both are set from dropdowns in the dashboard and evaluated on the server on every click.
**What happens if I change the catalog while someone is configuring?**
Every action carries the catalog version the page loaded with. If you publish a new version mid-session, the engine answers 409 before touching anything, the SDK picks up the new version and replays the action, and the shopper never notices.
**Is my API key exposed in the browser?**
It must not be, and that is in your hands: keep the API key on your server and never ship it to a page. Your server exchanges it for a session token that lives 30 minutes and is sent as a Bearer header; a token can be bound to one system and one origin, so one lifted from your page is useless elsewhere.
**What do I install for the SDK?**
One package: npm install @imagineio/configurator-sdk, with React 18 or React 19 (on React 18 the command is longer; the SDK docs give it). Call mount() once and the configurator runs; the 3D stack is installed for you as peer packages. The sample project on GitHub is the same thing already wired up.
**Can customers save and share what they configured?**
Yes. A saved project gets a share link and a quote PDF, and an AR link opens the exact configuration at full size on a phone. Through the SDK, projects, quotes and renders can also be written into your own systems.
**Can a configuration become a quote?**
Yes. A saved project gets a share link and a quote PDF with the itemised price. Through the SDK you can customise the quote template or supply your own.
**I do not have 3D models. Can imagine.io make them?**
Yes. imagine.io's 3D production team builds configurator-ready models from your product photos, drawings or CAD files, and can set up the catalog, options, rules and prices with you. It is the same service our product visualisation customers use. [Book a walkthrough](https://configurator-platform.imagine.io/#book-a-walkthrough) and we will scope your product line.
**Can customers view it in AR?**
Yes. Generate an AR link for the current configuration and put its QR code on the page or the quote. The shopper scans it with a phone and sees the exact piece they built, at full size, in their own room.
**What is a sales channel?**
One route you sell through: your own website, a dealer's site, a marketplace you list on such as Wayfair or Amazon, or an internal tool for your sales team. Each channel gets its own link or embed and can carry its own prices, option overrides and presets, so one catalog is sold differently per channel.
**Can prices differ by channel or dealer?**
Yes. Sales channels carry their own pricing and overrides, so a dealer, a marketplace and your own storefront can run the same configurator at different prices and with different options.
Get started
### Your catalog can be live this week.
Permalink: https://configurator-platform.imagine.io/#contact
Create an organization, build the catalog in the dashboard and publish a link. Share it or embed it on your site the same day. When you want full control, an API key and the SDK docs are one click away. Prefer to talk first, or want us to build the 3D models and the catalog for you? [Book a walkthrough](https://configurator-platform.imagine.io/#book-a-walkthrough) and we will go through your product line together.
[Open the dashboard](https://admin-configurator.imagine.io/)
[Book a walkthrough](https://configurator-platform.imagine.io/#book-a-walkthrough)
[Read the SDK docs](https://configurator-platform.imagine.io/sdk/index.html)
Contact: [configurator@imagine.io](mailto:configurator@imagine.io)
**Fair usage New platform offer for the first 50 self-serve accounts**
Storage 500 GB
Bandwidth 4 TB
API calls 4 million
Plans are not metered by catalog size: configurators, products, variants and materials stay unlimited on every plan. These are the fair-usage limits for the founding offer, and they are generous by design: a catalog of several thousand products with high-resolution textures and 3D models sits comfortably inside them. Heading past one? [Talk to us](mailto:configurator@imagine.io) and we will work out a plan that fits.
---
# SDK documentation — install, customise, embed, events, evaluation, guides, API reference
Source: https://configurator-platform.imagine.io/sdk/index.html
Developer documentation
## Add a 3D product configurator to your site.
The imagine.io Configurator SDK is the complete configurator your customers use: a live 3D scene, options with live pricing, save and share, AR on the phone, AI-generated product images and an assistant. Your products, rules and prices are set up once in the imagine.io admin panel; the SDK renders them. Install the package, call **`mount()` once**, and it runs. Then change anything about how it looks and behaves — theme, layout, individual components, or drive it from your own page — without waiting for an SDK release.
`npm install @imagineio/configurator-sdk`
Package: [@imagineio/configurator-sdk on npm](https://www.npmjs.com/package/@imagineio/configurator-sdk) ↗ · The command is for React 19; on React 18, use the one in the quickstart.
Install and mount Quickstart — from an empty Vite app to a running configurator in about fifteen minutes.
Then follow a guide Twelve walkthroughs — your theme, buttons, your store, custom 3D, quote templates and more.
[Image: The SDK's default UI: option sidebar with layout and cabinet thumbnails, the scene toolbar with Save and Generate Assets, a live 3D kitchen with room dimensions, and the Powered by imagine.io mark]
The default UI, unmodified — one `mount()` call. Every surface of it is themeable or replaceable below.
**React** 18 or 19
**three** 0.159 or 0.186
**@react-three/fiber** 8 or 9
**zustand** 5
Vite
**Set up once, in the admin panel**
Products, options, rules, constraints and prices live in imagine.io. Change them there and every site running the SDK updates — no code, no release.
**Every surface is yours**
Restyle it with theme tokens or plain CSS, swap any component for your own, pick a layout, or run it inside your storefront and talk to it over `postMessage`. Each has a working default, so you only touch what you want to change.
What's in each section
01 Quickstart Install, initialize and mount — an empty Vite app to a live configurator, including every configuration value the SDK reads.
02 Customise the UI Theme tokens, layout templates, overriding the built-in components, custom quote & BOM documents — and the full component library.
03 Embed a public link Put a ready-made configurator on a store page with one iframe — no install, no key, no build step — and drive it from your own buttons.
04 E-commerce bridge Drive the configurator from a parent page over postMessage — the complete wire protocol for a store integration.
05 Events & rules The SDK lifecycle bus and the backend rule bus — react to everything without owning any of it.
06 Rule & constraint evaluation What the engine is asked on every change, what it answers, and how to read that answer — visibility, availability, price, messages, rejections.
07 Guides Twelve step-by-step walkthroughs, each ending in a reference of what it used: theme & layout, buttons, custom 3D, quote templates, e-commerce platforms, popups, your own APIs, rules & constraints, placement logic, the loading screen, dimensions.
08 API reference The complete reference — every function, hook and namespace, each with a runnable example.
#### How it fits together
Permalink: https://configurator-platform.imagine.io/sdk/index.html#model
Two ideas explain every extension point, so you can predict the API instead of memorising it.
#### imagine.io decides, the SDK shows
The SDK never invents behaviour. Every choice a shopper makes is sent to imagine.io, which answers with what is allowed, what it costs and what the scene should look like. That is why one SDK serves a kitchen, a sofa or any other product line: the difference is your data, not the code.
#### Name it in data, supply it in code
Every customisation is a `register (name, implementation)` call that returns an `unregister`. Registering a name twice keeps the latest; a name imagine.io asks for that you have not registered falls back to the built-in and **never throws**. So the admin panel can pick a layout, a placement strategy, a quote template or a component by name, and your code provides that name's implementation — the two are wired without either side hardcoding the other.
One call
`configure({...})` registers many extensions at once — components, slots, theme, labels, events, middleware, placement strategies — and returns a **single teardown** that reverses all of them. It's the right entry when an integration mounts and unmounts as a unit.
#### The words on this page
Permalink: https://configurator-platform.imagine.io/sdk/index.html#glossary
Thirteen terms carry the whole documentation. Skim these once and every section below reads normally:
| **engine** | your backend rules service. Every change the shopper makes is sent to it (“an **evaluate** ”), and it answers with the authoritative scene + prices. The SDK renders; the engine decides. |
| --- | --- |
| **system** | one configurable product line — a sofa, a kitchen. `systemId` (from onboarding) picks which one loads. |
| **product & variant** | a product is the catalog item (“Base Cabinet”); a variant is one concrete version of it (“Single Door 9″”). Adding to the scene takes both ids. |
| **placement** | one product _placed in the scene_, with an engine-minted id like `'p1'`. Payloads sometimes call it a _piece_ or an _instance_ — same thing. |
| **option set & option** | a choice group (“Fabric”) and its choices (“Cognac”). Selected by `optionSetId` + `optionId`. |
| **hosted product** | a product that mounts ON another product — an appliance on a cabinet. The carrier is its **host**. |
| **run & placementGroup** | products chain side-by-side into rows (“runs”). `placementGroup` names which row a placement belongs to (`'floor'`, `'wall'`). |
| **preset** | a saved starting arrangement for a system (also called a _scene config_) — what a layout picker applies. |
| **shell** | the page arrangement around the scene (where the sidebar sits, wizard vs single page). Registered/selected via `ui.registerLayout`. |
| **anchor** | holding a product “on the cursor” so the shopper clicks where it goes — the two-step add flow. |
| **admin panel** | where your organisation sets everything up — catalog, systems, rules, prices, users and API keys — at [admin-configurator.imagine.io](https://admin-configurator.imagine.io/). |
| **API key** | your organisation's long-lived credential, created in the admin panel as read & write or read only. Fine in internal tools and development; never in a public page. |
| **session token** | a 30-minute credential imagine.io issues when _your server_ presents the API key. What a public page runs on; the SDK asks your server for a fresh one as needed. |
Get running
### Quickstart
Permalink: https://configurator-platform.imagine.io/sdk/index.html#quickstart
From an empty project to a live configurator. Every step below is one a stock Vite app actually runs.
Also available as its own page: [SDK quickstart](https://configurator-platform.imagine.io/sdk/quickstart/index.html), the same steps with nothing else around them.
You need
Two values: your **org API key** and the **system id** of each configurator built for you (a system is one configurable product line — a sofa, a kitchen). Both come from the imagine.io admin panel; the first step below shows where.
##### Create a Vite React app
Skip this if you're adding the SDK to an existing app. Vite is required — the SDK ships modern ESM/JSX source, which Vite transforms natively.
```
npm create vite@latest my-configurator -- --template react
cd my-configurator
```
##### Install the SDK
Version 0.1.6 and later support React 18 and React 19. The 3D packages (three, fiber, drei) are installed for you — npm 7+ adds the SDK's peer packages automatically — at the versions that match your React.
**React 19**, which a fresh Vite template ships: install the package on its own. npm adds three.js 0.186, @react-three/fiber 9 and @react-three/drei 10. Keep React at 19.3 or earlier; @react-three/fiber 9 does not accept 19.4 yet:
```
npm install @imagineio/configurator-sdk
```
**React 18**: name the React 18 versions in the same command, so npm installs three.js 0.159, @react-three/fiber 8 and @react-three/drei 9. A fresh Vite template ships React 19 types, so install the React 18 ones too:
```
npm install @imagineio/configurator-sdk react@^18.2 react-dom@^18.2 three@~0.159.0 @react-three/fiber@^8.15 @react-three/drei@^9.88 @react-three/postprocessing@^2.16 postprocessing@~6.36.0
npm install -D @types/react@^18.2 @types/react-dom@^18.2
```
Versions
The two React versions can look slightly different: three.js 0.186 lights the same HDR environment slightly differently from 0.159, and no setting changes that. Shadows render as PCF on both; the admin panel's PCF Soft and PCF Hard both render as PCF, and the shadow radius sets how soft the edges are. If `npm install` stops with `ERESOLVE`, or you are moving an app from React 18 to React 19, see Troubleshooting.
##### Add the Vite plugin
One plugin, two jobs: serves the SDK's 3D assets (the Draco decoder models load from `/assets/draco/`) in dev and copies them into your build, and keeps react/three deduped so a second copy pulled in by another dependency can't blank the canvas:
```
// vite.config.js
import imagineConfigurator from '@imagineio/configurator-sdk/vite';
export default defineConfig({
plugins: [react(), imagineConfigurator()],
});
```
##### Get your API key and system id
Both live in the **imagine.io admin panel** at [admin-configurator.imagine.io](https://admin-configurator.imagine.io/). **Sign in** — or **sign up** first if your organisation does not have an account yet.
[Image: The imagine.io admin panel sign-in screen: email and password fields and a Sign In button]
Sign in, or create the account, at the admin panel.
Catalog first
The configurator shows **nothing** until your organisation has a catalog. Before you take a key, set it up in the admin panel: products and their variants, materials, components, option sets and options, then a configurable system that ties them together. The [Admin documentation](../admin-guide/index.html#setup) walks through each of these in order.
Then go to **Settings › API Keys** and press **Create key**. Name it after the site or tool that will use it, choose its permission, and list the websites that may use it:
| **Read & write** | the full key. The configurator can save and share projects and upload renders. Use it in your own tools and on your server to request session tokens. |
| --- | --- |
| **Read only** | browse, configure and price; nothing is ever written. The safer choice for a page that never saves. It can only request read-only (`catalog`) session tokens. |
| **Websites** | at least one is required. Enter `shop.example.com` for a site, `*.example.com` for all its subdomains, and for a developer's machine `localhost` _with its port_ — `localhost:5173`, not `localhost`. The browser is refused before the key is even checked on any site not listed, so a key with an empty list works nowhere. |
[Image: The API Keys page in the admin panel: one key listed with its masked value, a permission selector, status and a Revoke action]
Settings › API Keys. Copy the key when it is shown. You can change a key's permission or its websites, or revoke it, here at any time.
The **system id** is under **Scenes › Configurable Systems**, where each configurator built for you is listed with its id. One key serves every system in your organisation.
##### Add your API key
Put the key in an **env file**, not in your source. Create `.env.local` next to `package.json` (Vite loads it automatically, and the file is git-ignored by default):
```
VITE_API_KEY=YOUR_ORG_API_KEY
```
The SDK reads `VITE_API_KEY` on its own — there is no call to make. Prefer a different variable name? Keep the env file and pass it yourself: `config.setApiKey(import.meta.env.VITE_MY_KEY)`. Then replace your `src/main.jsx` with this; the SDK brings its own styles, nothing else to import.
```
import { mount, config } from '@imagineio/configurator-sdk';
// 1. The org API key comes from .env.local (VITE_API_KEY) — nothing to write here.
// The backend endpoint and the AI-chat runtime are built into the SDK — nothing to configure.
// Using your OWN variable name? Read it and hand it over, before mount():
// config.setApiKey(import.meta.env.VITE_MY_KEY);
// 2. OPTIONAL — sales channel (per-channel prices, hidden options, theme)
config.setChannelId('dealer-42');
// 3. Boot the system, load catalog + scene, render the full default UI
const app = mount('#root', { systemId: 1 });
// later: app.unmount();
```
##### Production: a session token instead of the key
The API key is long-lived and reads your whole catalog, so it must never reach a browser. In production your server asks imagine.io for a **session token** — a 30-minute credential the browser can safely hold — and the SDK uses that instead. Three parties, one direction:
```
Browser (SDK) ──► your server ──► imagine.io POST /api/v1/auth/token/ (X-Api-Key)
◄── token ◄── imagine.io creates it and answers { access_token, expires_at, … }
```
**Your server** — one route. The key stays in an env var here and nowhere else; the response goes back to the page as-is.
```
// server.js — your backend
app.post('/configurator-token', async (req, res) => {
const r = await fetch('https://api-configurator.imagine.io/api/v1/auth/token/', {
method: 'POST',
headers: { 'X-Api-Key': process.env.CONFIGURATOR_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ scope: 'session', system_id: 12, origin: 'https://www.your-site.com' }),
});
res.status(r.status).json(await r.json());
});
```
The three body fields are optional. Each one narrows what the token can do, and narrower is safer:
| `scope` | `session` can save projects and upload renders; `catalog` can only load, configure and price. Use `catalog` for anonymous pages. A read-only key gets `catalog` tokens only. |
| --- | --- |
| `system_id` | lock the token to the one system this page shows. |
| `origin` | lock the token to your site, so one lifted from the page is useless anywhere else. |
**Your page** — hand `mount()` the route as a callback. No `VITE_API_KEY` exists in this build.
```
const app = mount('#root', {
systemId: 12,
getToken: async () => (await fetch('/configurator-token', { method: 'POST' })).json(),
});
```
That's it
The SDK sends the token as `Authorization: Bearer` on every request and never the key. It calls your route again shortly before the token expires and once more on a `401`, so there is nothing to refresh by hand. If the key ever leaks, revoke it in the admin panel: every token made from it stops working within about 30 seconds. Refusals and what they mean: Troubleshooting › Session tokens. The whole flow on one page: [how session tokens work](https://configurator-platform.imagine.io/docs/concepts/session-tokens/index.html).
##### Run
```
npm run dev
```
**What you should see:** a brief loader, then the option sidebar on the left and the 3D scene on the right — like the screenshot in the Overview. Blank page or missing models? The Troubleshooting section covers every known cause. A different `systemId` is a different configurator — a sofa, a kitchen, a wardrobe — with no frontend change.
##### What next
You have a running configurator. The three things most teams do next each have a step-by-step guide:
| Make it look like your brand | change one colour, build a whole theme, or swap the page layout. |
| --- | --- |
| Change what a button does | add to Save, replace Add to cart, or add a button of your own. |
| Connect your store | run it inside Shopify or any storefront and hand the configuration to your cart. |
All twelve: Guides. Each ends with a reference of every function it used.
Reshape the interface
### Customise the UI
Permalink: https://configurator-platform.imagine.io/sdk/index.html#customize
Guide
Prefer a walkthrough? Customize Theme & Layout · Override Button Functionality · Add a Custom Button · Add Custom Popups · Customize the Loading Screen.
Everything the default UI shows can be restyled, replaced or removed — the default UI is itself built from these same seven mechanisms, so there is no surface you can't reach. Start from what you want to change, and use the _cheapest_ mechanism that does it:
| You want to… | Use | Effort |
| --- | --- | --- |
| change colors, fonts, corner radius, spacing — the brand look | Theme tokens | a config object |
| restyle or hide one specific element (a tile, a button, a heading) | Plain CSS | a normal stylesheet |
| change how one part LOOKS or BEHAVES (your own swatch, your own dialog) | Override a component | one React component |
| ADD something ours doesn't have (a promo banner, a “book a designer” button) | Slots | one React component |
| move the panels around — sidebar right, wizard steps, your own page frame | Layouts | compose from `parts.*` |
| change the quote / BOM document | BOM & quote PDF | a template, or the raw data |
| keep only our logic and write ALL the markup yourself | Headless (below) | your app, our hooks |
Every mechanism is a _registration_: call it any time (even after `mount()` — the UI re-renders live), and it returns an `unregister` function that puts ours back. Calling it is safe in any order: an unregister whose change a later call has already replaced does nothing, so it can never undo someone else's work.
**One exception: `ui.applyTheme` returns nothing.** A theme is _applied_, not registered — it writes CSS variables and root attributes rather than something we hold a previous copy of, so there is no record to put back and a theme stays applied. To change it, apply the record you want instead. (This is why `configure()` 's teardown reverses a `labels:` block but leaves a `theme:` in place.)
#### 1. Theme tokens
Permalink: https://configurator-platform.imagine.io/sdk/index.html#cz-theme
One call restyles the whole UI — pass a theme record and every color, font and radius follows. Tokens you don't set keep their defaults. `surface` is the field people miss: set only `background` and cards/dialogs stay white.
```
import { ui } from '@imagineio/configurator-sdk';
ui.applyTheme({ name: 'brand', config: {
colors: {
primary: '#1a936f', // buttons, highlights — hover/light shades derived automatically
accent: '#f2542d',
background: '#f5f1e8', // the page — a dark value switches the UI to dark mode automatically
surface: '#fdfaf2', // cards, dialogs, panels
text: '#20221f', textMuted: '#6b6f66',
border: '#e2ddd0', // omit it and rules derive from your text color
},
sizing: { cardWidth: 360, cardPadding: 16, radius: 10, controlHeight: 40, gap: 8 }, // px
typography: { fontFamily: '"Inter", "Inter Fallback", sans-serif', baseSize: 14, labelSize: 12, headingSize: 22, fontWeight: 600 },
buttons: { buttonStyle: 'filled', buttonRadius: 999, shadow: 'sm' }, // shadow: 'none' | 'sm' | 'md'
}});
```
Every token, and what it drives:
| Group | Token | Drives |
| --- | --- | --- |
| `colors` | `primary` | buttons, active states, highlights. Hover and light shades are derived, and the whole brand family (header, modals, PDFs) follows it. |
| `accent` | secondary emphasis; falls back to `primary`. |
| `background` | the page itself. A dark hex flips the UI into dark mode automatically (or set `mode: 'dark'` explicitly on the record). |
| `surface` | cards, dialogs, panels — the raised layer above the background. |
| `text` | the main ink. Secondary/tertiary text shades derive from it. |
| `textMuted` | labels and secondary copy. |
| `border` | rules and outlines. Omitted → derived from `text` so dark/warm themes never look half-applied. |
| `sizing` (px) | `cardWidth` | option-panel width |
| `cardPadding` | panel content padding |
| `radius` | corner radius of cards and thumbnails |
| `controlHeight` | button/input height |
| `gap` | spacing between option tiles |
| `typography` | `fontFamily` | the UI font — a Google Font is fetched automatically when needed |
| `baseSize` | body text size (px) |
| `labelSize` | section titles / labels (px) |
| `headingSize` | headings (px) |
| `fontWeight` | section-title weight |
| `buttons` | `buttonStyle` | `'filled'` or `'outline'` |
| `buttonRadius` | button corner radius (px) — `999` = pills |
| `shadow` | button shadow preset — exactly `'none'`, `'sm'` or `'md'`; any other value is ignored |
| text | `labels` | any UI string by key — the admin's _Text & labels_ panel writes this map (`{ 'panel.delete': 'Remove piece', 'save.snapshots': '' }`). A value rewrites our text; an **empty string hides it** — headings, hints and captions render nothing, a button becomes icon-only. A key your code set with `ui.setLabels` keeps your text whichever arrives last, and switching themes replaces the previous theme's wording rather than stacking on it. |
| record | `layoutDensity` | overall compactness |
| `logoUrl` | your logo in the header |
| `faviconUrl` | the browser-tab icon |
| `layout` | which page shell mounts — `'default'`, `'wizard'`, `'showroom'` or `'showcase'`. Omit it and the record's `name` decides (see below). |
When to call it
**Your call wins.** `ui.applyTheme()` from app code — before or after `mount()` — marks the theme as yours, and the backend's theme (applied during boot, and again when the shell mounts) yields to it. The one thing that still outranks you is the `?theme= ` URL preview, on purpose: it lets anyone preview a preset without touching code or backend. It takes string ids only (`?theme=theme3`), never a record.
Records vs presets
Two code paths. A **string** — `ui.applyTheme('theme3')` — selects one of the shipped preset palettes (`theme2` … `theme5`) from our stylesheet. A **record** — `{ name, config }` — writes your tokens as CSS variables. A record _named_ after a preset (`{ name: 'Theme 3' }`) selects that preset's palette too, with any tokens you pass layered on top.
**The name also picks the page shell.** A record's `name` is slugified into a layout key: `'Theme 2'` → the wizard shell, `'Theme 3'` → showroom, `'Theme 4'` → showcase. Any other name (`'brand'`, `'studio'`) matches no shell, so the default shell renders — the palette still applies, and the console says so. To choose the shell independently of the name, set `layout` on the record, or call `ui.setLayout()`, which outranks everything.
Three token vocabularies
A record's colours land as `--color-*`, most component CSS reads `--bg-*`, `--text-*` and `--border-*`, and a third family — `--color-brand-*` — sits **upstream of both**: `variables.css` defines `--color-primary: var(--color-brand-primary)`, and a dozen stylesheets read the brand tokens directly. `applyTheme` writes all three from the one record, which is why the record path just works.
**Theme with CSS instead of a record and you own all three.** Setting only `--color-primary` recolours the sidebar and leaves the header, the save dialog and the generated-assets modal on our orange; setting only `--color-*` leaves every dialog on our default surfaces. The full list is below — set what you need from it, or pass a record to `ui.applyTheme` and let it derive the rest.
Every variable `applyTheme` writes, what it derives from, and what it costs to miss it. The lighten/darken percentages are exact. A value your record does not supply is **not written at all** — the stylesheet default stands — and `ui.applyTheme(null)` removes every row here at once.
| Family | Variable | Derived from | What it paints / why it matters |
| --- | --- | --- | --- |
| brand | `--color-brand-primary` | `colors.primary`, verbatim | The **root** brand colour, not a derivative: the header, sidebar active states, the save and generated-assets modals, the AR viewer and the wizard shell read it _directly_. |
| `--color-brand-primary-dark` | `primary` darkened 15% | hover / pressed states of brand surfaces |
| `--color-brand-primary-light` | `primary` lightened 30% | tints and subtle fills |
| `--color-brand-primary-rgb` | `primary` as an `R, G, B` triple | the `rgba(var(--color-brand-primary-rgb),.1)` pattern — a hex value here makes every such rule invalid |
| `--color-brand-accent` | `colors.accent`, else `primary` | secondary emphasis on brand surfaces |
| `--color-*` | `--color-primary` | `colors.primary` | In `styles/variables.css` this one _defaults to_ `var(--color-brand-primary)` — the brand family above is upstream of it. That inversion is why setting only `--color-primary` from CSS leaves the header and the modals on our orange. |
| `--color-primary-dark` | `primary` darkened 15% | primary-button hover |
| `--color-accent` | `colors.accent` | accents and secondary emphasis |
| `--color-background` | `colors.background` | the page ground |
| `--color-surface` | `colors.surface` | the raised layer |
| `--color-foreground` | `colors.text` | the main ink |
| `--color-secondary` | `colors.textMuted` | muted copy |
| `--color-border` | `colors.border` | rules and outlines |
| `--bg-*` | `--bg-primary` | `surface`, else `background` | the raised surface — cards, dialogs, panels. Derived from `surface` rather than `background` on purpose; the steps below move away from it. |
| `--bg-secondary` | `background`, else `surface` darkened 4% | the layer behind the raised one |
| `--bg-tertiary` | (`background`, else `surface`) darkened 8% | wells, inset areas |
| `--bg-muted` | (`background`, else `surface`) darkened 2% | quiet fills, disabled rows |
| `--text-*` | `--text-primary` | `colors.text` | body ink across every component |
| `--text-primary-rgb` | `text` as an `R, G, B` triple | the theme shells tint their surfaces with `rgba(var(--text-primary-rgb),.08)`. Skip it and a themed sidebar sits inside a shell still tinted with _our_ ink — the classic half-applied look. |
| `--text-secondary` | `textMuted`, else `text` lightened 45% | labels, secondary copy |
| `--text-tertiary` | `textMuted`, else `text` lightened 60% | hints, captions |
| `--border-*` | `--border-default` | `colors.border`, else `text` lightened 86% | every rule and outline. Derived from the _ink_ when no border is named, because a palette that states its ink and paper has implied its rules. |
| `--border-light` | the resolved rule lightened 35% | hairlines, dividers inside a card |
| `--border-dark` | the resolved rule darkened 20% | emphasised or focused outlines |
| sizing | `--sidebar-width` | `sizing.cardWidth` | option-panel width |
| `--sidebar-content-padding` | `sizing.cardPadding` | panel content padding |
| `--radius-xl` | `sizing.radius` | card corner radius |
| `--thumbnail-border-radius` | `sizing.radius` | thumbnail corner radius — the same input drives both |
| `--btn-height-md` | `sizing.controlHeight` | button / input height |
| `--thumbnail-gap` | `sizing.gap` | spacing between option tiles |
| typography | `--font-size-md` | `typography.baseSize` | body text |
| `--sidebar-section-title-size` | `typography.labelSize` | section titles and labels |
| `--font-size-2xl` | `typography.headingSize` | headings |
| `--sidebar-section-title-weight` | `typography.fontWeight` | section-title weight |
| `--font-family-base` | `typography.fontFamily`, else `typographyTokens.bodyFont` | the UI font — a Google Font is fetched automatically |
| `--font-family-heading` | `typographyTokens.headingFont`, else `typography.fontFamily` | headings, when the record separates them |
| buttons & shell | `--btn-border-radius` | `buttons.buttonRadius` | button corners (999 = pills) |
| `--btn-shadow` | `buttons.shadow` preset — `'none'` / `'sm'` / `'md'` | button shadow only. Deliberately _not_ `--shadow-md`, which every card uses. |
| `--layout-density` | `layoutDensity` | overall compactness |
| `--brand-logo-url` | `logoUrl`, wrapped as `url("…")` | the header logo — a bare URL will not work here |
| attributes (not variables) | `data-theme` | `layout` if the record sets one, else its `name`, slugified | picks the page shell (`theme2` → wizard, `theme3` → showroom, `theme4` → showcase) |
| `data-theme-preset` | set only when `name` matches a shipped preset | renders that preset's palette block from `themes.css`, under your explicit tokens |
| `data-theme-mode` | `mode`, else the luminance of the resolved `background` | `light` / `dark` — the shared dark skin hangs off this |
| `data-button-style` | `buttons.buttonStyle` | `filled` or `outline`; any other value is ignored |
| `data-theme-id` | `theme.id` | debugging only — nothing styles off it |
#### 2. Style any part with plain CSS
Permalink: https://configurator-platform.imagine.io/sdk/index.html#cz-theme-css
When a theme token can't express what you want, just write normal CSS in your own stylesheet. Every element the SDK renders carries a `data-part` attribute — a stable name that never changes between releases — and the SDK deliberately keeps its own styles in a weaker CSS layer, so **your plain CSS wins over our component styles** — no specificity battles, no digging for class names. One scoped exception: **theme tokens** (`--color-*`, `--font-*`, `--bg-*`, `--text-*` …) are written by `applyTheme` as _inline_ styles on ` `, and inline beats any stylesheet regardless of layer. Overriding a _token_ from CSS therefore does need `!important` — or, better, pass it through `ui.applyTheme` and skip the fight. Going the CSS route, work from the derived-token list: there are three colour families, and setting one of them recolours part of the UI.
##### Find the part
Right-click the element → Inspect. The attribute is right there: `
##### Write a normal selector against it
Target `[data-part="…"]` — never our class names (those are internal and may change; `data-part` is the contract).
##### That's it
Put it in any stylesheet your app already loads. It applies immediately and survives every SDK update.
A small makeover, line by line:
```
/* your-app.css — plain CSS, loaded like any other stylesheet */
/* 1. round the option swatches and brand the selected one */
[data-part="option-card"] { border-radius: 12px; }
[data-part="option-card"][aria-selected="true"] { outline: 2px solid #1a936f; }
/* 2. make every toolbar button pill-shaped */
[data-part="toolbar-button"] { border-radius: 999px; }
/* 3. hide one specific button (pair data-part with data-button) */
[data-part="toolbar-button"][data-button="fullscreen"] { display: none; }
```
Every `data-part` the SDK stamps, with a copy-paste starter for each:
| data-part | What it is | Starter |
| --- | --- | --- |
| `option-set` | one option-set section in the sidebar | `[data-part="option-set"] { margin-bottom: 20px; }` |
| `option-set/title` | that section's heading | `[data-part="option-set/title"] { text-transform: none; }` |
| `option-set/options` | the grid holding its options | `[data-part="option-set/options"] { gap: 10px; }` |
| `option-set/toggle` | its expand/collapse control | `[data-part="option-set/toggle"] { display: none; }` |
| `option-card` | a single option / swatch tile | `[data-part="option-card"] { border-radius: 12px; }` |
| `toolbar-button` | one scene-toolbar button — add `[data-button="…"]` to hit a specific one | `[data-part="toolbar-button"] { background: #111; color: #fff; }` |
| `popover` | any floating popover panel | `[data-part="popover"] { box-shadow: 0 12px 40px rgb(0 0 0 /.18); }` |
| `modal` | the backdrop behind a host-registered modal (`ui.registerModal`) — dims and blurs the page; the blur amount is the `--modal-backdrop-blur` token (default `4px`), shared by every dialog backdrop of ours | `[data-part="modal"] { background: rgb(20 18 15 /.6); }` |
| `modal/panel` | the panel your modal component renders inside — centred, themed, scrollable | `[data-part="modal/panel"] { max-width: 720px; border-radius: 4px; }` |
| `sidebar-frame` | the sidebar's outer container (desktop, embedded and mobile variants) | `[data-part="sidebar-frame"] { border-right: 1px solid var(--border-default); }` |
| `loading` | the loading screen — boot overlay and the compact in-context form (`data-compact="true"`) | `[data-part="loading"][data-compact="true"] { border-radius: 999px; }` |
| `quote` | the whole on-screen quote document | `[data-part="quote"] { font-family: Georgia, serif; }` |
| `quote/brand` | the logo + company block at the top | `[data-part="quote/brand"] { justify-content: center; }` |
| `quote/head` | the header: quote title + date | `[data-part="quote/head"] { border-bottom: 2px solid #111; }` |
| `quote/for` | the reference / recipient line (“Quote 1042 · For …”) | `[data-part="quote/for"] { font-style: italic; }` |
| `quote/scene` | the scene-selections summary line (“Finish: Oak · …”) | `[data-part="quote/scene"] { display: none; }` |
| `quote/lines` | the line-items table | `[data-part="quote/lines"] { font-size: 12px; }` |
| `quote/additional` | the additional-options table (scene-level cost lines) | `[data-part="quote/additional"] { margin-top: 16px; }` |
| `quote/totals` | the item-count + grand-total row | `[data-part="quote/totals"] { font-size: 15px; }` |
| `quote/renders` | the render-image grid | `[data-part="quote/renders"] { gap: 12px; }` |
| `quote/render` | one render image in that grid | `[data-part="quote/render"] { border-radius: 8px; }` |
| `quote/qr` | the AR QR-code block | `[data-part="quote/qr"] { display: none; }` |
| `quote/terms` | the notes / terms footer | `[data-part="quote/terms"] { font-size: 11px; }` |
Possible values of `data-button` (on `toolbar-button`) — always paired with the part selector:
| data-button | Button | Starter |
| --- | --- | --- |
| `toggle2d3d` | the 2D / 3D view switch | `[data-part="toolbar-button"][data-button="toggle2d3d"] { font-weight: 700; }` |
| `dimensions` | dimension overlay on/off | `[data-part="toolbar-button"][data-button="dimensions"] { background: #1a936f; color: #fff; }` |
| `walls` | wall visibility | `[data-part="toolbar-button"][data-button="walls"] { border-radius: 999px; }` |
| `resetCamera` | reset the camera | `[data-part="toolbar-button"][data-button="resetCamera"] { opacity:.6; }` |
| `fullscreen` | enter/exit fullscreen | `[data-part="toolbar-button"][data-button="fullscreen"] { display: none; }` |
| `undo` | undo the last change | `[data-part="toolbar-button"][data-button="undo"] { display: none; }` |
| `redo` | redo the undone change | `[data-part="toolbar-button"][data-button="redo"] { display: none; }` |
`uiToggles` keys — the backend's `system.uiToggles` and `ui.setToggles()` share one key set. A key set to `false` removes the control (distinct from _disabled_, which is a state reason); an absent key means shown. The host's value wins over the backend's, per key.
| Key | Removes | Note |
| --- | --- | --- |
| `dimensions` · `walls` · `resetCamera` · `fullscreen` · `undo` · `redo` | the matching toolbar button | same names as `data-button` above |
| `liveStatus` | the live status / debug panel | — |
| `selectionPanel` | **selecting pieces at all**: a click on a piece does nothing, no selection or hover outline is drawn, and the per-piece action panel never mounts — even if code sets a selection | the master switch for the six keys below; placement-target clicks (placing a hosted product) still work |
| `panelPrice` | the price chip in the per-piece action panel | — |
| `panelMoveLeft` · `panelMoveRight` | the reorder buttons | — |
| `panelAdd` · `panelDuplicate` · `panelDelete` | the add / duplicate / delete buttons | named after the panel's label keys (`panel.add`, …); a control the piece does not offer is absent regardless |
Why this works
The SDK's own styles live in a CSS `@layer`, and layered CSS always loses to your unlayered CSS — that ordering is the published contract. Prefer hiding buttons via `ui.setToggles({ fullscreen: false })` when you want them gone functionally; use CSS when you're reskinning.
#### 3. Override a component
Permalink: https://configurator-platform.imagine.io/sdk/index.html#cz-override
Same word, two things
“Component” here means a **React component** of the UI. Elsewhere (`scene.hideComponent`, `componentId`, `parts.ComponentMesh`) it means a **physical part of a product** — a door, a handle, a leg. Context makes it clear, but they are unrelated.
Your component receives our built-in as `Default` — wrap it rather than reimplement. Registering after `mount()` re-renders live.
```
// overrides.jsx — a .jsx file, because the override returns markup
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('OptionThumbnail', ({ Default, ...props }) => (
{props.option?.isNew && New}
));
```
The complete set of overridable components:
`Sidebar` `OptionSetSection` `OptionThumbnail` `FinishThumbnail`
`LayoutThumbnail` `HostedProductThumbnail` `AddProductToggle` `SceneToolbar`
`SelectionActionPanel` `SaveProjectButton` `GenerateAssetsButton` `LiveStatusPanel`
`ChatBar` `ConfirmDialog` `SceneDimensions` `ARViewer` `LoadingScreen`
What each one receives. Every override also gets `Default` (the built-in, injected by the registry — it is only present when an override is registered). Props below are extracted from the actual render sites; shapes in metres/ids as noted.
| Component | Props it receives | Renders |
| --- | --- | --- |
| `Sidebar` | `embedded?: boolean`, `optionSetIds?: string[]` (wizard/showcase shells pass the step's option-set ids), `backHeader?: boolean` (default `true` — the '‹ Selected' row above a focused piece's options; pass `false` when your shell already names the selection) | Main option panel — desktop panel, mobile tab, all shells |
| `SceneToolbar` | `variant: 'desktop' \| 'mobile'` | Header (desktop) / above the scene (mobile, shells) |
| `SaveProjectButton` | `disabled: boolean`, `className?: string` | Header, mobile top bar, shell CTAs |
| `GenerateAssetsButton` | `onClick: () => void`, `isGenerating: boolean`, `disabled: boolean`, `className: string` | Header, mobile top bar, shell CTAs |
| `LiveStatusPanel` | `embedded?: true` (mobile tab) — no props on the desktop float | Status/debug panel when the panels region is on |
| `ChatBar` | `alwaysExpanded?: true` (mobile tab, shell FAB popup) — no props on the desktop chat card | AI assistant input |
| `OptionSetSection` | `title: string`, `presentation: 'inline' \| 'accordion'`, `flow: 'column' \| 'row'`, `gridClassName`, `className`, `labelKey: optionSetId`, `sectionRef`, `beforeGrid?`, `kind?: 'group'`, `depth?`, `defaultOpen?`, `children` | Every option-set block in the sidebar (8 sites) |
| `OptionThumbnail` | `option: { id, name, value, thumbnail?, disabled?, disabledReason? }`, `isSelected: boolean`, `onClick: () => void` | Generic option grids |
| `FinishThumbnail` | `option` (as above), `material: { thumbnail?, textures?: { diffuse? }, color? }`, `isSelected`, `onClick` | Material/finish grids (thumbnail → diffuse → color fallback) |
| `LayoutThumbnail` | `option: { id, value, thumbnail? }` (`value` is the layout class, e.g. `l_shaped`), `isSelected`, `onClick` | Layout picker grid |
| `HostedProductThumbnail` | `appliance: { id, name, thumbnail?, icon?, isPlaced, canReplace, isDisabled, … }`, `isSelected`, `isPlaced`, `canReplace`, `isDisabled`, `onClick` | Hosted-product (appliance) cards |
| `AddProductToggle` | `optionSet` — the option-set record, `getOptionsForSet(set)` — the set's options, `getSelection(optionSetId)`, `onSelectionChange(optionSetId, optionId, set)` | An add-a-product option set rendered as an on/off toggle |
| `ConfirmDialog` | `dialog: { title?, message, hint?, confirmText?, cancelText?, singleButton?, onConfirm?, onCancel? } \| null`, `onClose: () => void` | Overlap/confirm prompts (all sidebar variants) |
| `SelectionActionPanel` | `actions: { onMoveLeft, onMoveRight, onDuplicate?, onDelete, disabledActions: { moveLeft?, moveRight?, duplicate?: { disabled, reason } } }`, `priceInfo: { unitPrice, adjustments, currency } \| null` | DOM overlay over the canvas while a piece is selected |
| `SceneDimensions` | `bbox: { minX, maxX, minZ, maxZ, w, d, h, height }` — metres; `h` = wall height, `height` = tallest piece top. **Renders inside the scene canvas**, not the DOM | When the dimensions toolbar toggle is on and the scene has extent |
| `ARViewer` | no props — reads the `?src` GLB URL itself | The `/ar-viewer` route (QR-code landing page) |
**A worked override for every component** — each is complete and copy-paste-ready; swap the class names and inner components for your own. These return JSX, so they belong in a `.jsx` / `.tsx` file; `MySwitch`, `MyModal`, `MyMobileBar` and `MyCallouts` stand in for your own components:
`Sidebar` put the whole option panel in your own frame (everything inside still works)
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('Sidebar', ({ Default, ...props }) => (
));
```
`OptionSetSection` force every option group open, with your own heading style
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('OptionSetSection', ({ Default, ...props }) => (
));
```
`OptionThumbnail` badge new options; keep our tile underneath
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('OptionThumbnail', ({ Default, ...props }) => (
{props.option?.isNew && New}
));
```
`FinishThumbnail` render material swatches your own way (thumbnail → texture → flat color)
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('FinishThumbnail', ({ option, material, isSelected, onClick }) => (
));
```
`LayoutThumbnail` bigger layout tiles with the name under the image
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('LayoutThumbnail', ({ option, isSelected, onClick }) => (
{option.value.replace('_', ' ')} {/* e.g. "l shaped" */}
));
```
`HostedProductThumbnail` show placed state and why a card is disabled
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('HostedProductThumbnail', ({ appliance, isPlaced, isDisabled, onClick }) => (
));
```
`AddProductToggle` render an add-a-product option set as your own switch
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('AddProductToggle', ({ optionSet, getOptionsForSet, getSelection, onSelectionChange }) => {
const [offOpt, onOpt] = getOptionsForSet(optionSet);
const isOn = String(getSelection(optionSet.id)) === String(onOpt?.id);
return onSelectionChange(optionSet.id, (v ? onOpt : offOpt).id, optionSet)} />;
});
```
`SceneToolbar` desktop keeps our toolbar; mobile gets your compact one
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('SceneToolbar', ({ Default, variant, ...props }) =>
variant === 'mobile' ? :
);
```
`SelectionActionPanel` your own action pill — same handlers, plus the live unit price
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('SelectionActionPanel', ({ actions, priceInfo }) => (
));
```
`SaveProjectButton` restyle the save CTA (the built-in keeps the whole save flow)
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('SaveProjectButton', ({ Default, ...props }) => (
));
```
`GenerateAssetsButton` your button, our generation pipeline
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('GenerateAssetsButton', ({ onClick, isGenerating, disabled }) => (
));
```
`LiveStatusPanel` hide the status panel entirely
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('LiveStatusPanel', () => null);
```
`ChatBar` keep the assistant, change its frame
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('ChatBar', ({ Default, ...props }) => (
));
```
`ConfirmDialog` route confirms through your own modal system
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('ConfirmDialog', ({ dialog, onClose }) => {
if (!dialog) return null;
return { dialog.onConfirm?.(); onClose(); }}
confirmText={dialog.confirmText ?? 'Continue'}>{dialog.message};
});
```
`SceneDimensions` custom measurement callouts (renders INSIDE the scene canvas)
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('SceneDimensions', ({ bbox }) => (
// metres
));
```
`ARViewer` brand the AR landing page a phone opens from the QR code
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('ARViewer', ({ Default, ...props }) => (
Acme Studio
));
```
#### 4. Add net-new UI — slots
Permalink: https://configurator-platform.imagine.io/sdk/index.html#cz-slots
**When:** you want to ADD something the UI doesn't have — a promo banner, a “book a designer” button, a live chat bubble — without touching what's already there. A slot is a fixed spot where the SDK renders nothing of its own; register a component and it appears there. A custom div in the sidebar reflows its siblings automatically (the sidebar is normal flex flow). There are five slots — each renders at a fixed spot and hands your component a context object:
| Slot | Renders | Context props |
| --- | --- | --- |
| `toolbar` | beside the scene-toolbar buttons (2D/3D, undo, walls…) | `{ isMobile }` |
| `sidebar-top` | top of the option panel, above every option set | `{ placementId }` |
| `sidebar-bottom` | bottom of the option panel, below every option set | `{ placementId }` |
| `selection-panel` | inside the floating action pill shown when a piece is selected | `{ placementId, actions }` |
| `overlay` | a full-scene layer above the 3D canvas — you position it yourself | — |
Add your own pieces around the built-in interface without replacing anything: a toolbar button, your own component in the `sidebar-top` slot, and an overlay layer above the scene that you position yourself:
```
import { ui } from '@imagineio/configurator-sdk';
import MyPromoBanner from './MyPromoBanner'; // your own component
ui.registerButton({ slot: 'toolbar', label: 'Book a designer', onClick });
ui.registerSlot('sidebar-top', ({ placementId }) => );
ui.registerSlot('overlay', () =>
…
);
```
#### 5. Rearrange everything — layouts
Permalink: https://configurator-platform.imagine.io/sdk/index.html#cz-layouts
Same word, two things
“Layout” here means the **page shell** (where the sidebar and scene sit). The _product arrangement_ layout — L-shaped vs U-shaped — is a normal option the shopper picks (see `LayoutThumbnail`, and the bridge's `setLayout` command drives that one).
**When:** the pieces are right but the page isn't — you want the sidebar on the right, a wizard flow, or your own frame around everything. A layout owns where the panel sits, the chrome, the mobile shape. Compose it from `parts.*` (~50 exported components) instead of rebuilding. Read `ui.activeLayout()` before registering — the backend may have selected another shell.
```
import { ui, parts } from '@imagineio/configurator-sdk';
function MyShell({ Scene }) {
return (
// a COMPONENT — render it, don't interpolate it
// where ui.registerSlot content renders
// where ui.registerModal content renders
);
}
ui.registerLayout(ui.activeLayout() ?? 'default', MyShell);
```
Three things every shell needs
**Render ` `, never `{Scene}`.** It is a component; interpolating it hands React a function, which renders nothing — a shell with no 3D scene and no error.
**Mount `parts.SlotHost` and `parts.ModalHost`.** They are the render points for `ui.registerSlot` and `ui.registerModal`; without them every such registration silently stops working in your shell. One host per slot name — and only for slots nothing else renders. `overlay` is the one a custom shell always owns, because it replaced the layout that used to render it. The other three come free with the part that owns them: `toolbar` with `parts.SceneToolbar`, `sidebar-top` and `sidebar-bottom` with `parts.Sidebar`, `selection-panel` with the selection pill. Mount a second host for one of those _and_ the part that owns it, and the registration renders twice.
**Size the scene's box.** The canvas fills its container. In a full-height column beside a panel (every built-in shell) that just works; in a grid with a top bar and a bottom deck, the scene row will size to the viewport and push later rows off-screen. Give that row `min-height: 0` and its scene container `position: relative; overflow: hidden`, and the canvas will take the row, not the page.
#### 6. Whole pages & canvas-only
**When:** you need to own an entire page (like the AR landing page a QR code opens), or you want ONLY the 3D scene and none of our chrome. Replace a page a QR opens, or hide our UI entirely and build your own around the 3D scene. Hidden regions aren't rendered, so they don't compete for space.
```
import { ui } from '@imagineio/configurator-sdk';
import MyArPage from './MyArPage'; // your own page component
ui.registerRoute('/ar-viewer', MyArPage);
ui.hide('sidebar', 'toolbar'); // bare canvas + your own chrome
```
#### 7. Headless — your markup, our logic
**When:** your design system must own every pixel and none of our components fit — you write all the markup, and the hooks hand you the data and the dispatch so your UI behaves exactly like ours. React hooks expose option resolution, availability, hidden-option filtering and dispatch, so custom markup never re-derives them. `select()` routes through the same path our sidebar uses.
```
import { useOptionSets } from '@imagineio/configurator-sdk';
const { optionSets, getOptionsForSet, visibleOptions,
optionDisabledPropsFor, select } = useOptionSets();
// render your own buttons; select(set.id, option.id, set)
```
**The other headless hooks** — each re-renders your component exactly when its data changes. They are all flat named exports from the same package:
```
import { usePrice, useProducts, useSelection, useSelectionActions,
useToolbar, useLabels, useBootStatus } from '@imagineio/configurator-sdk';
```
`usePrice` the live total for your own price display
```
import { usePrice } from '@imagineio/configurator-sdk';
function MyPrice() {
const { grandTotal, currency } = usePrice(); // re-renders on every engine re-price
return {currency} {grandTotal?.toLocaleString()};
}
```
`useProducts` everything placed in the scene, as plain rows
```
import { products, useProducts } from '@imagineio/configurator-sdk';
function MyPartsList() {
const products = useProducts(); // [{ placementId, productId, variantId, sequence, placementGroup, … }]
return
{products.map((p) =>
{p.variantId}
)}
;
}
```
`useSelection` react to what the shopper has selected
```
import { useSelection } from '@imagineio/configurator-sdk';
function MyInspector() {
const { isSelected, placementId, piece } = useSelection();
if (!isSelected) return
;
}
```
`useSelectionActions` the selected piece’s actions + price, for a custom panel
```
import { useSelectionActions } from '@imagineio/configurator-sdk';
function MyActionBar() {
const { panelActions, priceInfo } = useSelectionActions();
if (!panelActions) return null; // nothing selected
return (<>
{priceInfo && {priceInfo.currency} {priceInfo.unitPrice}}
>);
}
```
`useToolbar` all toolbar state + handlers, for building your own toolbar
```
import { useToolbar } from '@imagineio/configurator-sdk';
function MyToolbar() {
const { is3D, handleToggleView, canUndo, handleUndo, isOn } = useToolbar();
return (<>
{isOn('undo') && }
>);
}
```
`useLabels` every UI string through one function — localize or rebrand text
```
import { useLabels } from '@imagineio/configurator-sdk';
function MyHeading({ setId }) {
const label = useLabels(); // returns the getLabel(key, fallback) function
return
{label(`optionSet.${setId}`, 'Options')}
;
}
```
`useBootStatus` drive your own loading screen
```
import { useBootStatus } from '@imagineio/configurator-sdk';
function MyShellGate({ children }) {
const boot = useBootStatus(); // { loading, progress, themeReady, ready, … }
if (!boot.ready) return ;
return children;
}
```
#### Custom scene dimensions
The measurement overlay is replaceable like any component — and the geometry it draws from is public, so an elevation-style overlay (callouts per piece, imperial units, your typography) is an override plus one reader:
```
import { ui, scene } from '@imagineio/configurator-sdk';
// Replace the built-in dimensions overlay. Your component renders INSIDE the R3F tree
// (drei Html/Line available, no manual disposal), receives the run's bbox + our Default,
// and rides the same toolbar toggle the user already knows.
ui.registerComponent('SceneDimensions', ({ bbox, Default }) => (
// or to keep ours too
));
// Need per-piece geometry (a callout on each product's back panel)? Read render truth —
// no scene traversal, no name heuristics:
await scene.onSettled(); // wait for late-loading models first
const { total, pieces } = scene.readBounds();
// total: { min, max, w, h, d } — the whole run
// pieces: [{ placementId, productId, worldBox, localBox, matrixWorld }]
```
Enable / disable
Hide built-in buttons at runtime with `ui.setToggles({ fullscreen: false })` — it merges over the backend's toggles and can also switch one back _on_. Option availability and visibility (greyed / hidden options) are backend-driven per the option-set records.
#### Custom BOM / quote PDF
Permalink: https://configurator-platform.imagine.io/sdk/index.html#bompdf
Guide
Prefer a walkthrough? Customize or Create Quote Templates.
The quote & bill-of-materials document is fully replaceable. Style the on-screen quote with `quote.registerTemplate`, or take the raw data below and build the document anywhere — your own renderer, your ERP, your invoicing system.
##### Take the raw data and do anything (no SDK PDF path at all)
```
import { commerce } from '@imagineio/configurator-sdk';
// The raw bill of materials — one row per placed piece, in order, with the ids a commerce
// platform keys on and the engine's own per-piece price (never computed locally).
const { lines, grandTotal, currency, metadata } = commerce.readBom();
// lines[i] = { placementId, productId, variantId, sku, name, qty,
// unitPrice, adjustments, selections, metadata }
// → build your own PDF, or POST straight to your ERP / invoicing system.
```
##### Everything you can put in a BOM — the readers
These return plain data you can drop into any PDF, cart, or ERP:
| Get | Call | Returns |
| --- | --- | --- |
| Placed products + prices | `commerce.readBom()` | `{ lines, grandTotal, currency }` — each line has `sku, name, qty, unitPrice, adjustments, variantId, selections, selectionsNamed, components, materials` |
| Priced, display-ready lines | `quote.read()` | `{ lines, totals }` — the same rows plus formatted prices and `totals.grandTotal` |
| Ready-made document model | `commerce.collectBom()` | `{ groups, title, summary, currency }` — one flat “Bill of Materials” list: every part is a line, duplicates collapsed with qty, priced hardware (handles etc.) as regular lines. What our built-in BOM PDF renders. Async. |
| Silo / lifestyle images + AR link | `quote.images()` | `{ images, ready }` — each `{ type: 'silo'\|'lifestyle'\|'ar'\|'pdf', url, status, label }` |
| Generate those assets first | `quote.generateAll()` | renders silo + lifestyle + AR server-side; `quote.generationStatus()` reports progress |
| A live scene render | `scene.capture()` | `{ perspective, front, top }` data-URLs — an alternative image source |
```
import { commerce, quote } from '@imagineio/configurator-sdk';
// PRODUCTS IN THE SCENE, WITH PRICES. One row per placed piece, in order. Prices are
// backend-authoritative (echoed on every /evaluate/), never computed locally.
const { lines, grandTotal, currency } = commerce.readBom();
// lines[i] = { placementId, productId, variantId, sku, name, qty,
// unitPrice, adjustments, selections, metadata }
// Or the display-ready version — same rows with formatted prices + a total:
const priced = quote.read(); // { lines, totals: { grandTotal, subtotal, ... } }
// Everything is plain data — feed it into your own PDF, your ERP, or a cart.
```
Trigger the PDF however you like — a custom button (`ui.registerButton`), a rule, or the Generate-Assets flow:
```
import { quote, scene } from '@imagineio/configurator-sdk';
await quote.savePdf(); // build + download it in the browser
const blob = await quote.toPdf(); // get the Blob (upload / attach / POST it)
await quote.generateBomPdf(); // produce the BOM as a Generate-Assets artefact
const b = await scene.buildPdf(); // the same document, as a Blob
```
One document
**There is one BOM.** `quote.generateBomPdf()` (the Generate-Assets `pdf` artefact) and `scene.buildPdf()` (what a saved project attaches) are the same builder over the same `commerce.collectBom()` model — so the copy a customer downloads and the copy attached to their saved design cannot disagree about what is in the configuration or what it costs.
Only the three pictures differ, because each flow has different ones to hand: the Generate-Assets copy uses that run's AI lifestyle renders, the saved copy uses 3D captures of the live scene. Pass `images` to `scene.buildPdf` to choose your own. QR pages follow the data — the AR page appears when an AR asset exists, the reopen-design page when the design has a share link.
##### Brand every document — without writing a renderer
Most integrations don't need their own PDF code; they need _their name on ours_. One object does that, and it is read by **every** document the SDK produces — the on-screen quote, `quote.toPdf()`, the Generate-Assets PDF and the file a saved project attaches. Set it once, at boot.
```
import { quote } from '@imagineio/configurator-sdk';
quote.setDocument({
company: 'Acme Interiors', // "From Acme Interiors" on the cover
customer: 'J. Marsh', // "For J. Marsh"
logoUrl: 'https://acme.com/l.png', // top-right of the cover (CORS-fetched)
accent: '#0b7285', // bands, rules, headings — hex only in PDFs
reference:'ACME-2026-0431', // your number instead of our BOM-… ref
title: 'Product Specification', // overrides the system name as the heading
notes: 'Lead time 6–8 weeks.', // printed on the cover
terms: 'Prices valid 30 days.',
arQr: true, arQrLabel: 'Scan to view in your room',
showSceneSelections: true, // false → a bare parts list, everywhere
dateFormat: { day: '2-digit', month: 'short', year: 'numeric' },
});
// Returns a reset(). Unset fields keep our defaults — nothing is all-or-nothing.
```
Two fields are screen-only
`columns` and `images` shape the _quote_ — its table columns and its render strip. The BOM has its own table (line no · item · qty · unit · total) and its own three cover/view images, so those two fields do not apply to it. Everything else in the spec applies to both.
`accent` accepts `rgb()`, `hsl()` and `var()` for the on-screen document, but a PDF has no DOM to resolve them against — so in PDFs a non-hex accent falls back to our default rather than drawing nothing. Use `#rrggbb` if you want it everywhere.
##### Replace the PDF everywhere, from one registration
Register your own builder and it becomes **the** document — in all four places a PDF can come out of the SDK: `quote.toPdf()`, `quote.savePdf()`, the Generate-Assets `pdf` artefact, and the file attached to a saved project. Register once; there is no second place to keep in step.
```
import { quote } from '@imagineio/configurator-sdk';
// A. You already render PDFs server-side — point us at it (one line).
quote.registerPdfEndpoint({ url: '/api/quote-pdf' });
// We POST `{ quote, options }` and expect a PDF back. Auth via `headers`,
// reshape with `body: (quote, opts) => ...`, `timeoutMs` defaults to 30s.
// B. You want to draw it in the browser — return a Blob.
quote.registerPdf(async (q, opts) => {
// q — quote.read(): { lines, totals } with formatted prices
// opts.bom — the full commerce.collectBom() model, already built and priced
// opts.images — { perspective, front, side } for this document
// opts.shareUrl / opts.arUrl — print them as QR codes if you want them
// opts.source — 'generate-assets' | 'save-project' | undefined (a direct toPdf call)
return myRenderer(q, opts); // Blob | Promise
});
// Several designs? Key them — the backend-selected quote design picks one.
quote.registerPdf('dealer', dealerBuilder);
```
Fails safe
If your builder throws or your endpoint is unreachable, the SDK logs the reason and renders the built-in BOM instead. A document that fails to generate is worse than one that is not on your letterhead — and the Generate-Assets pipeline still has to produce its artefact. Pass `fallback: false` to `registerPdfEndpoint` if you would rather it fail loudly.
`opts.bom`, `opts.images`, `opts.shareUrl`, `opts.arUrl` and `opts.source` are supplied when the SDK is building the BOM document. A direct `quote.toPdf(opts)` call passes only what you give it, so read them defensively — or call `commerce.collectBom()` and `quote.images()` yourself.
Keyed
The active _quote design_ is backend-selectable. Register your on-screen template under a key — `quote.registerTemplate('dealer', C)` — to ship several and let the backend choose which one a session uses.
#### Generated assets — silo, lifestyle, AR
Permalink: https://configurator-platform.imagine.io/sdk/index.html#genassets
Beyond live captures, the platform renders **marketing-grade assets** of the current configuration server-side: a _silo_ (product on white), a _lifestyle_ image (product in a styled room), and an _AR link_ (a QR-ready page that opens the model in augmented reality on a phone). Generation is asynchronous — kick it off, then read the finished URLs.
```
import { quote, scene } from '@imagineio/configurator-sdk';
// 1 — generate (server-side, async). All three, or one at a time:
await quote.generateAll(); // or generateSilo() / generateLifestyle() / generateAr()
quote.generationStatus(); // poll progress if you want a UI for it
// 2 — read the finished URLs (only assets that completed carry a url):
const { ready } = quote.images();
const silo = ready.find((a) => a.type === 'silo')?.url;
const lifestyle = ready.find((a) => a.type === 'lifestyle')?.url;
const arLink = ready.find((a) => a.type === 'ar')?.url;
// 3 — or skip generation and capture the LIVE scene as three view data-URLs:
const { perspective, front, top } = await scene.capture();
```
#### Component library `parts.*`
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-parts
Every building block the default UI is made of, exported for composing your own shell — import as `parts. ` and drop into your layout (see the composed-shell example under Layouts). The **16 marked ⭐** can also be overridden in place via `ui.registerComponent`; the rest are composition-only.
Option UI — the picker panel and its pieces
| `parts.Sidebar` ⭐ | the whole option panel (sections, pickers, appliances) |
| --- | --- |
| `parts.SidebarFrame` | the panel's chrome without its content — floating card / mobile tab body / bare column when `embedded`. A wholesale `Sidebar` override renders inside it so the custom panel lands where ours did (see Example 5) |
| `parts.OptionSidebar` | the lean, domain-agnostic picker — every scene-level option set, nothing else |
| `parts.OptionSetSection` ⭐ | one titled option-set block (inline or accordion) |
| `parts.OptionThumbnail` ⭐ · `parts.FinishThumbnail` ⭐ · `parts.LayoutThumbnail` ⭐ · `parts.HostedProductThumbnail` ⭐ | the four tile types: generic option, material swatch, layout picker, appliance card |
| `parts.ColorSwatch` · `parts.WidthSlider` · `parts.FrameSizeButton` · `parts.ProductFeaturePickers` | smaller inputs the pickers are built from |
| `parts.AddProductToggle` ⭐ | the on/off control for an add-a-product option set |
Chrome — header, toolbar, status
| `parts.Header` | the top bar (brand, toolbar, actions) |
| --- | --- |
| `parts.SceneToolbar` ⭐ | the 2D/3D · dimensions · walls · undo/redo button row |
| `parts.SaveProjectButton` ⭐ · `parts.GenerateAssetsButton` ⭐ | the two header CTAs |
| `parts.LiveStatusPanel` ⭐ | the engine status/debug panel |
| `parts.ChatBar` ⭐ | the AI assistant input |
| `parts.NotificationContainer` | where `ui.notify` toasts render — mount it once in a custom shell |
Modals & overlays
| `parts.Modals` | all built-in modals in one mount — or pick them individually below |
| --- | --- |
| `parts.SaveProjectModal` · `parts.ExportModal` · `parts.ARModal` · `parts.GeneratedAssetsModal` | the individual dialogs |
| `parts.Modal` · `parts.Button` | the primitives they are built from — reuse for visual consistency |
| `parts.ConfirmDialog` ⭐ | the confirm / overlap prompt |
| `parts.LoadingScreen` · `parts.EvaluatingOverlay` | the one loading UI (boot overlay, or `compact` pill), and the busy veil during engine round-trips — the veil renders `LoadingScreen` in compact form, so a registered `LoadingScreen` changes every loader |
| `parts.Popover` | floating panel primitive (styleable via `data-part="popover"`) |
| `parts.SlotHost` · `parts.ModalHost` | render points for `ui.registerSlot` / `ui.registerModal` content — mount them in custom shells so registrations keep working |
Scene — the 3D building blocks
| `parts.SceneStage` · `parts.SceneEnvironment` · `parts.SceneRoom` | canvas stage, lighting/ground, and the room box (walls / floor / ceiling) |
| --- | --- |
| `parts.ProductInstance` · `parts.ComponentMesh` | one placed product, and the mesh loader it renders its components with |
| `parts.SelectionBox` · `parts.SelectionActionPanel` ⭐ | the selection outline in 3D, and the floating action pill in the DOM |
| `parts.SceneDimensions` ⭐ | the measurement overlay (renders inside the canvas) |
| `parts.FreeMovable` | drag / rotate wrapper for free-floating pieces (islands, ottomans) |
| `parts.PlacementGaps` · `parts.PlacementTargets` | the "+" insertion markers, and the candidate tiles of the anchor flow |
| `parts.CameraAnimator` | animates the camera to focus targets — mount once per custom scene |
Quote & AR
| `parts.QuoteRenders` · `parts.QuoteQr` | drop-in blocks for a custom quote template: the generated images grid, and a scannable AR QR code |
| --- | --- |
| `parts.ARViewer` ⭐ | the standalone AR landing page a phone opens from the QR |
No install, no build step
### Embed a public link
Permalink: https://configurator-platform.imagine.io/sdk/index.html#embed
Guide
Already installing the package? Quickstart mounts it in your own app instead. The commands below are the same ones documented in The e-commerce bridge.
A **public link** is a ready-made configurator on a URL — `https://configurator.imagine.io/lk_qyYEAKXys-nP`. It carries its own system, catalog, theme and credentials, so a store page embeds it in an ` ` and is finished: no npm install, no API key on the page, no build step. This is the fastest route from “we have a configurator” to “it is on the product page”. [See it running](https://configurator-platform.imagine.io/demo/index.html#engine) — the live demo has a drawer that shows every response and every command on the wire.
Platform-specific steps, with the cart hand-off for each: [Shopify](https://configurator-platform.imagine.io/docs/guides/shopify/index.html), [WordPress](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html), [WooCommerce](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html), [Webflow](https://configurator-platform.imagine.io/docs/guides/webflow/index.html), and for a page of your own, [React with the SDK](https://configurator-platform.imagine.io/docs/guides/react/index.html). All of them: [platform guides](https://configurator-platform.imagine.io/docs/guides/index.html).
#### Get the link
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-get
Links are created in the admin panel, one per system, and can be revoked there. See the [Admin guide](../admin-guide/index.html) for creating and managing them. A link is safe to put in public page source: it grants that one system and nothing else, and it carries no org key.
#### Put it on the page
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-iframe
One element. The configurator boots, loads its catalog and renders itself:
```
```
Serve it over http
Open your page from a web server, not from the file system. A `file://` page has no origin the browser will deliver replies to, so the events below still arrive while every command times out — the confusing half-working state. Any static server does: `npx serve.`
#### Show only what you want
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-params
Two URL parameters decide how much of our interface appears, both read once when the frame boots. Use them when your page already has its own chrome:
```
?hide=sidebar // our option panel goes, the scene stays
?hide=sidebar,save // several at once, comma separated
?hide=all // the bare 3D scene and nothing else
?gui=false // as above, and drops in-scene overlays too
```
The names are the UI regions: `sidebar`, `header`, `toolbar`, `panels`, `chat`, `notifications`, plus the individual controls `save`, `generateAssets` and `selection`. Hiding a region hides what it contains — so `?hide=sidebar` also takes the Save and Generate Assets buttons with it on the themes that put them there. The same regions can be switched at runtime with the `hideUI` / `showUI` commands below.
#### Call into the frame
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-call
The postMessage bridge activates by itself inside a public link — there is nothing to enable. Wait for `configurator:ready`, then command it. Write callConfigurator once (ten lines, in the bridge section) and every command becomes one `await`:
```
const iframe = document.getElementById('imagine-cfg');
window.addEventListener('message', (e) => {
if (e.data?.type === 'configurator:ready') start(); // it is listening
});
async function start() {
// What can this product be asked? Build your own swatches from the answer.
const sets = await callConfigurator(iframe, 'getOptionSets');
// Your swatch → our scene. By name, or by id when your CMS stores ids.
await callConfigurator(iframe, 'selectOption', { optionSet: 'Fabric', option: 'Cognac' });
await callConfigurator(iframe, 'selectOption', { optionSetId: 579, optionId: 5706 });
// Switch off part of our UI after boot (the URL form above is boot-time only).
await callConfigurator(iframe, 'hideUI', { regions: ['sidebar'] });
}
```
One product, not the scene
Some option sets belong to a single placed product rather than the whole scene — arms, legs, modules. `selectOption` resolves those from whatever the shopper has selected in 3D, and a button on your page has no such selection, so name the product instead: read `getProductInstances`, then call `setProductOption` with its `placementId`. Scene-wide sets (finishes, fabrics, layouts) need none of this.
#### Wire it to your cart
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-cart
Two calls turn what the shopper built into a cart line — the itemised price and a snapshot that can reopen the exact build later:
```
```
Nothing above is specific to one platform: the payload is plain data, and Shopify, WooCommerce, BigCommerce or your own checkout all accept it. For platform-specific carts see Integrate with E-Commerce Platforms.
#### Every URL parameter
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-urls
Everything you can change without running a single line of script. All are read once, when the frame boots — to change something later, use a command from the next table.
| Parameter | Example | What it does |
| --- | --- | --- |
| `hide` | `?hide=sidebar,save` | Hide named UI regions. `?hide=all` leaves the bare 3D scene. An unrecognised name is ignored with a console warning that lists the valid ones. |
| `gui` | `?gui=false` | Hide the whole interface _and_ the in-scene overlays (selection outlines, hover labels, dimension text). Blunter than `hide=all`; use it for a clean display or a capture. |
| `theme` | `?theme=theme2` | Preview a theme without changing the backend. Overrides the system's configured theme for that page load — useful for showing a client two looks side by side; the admin panel is where you set the real one. |
| `project` | `?project=4821` | Open a saved project instead of the default configuration — a shopper returning to their build from an order confirmation or a wishlist. |
| `config` | `?config= ` | Restore a configuration from a share token (what `project.shareUrl()` produces). The scene opens exactly as it was shared. |
Combine freely: `?hide=sidebar,header&project=4821` opens a saved build with your own chrome around it.
#### Every postMessage command
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-actions
Fifteen commands, in four groups. Each is documented once, with its payload, its real reply and a runnable example, in the bridge chapter's full protocol — the single list this page maintains. The frame can also tell you: an unknown action replies with an error naming every action it accepts.
| **Change the configuration** | `selectOption` · `setSceneOption` · `setProductOption` · `setLayout` |
| --- | --- |
| **Read the state** | `getQuote` · `getSelections` · `getOptionSets` · `getProductInstances` · `getSceneSelections` · `getConfiguration` |
| **Camera & view** | `resetCamera` · `toggleView` |
| **Our interface** | `setUIRegions` · `getUIRegions` · `setGuiVisible` |
#### The store checklist
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-points
The eleven things a product page wires — the iframe as it should look, then the rows that get the configurator on the page, make it sellable, and cover what stores add after the first sale — are kept in one place: E-commerce integration points in the bridge chapter. Each row there points at the section that shows it running. Everything on this page is rows 1 to 7.
#### Worth knowing before you ship
Permalink: https://configurator-platform.imagine.io/sdk/index.html#em-know
- **Any page that frames a public link can drive it.** The bridge accepts commands from its parent whatever that parent is, because a public link cannot know in advance which site will embed it. Treat the link as public, and keep anything you would not publish out of that system.
- **A reply means the engine accepted it, not that a rule allowed it.** Commands are applied by the same engine your sidebar clicks go through. A rule can still reject the result a moment later, which arrives as an `evaluate.rejected` event — roll a cart line back on that event, not on the command's reply.
- **The option list is the whole catalog.** `getOptionSets` answers with every option the system defines, not only the ones currently selectable, so a button you build from it can still be refused. Read `optionAvailability` from the evaluation if you want to grey yours out the way ours are.
- **Our branding stays in the scene.** The “Powered by imagine.io” mark moves out from under panels rather than being covered, and links to the platform. It is part of the free plan, not part of the UI regions.
Talk to Shopify & other platforms
### The e-commerce bridge
Permalink: https://configurator-platform.imagine.io/sdk/index.html#commerce
Guide
Prefer a walkthrough? Integrate with E-Commerce Platforms · Integrate Custom APIs.
When the configurator runs in an **iframe** on your store, a postMessage bridge activates automatically. The parent page commands the configurator and hears everything that happens inside it — no setup in the iframe. How the numbers it hands you are made: [live pricing and quotes](https://configurator-platform.imagine.io/configurator-with-live-pricing-and-quotes/index.html).
Two routes
**Configurator in an iframe** — a public link, or your own page that mounts the SDK. The store page talks to it with postMessage. **That is this chapter.**
**SDK mounted on the store page itself** — no iframe, no bridge: call the functions directly. Prices and selections arrive through Events & rules, the catalog and the bill through the options and quote reference, and Integrate with E-Commerce Platforms walks through a whole store.
#### E-commerce integration points
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-points
The eleven things a product page wires, in the order they come up, whether the frame holds a public link or a page of your own that mounts the SDK. Each row points at the section of this chapter that shows it running.
**The iframe, as it should look.** Every row below assumes this element — copy it first, then work down the list.
```
```
`src` — the public link (row 1) · `allow` — AR, the fullscreen toggle and the Copy buttons (`clipboard-write`) (row 2) · `referrerpolicy` — keeps the referrer the domain check reads (rows 2, 3) · the disabled button wakes on `configurator:ready` (row 4).
Do _not_ add a `sandbox` attribute that strips `allow-scripts` or `allow-same-origin`, and do not set `referrerpolicy="no-referrer"` — both break the configurator from your side. Serve the page over http, not `file://`.
| # | Point | What you wire | Shown in |
| --- | --- | --- | --- |
| 1 | **Embed URL** | A public link as the iframe `src`, or a page of your own that mounts the SDK (mount()). The bridge activates automatically whenever the configurator finds itself inside an iframe. | Get the link |
| 2 | **The iframe element** | `allow="xr-spatial-tracking; fullscreen; clipboard-write"` (without `clipboard-write` the browser blocks copying inside the configurator); referrer visible (`referrerpolicy="strict-origin-when-cross-origin"` or looser) so the licence and domain checks can identify your store; responsive sizing; no script-stripping `sandbox`. | Put it on the page |
| 3 | **Domain & licence** | A link’s _Allowed domains_ and the org’s plan decide where a configurator may run. Test on the real store domain; on refusal the shopper sees a fixed licence notice (no Retry) or a “not authorized” card. | [Admin guide](../admin-guide/index.html#publish-link) · Error shapes |
| 4 | **Ready handshake** | Enable controls on `{ type: 'configurator:ready' }`. Commands `{ action, payload, requestId }` in; `{ type: 'configurator:response', requestId, success, data \| error }` out. Write the helper once. | The helper |
| 5 | **Live price & state** | `price.changed` (`{ grandTotal, currency, … }`) drives the button; `option.selected`, `product.added` / `product.removed`, `selection.changed`, `layout.changed` keep a cart preview honest; `evaluate.rejected` = the engine refused a change. | Hearing the configurator |
| 6 | **Add to cart** | `getQuote` (itemised, engine-priced), `getConfiguration` (snapshot) — posted as the cart line’s price and properties. | Add-to-cart, complete |
| 7 | **The order record** | `project.saved` → `{ shareToken, shareUrl, pdfUrl }`; store `shareUrl` with the snapshot on the order line. No inbound command loads a snapshot — reopening is by share link. | Events · project.* |
| 8 | **Driving it from the store** | `setSceneOption` / `setProductOption` / `setLayout` from your own swatches (ids from `getOptionSets`); `hideUI`, `showUI`, `setUIRegions` to fit the page. | Their button → our option |
| 9 | **Origin lock** | On a page that mounts the SDK, `setAllowedOrigins(['https://shop.example.com'])`: unlisted origins are dropped, not answered. Unset stays open — the public-embed default. | Scope |
| 10 | **Errors** | `{ success: false, error }` under the same `requestId`; `evaluate.rejected`; the `error` event. Surface them. | Error shapes |
| 11 | **Content-Security-Policy** | Your store’s CSP allows the iframe origin in `frame-src`; the configurator host already permits framing. (The CSP inside the configurator is in the package README.) | Put it on the page |
#### Write the helper once
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-helper
Every command is one `postMessage` in and one reply out, matched by `requestId`. Wrap that in a promise once and the whole protocol becomes `await` -able:
```
// Ten lines you write once — every example below uses it.
// Posts a command into the iframe and resolves with that command's reply.
function callConfigurator(iframe, action, payload) {
return new Promise((resolve, reject) => {
const requestId = 'req-' + Math.random().toString(36).slice(2);
const onReply = (e) => {
const m = e.data;
if (m?.type !== 'configurator:response' || m.requestId !== requestId) return;
window.removeEventListener('message', onReply);
m.success ? resolve(m.data) : reject(new Error(m.error));
};
window.addEventListener('message', onReply);
iframe.contentWindow.postMessage({ action, payload, requestId }, '*');
});
}
```
#### Their button → our option
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-commands
`selectOption` is the flagship command — a fabric swatch, size button or finish picker in _your_ store UI selects the option inside the configurator, exactly as if the shopper had clicked our sidebar:
```
// Their swatch, our scene — by display name (ambiguous names are refused, not guessed):
await callConfigurator(iframe, 'selectOption', { optionSet: 'Fabric', option: 'Cognac' });
// By ids when your CMS stores them (exact — never ambiguous):
await callConfigurator(iframe, 'selectOption', { optionSetId: 41, optionId: 118 });
// success means the option resolved and was dispatched (same path as a sidebar
// click). A backend rule can still veto it a moment later — that arrives as an
// 'evaluate.rejected' event, so roll a cart line back on THAT, not on the reply.
```
#### Scene-wide vs one product
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-scope
`selectOption` routes like our own sidebar (scene-wide, or to the selected product). When you need to be explicit, two precise commands take over — and `setLayout` swaps the whole arrangement:
```
// Scene-wide: one finish for everything (what a "Finish" picker on the store page wants)
await callConfigurator(iframe, 'setSceneOption', { optionSetId: 41, optionId: 118 });
// One product only: needs the placementId — read them first, then target one
const products = await callConfigurator(iframe, 'getProductInstances');
const firstId = Object.keys(products)[0];
await callConfigurator(iframe, 'setProductOption',
{ placementId: firstId, optionSetId: 41, optionId: 119 });
// Swap the whole arrangement (an L-shaped / U-shaped picker on the store page):
await callConfigurator(iframe, 'setLayout', { layoutId: 'l_shaped' });
```
#### Reading what the shopper built
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-read
The `get*` commands are how the store page renders its own UI and its cart line — the catalog to build buttons from, the current picks to highlight them, the quote to charge from:
```
// Build the store page's own option buttons from the live catalog:
const sets = await callConfigurator(iframe, 'getOptionSets');
for (const set of Object.values(sets)) {
console.log(set.name, '→', set.options.map((o) => o.name).join(', '));
// "Fabric → Cognac, Slate, Oat" — render a button per option,
// wire each to selectOption with { optionSetId: set.id, optionId: o.id }
}
// What is picked right now (to preselect those buttons):
const { scene, placements } = await callConfigurator(iframe, 'getSelections');
// scene: { '41': 118, '42': 205 } — scene-wide picks
// placements: { 'p1': { '41': 119 }, … } — per-product picks
```
#### Camera & view
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-camera
Everything the scene toolbar does, the parent can do:
```
// Hide our UI and reset the framing, then bring the UI back:
await callConfigurator(iframe, 'setGuiVisible', { visible: false });
await callConfigurator(iframe, 'resetCamera');
await callConfigurator(iframe, 'setGuiVisible', { visible: true });
```
#### Hearing the configurator
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-events
Commands are request/reply; everything the shopper does _inside_ the iframe streams outward as `configurator:event` — no polling. The two you almost always want: `price.changed` (keep the price on your page live) and `configurator:ready` (enable your buttons).
```
window.addEventListener('message', (e) => {
const m = e.data;
if (m?.type === 'configurator:event' && m.event === 'price.changed')
updateCartPrice(m.data);
if (m?.type === 'configurator:ready') enableButtons();
});
```
#### The complete store page
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-cart
All of it together — live price, then quote + reopenable snapshot on “Add to cart”. This is the whole integration; there is no SDK on the store page:
```
```
#### The full protocol
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-protocol
The complete wire spec — every action with a runnable example (all use the helper above) and its real reply. Inbound envelope: `{ action, payload?, requestId? }` — `requestId` is echoed verbatim on the reply. All payload fields accept ids; the selection actions also accept display names.
##### Change the configuration
Same validated paths as our own sidebar — a backend rule can still veto after dispatch (watch `evaluate.rejected`).
`selectOption` select an option like a sidebar click — names or ids
```
// By display names (an ambiguous name is refused with candidates, never guessed):
await callConfigurator(iframe, 'selectOption', { optionSet: 'Fabric', option: 'Cognac' });
// By ids (exact — use these when your CMS stores them):
await callConfigurator(iframe, 'selectOption', { optionSetId: 41, optionId: 118 });
// → { applied: true } (throws: unknown / ambiguous / unavailable)
```
`setSceneOption` set a scene-wide option explicitly — every product that has the set follows
```
await callConfigurator(iframe, 'setSceneOption', { optionSetId: 41, optionId: 118 });
// → { optionSetId: 41, optionId: 118 }
```
`setProductOption` set an option on ONE placed product
```
// placementIds come from getProductInstances:
await callConfigurator(iframe, 'setProductOption',
{ placementId: 'p1', optionSetId: 41, optionId: 119 });
// → { placementId: 'p1', optionSetId: 41, optionId: 119 }
```
`setLayout` swap the whole arrangement — the engine rebuilds the scene
```
await callConfigurator(iframe, 'setLayout', { layoutId: 'l_shaped' }); // name or id
// → { layoutId: 'l_shaped' }
// expect product.added / product.removed events right after — the scene is rebuilt
```
`undo / redo` step the shopper's history — same stack as the toolbar buttons
```
await callConfigurator(iframe, 'undo'); // → { undone: true }
await callConfigurator(iframe, 'redo'); // → { redone: true }
```
##### Read the current state
All read-only — safe to call any time after `configurator:ready`.
`getQuote` the itemised, engine-priced bill — what "Add to cart" charges from
```
const quote = await callConfigurator(iframe, 'getQuote');
// → {
// quotedAt: '2026-09-02T10:14:03.512Z',
// system: { id: 12, name: 'Acme Living' },
// currency: 'USD',
// lines: [ { variant, quantity, unitPrice, lineTotal, selections, … }, … ],
// totals: { subtotal, grandTotal, grandTotalFormatted, … },
// scene: { … }, metadata: { … },
// }
addToCart(quote.lines, quote.totals.grandTotal);
```
`getSelections` every current pick — preselect your own option buttons from it
```
const { scene, placements } = await callConfigurator(iframe, 'getSelections');
// scene: { '41': 118, '42': 205 } — scene-wide picks (optionSetId → optionId)
// placements: { 'p1': { '41': 119 }, … } — per-product effective picks
```
`getOptionSets` the choosable catalog — build the store page's own pickers from it
```
const sets = await callConfigurator(iframe, 'getOptionSets');
// → { '41': { id: 41, name: 'Fabric', type: 'finish_change',
// options: [ { id: 118, name: 'Cognac', value: 'cognac' }, … ] }, … }
// type is the backend option-set type: 'finish_change' | 'product_change' |
// 'load_new_component' | 'load_new_product' | 'layout_change'
for (const set of Object.values(sets)) renderPicker(set.name, set.options);
```
`getProductInstances` every placed product — the source of placementIds for setProductOption
```
const products = await callConfigurator(iframe, 'getProductInstances');
// → { 'p1': { instanceId: 'p1', productId: 118, selections: { '41': 119 } }, … }
```
`getConfiguration` the full shareable snapshot — store it on the order line to reopen the exact build
```
const snapshot = await callConfigurator(iframe, 'getConfiguration');
orderLine.properties.configuration = snapshot; // opaque — store it whole, unmodified
```
`getSceneSelections` older scene-selection map — kept so existing parents keep working
```
// New code: use getSelections instead (it returns scene AND per-product picks).
const legacyMap = await callConfigurator(iframe, 'getSceneSelections');
```
##### Camera & view
Everything the scene toolbar does, the parent page can do.
`resetCamera` back to the default framing
```
await callConfigurator(iframe, 'resetCamera'); // → { reset: true }
```
`toggleView` switch 3D ↔ 2D plan view — the reply says which one you landed in
```
const { is3D } = await callConfigurator(iframe, 'toggleView');
viewButton.textContent = is3D ? 'See floor plan' : 'See in 3D';
```
`toggleWalls / toggleDimensions` show/hide the room walls, or the measurement callouts
```
await callConfigurator(iframe, 'toggleWalls'); // → { toggled: 'walls' }
await callConfigurator(iframe, 'toggleDimensions'); // → { toggled: 'dimensions' }
```
`setGuiVisible` hide/show the configurator's own UI — drive everything from your page
```
await callConfigurator(iframe, 'setGuiVisible', { visible: false });
// → { guiVisible: false }
await callConfigurator(iframe, 'setGuiVisible', { visible: true });
```
`hideUI / showUI` hide or restore individual parts of our interface — keep the scene, supply your own chrome
```
// Named regions. Both reply with the RESULTING flags, so you need not track them.
await callConfigurator(iframe, 'hideUI', { regions: ['sidebar', 'save'] });
// → { sidebar: false, header: true, toolbar: true, panels: true, chat: true,
// notifications: true, save: false, generateAssets: true, selection: true }
await callConfigurator(iframe, 'showUI', { regions: ['sidebar'] }); // one back
await callConfigurator(iframe, 'hideUI'); // no regions = canvas only
await callConfigurator(iframe, 'showUI'); // everything back
// An unknown region name is REFUSED (the reply is an error naming the valid ones),
// rather than quietly doing nothing.
```
`setUIRegions` set several regions at once — a partial merge, so what you do not name is left alone
```
await callConfigurator(iframe, 'setUIRegions', { sidebar: false, toolbar: true });
// → the full resulting flags, same shape as hideUI's reply
```
`getUIRegions` what is showing now, and every region name this build supports
```
const { regions, available } = await callConfigurator(iframe, 'getUIRegions');
// regions: { sidebar: true, header: true, … }
// available: ['sidebar','header','toolbar','panels','chat','notifications',
// 'save','generateAssets','selection']
// Build your own toggles from `available` rather than hardcoding the list —
// it grows, and a build that does not have a region will not lie about it.
```
#### Outbound messages
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-outbound
| Type | Shape | When |
| --- | --- | --- |
| `configurator:ready` | `{ type }` | Once, when the bridge starts listening — enable your buttons on it. |
| `configurator:response` | `{ type, requestId, success, data \| error }` | One per command; `requestId` echoed verbatim; `error` is always a string. |
| `configurator:event` | `{ type, event, data }` | Streams every SDK event (list below) plus any custom names your backend rules emit. |
Event names that stream on `configurator:event`:
`ready` `option.selected` `product.added` `product.removed`
`product.moved` `layout.changed` `selection.changed` `price.changed`
`evaluate.started` `evaluate.completed` `evaluate.rejected` `scene.ready` `project.saved` `assets.generated`
`error` `extension.failed`
A payload that can't be serialized arrives as `{ _unserializable: true }`, so the parent still learns the event fired.
#### Error shapes
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eb-errors
```
// Unknown action → the reply names every action it accepts:
{ type: 'configurator:response', requestId: 'r-7', success: false,
error: 'Unknown action: "addToCart". Available: selectOption, setSceneOption, setProductOption, setLayout, getOptionSets, …' }
// Refused selection (unknown / ambiguous / hidden option) — synchronous:
{ type: 'configurator:response', requestId: 'sel-1', success: false,
error: 'selectOption: not applied — unknown, ambiguous, or unavailable (see configurator console)' }
// Engine veto (a backend rule rejects it AFTER dispatch) — asynchronous, as an event:
{ type: 'configurator:event', event: 'evaluate.rejected',
data: { mutation: {…}, applied: false, rejected: true, resolvedState: null, warnings: [], pricing: null } }
```
React to the engine
### Events & rules
Permalink: https://configurator-platform.imagine.io/sdk/index.html#events
Guide
Prefer a walkthrough? Work with Custom Rules and Constraints.
Your page and the configurator are two separate worlds — the shopper changes the sofa, but _your_ cart, _your_ analytics, _your_ banners don't know. **Events are how the configurator tells your code what just happened**, so you can react. Think webhooks, but in the browser: you say which happenings you care about, and your function is called with the details.
Shopper picks
“Velvet” →
Engine validates
& re-prices →
Events fire
`option.selected` · `price.changed` →
Your code reacts
cart, analytics, UI
#### Start here: your first listener, in 30 seconds
Permalink: https://configurator-platform.imagine.io/sdk/index.html#ev-lifecycle
One import, one call: `on('event.name', yourFunction)`. The SDK calls your function every time that thing happens, handing it an object with the details (the “payload”). Here's the smallest useful example — a live price display outside the configurator:
```
import { on } from '@imagineio/configurator-sdk';
// "Whenever the price changes, run this function."
on('price.changed', (pricing) => {
// `pricing` is the payload — an object describing what happened.
document.querySelector('#my-price').textContent = pricing.grandTotal;
});
```
That's the whole mechanism. Everything below is the same call with different names and payloads.
#### Don't know which event you need? Log them all
Permalink: https://configurator-platform.imagine.io/sdk/index.html#ev-discover
The name `'*'` means _every_ event. Add this one line while developing, click around the configurator, and watch your console — you'll see each event's name and its exact payload as it fires. It's the fastest way to learn the vocabulary:
```
import { on } from '@imagineio/configurator-sdk';
// '*' handlers get (name, payload) — note the order, name first:
on('*', (name, payload) => console.log('[configurator]', name, payload));
// Now pick an option in the UI and the console shows, e.g.:
// [configurator] evaluate.started { mutation: {…} }
// [configurator] option.selected { optionSetId: 12, optionId: 45,
// optionSetName: 'Fabric', optionName: 'Velvet' }
// [configurator] evaluate.completed { mutation: {…}, applied: true, pricing: {…} }
// [configurator] price.changed { grandTotal: 2438, currency: 'USD', … }
```
#### Every built-in event, with a working starter
Permalink: https://configurator-platform.imagine.io/sdk/index.html#ev-list
Named handlers receive just the payload. `ready` and `scene.ready` are special: they _replay_ — subscribe after they already fired (a late-loading script) and your function still runs. Every other event is live-only.
| Event | Fires when | Starter |
| --- | --- | --- |
| `ready` | the SDK booted: catalog loaded, initial scene applied (replays) | `on('ready', () => enableCheckoutButton());` |
| `scene.ready` | the 3D scene is mounted and rendering (replays) | `on('scene.ready', () => hideMyOwnSplash());` |
| `project.saved` | a save completed — `{ project, shareToken, shareUrl, pdfUrl }` | `on('project.saved', ({ shareUrl }) => copyToClipboard(shareUrl));` |
| `assets.generated` | a render run settled — `{ assets, families }`, every requested asset complete or failed | `on('assets.generated', () => quote.open({ waitForImages: true }));` |
| `option.selected` | the shopper picked an option — `{ optionSetId, optionId, optionSetName, optionName }` | `on('option.selected', (p) => track(p.optionSetName, p.optionName));` |
| `product.added` | a product was placed in the scene — `{ variantId, productGraphId, placementIds }` | `on('product.added', (p) => console.log('placed', p.placementIds));` |
| `product.removed` | a placement was removed — `{ placementId }` | `on('product.removed', (p) => cart.removeLine(p.placementId));` |
| `product.moved` | a placement was reordered — `{ placementId, sequence }` | `on('product.moved', (p) => console.log(p.placementId, 'now at', p.sequence));` |
| `layout.changed` | a layout preset was applied — `{ presetId }` | `on('layout.changed', (p) => track('layout', p.presetId));` |
| `selection.changed` | the selected product changed — `{ placementId, componentId }`, both `null` on deselect | `on('selection.changed', (p) => showInspector(p.placementId));` |
| `price.changed` | pricing was recalculated — payload is the engine's pricing envelope | `on('price.changed', (p) => showTotal(p.grandTotal));` |
| `evaluate.started` | an engine round-trip began — `{ mutation, internal }` (`internal: true` for the SDK's own focus re-evaluate) | `on('evaluate.started', () => spinner.show());` |
| `evaluate.completed` | the engine answered — `{ mutation, internal, applied, resolvedState, pricing, warnings, code, errors }`; the same record is kept on `evaluation.last()` (see Rule & Constraint Evaluation) | `on('evaluate.completed', () => spinner.hide());` |
| `evaluate.rejected` | the engine _refused_ a change that already looked applied on screen — `{ mutation, applied: false, code, errors[] }` says which constraint and why | `on('evaluate.rejected', () => cart.rollback());` |
| `error` | an engine call failed — `{ op }` | `on('error', (p) => logError('engine call failed:', p.op));` |
| `extension.failed` | code a host registered (middleware) threw — `{ where, intent, message }` | `on('extension.failed', (p) => logWarn(p.where, p.message));` |
| `*` | every event — handler receives `(name, payload)`, name first | `on('*', (name, p) => analytics.track('imagine-cfg.' + name, p));` |
#### Stopping a listener, listening once, using React
Permalink: https://configurator-platform.imagine.io/sdk/index.html#ev-cleanup
Every `on()` call returns a function; call it to stop listening. `once()` auto-stops after the first firing. In React, returning that cleanup from `useEffect` is the entire integration:
```
import { on, once } from '@imagineio/configurator-sdk';
// on() RETURNS the "stop listening" function — keep it if you'll need it:
const stop = on('price.changed', (p) => showTotal(p.grandTotal));
stop(); // detached — the handler never runs again
// once() = run on the next firing only, then detach itself:
once('scene.ready', () => confetti());
// IN REACT: on()'s return value doubles as the useEffect cleanup — one line, no leaks:
useEffect(() => on('selection.changed', (p) => setSelected(p.placementId)), []);
```
#### Three complete recipes
Permalink: https://configurator-platform.imagine.io/sdk/index.html#ev-recipes
```
import { on, once, commerce } from '@imagineio/configurator-sdk';
// 1. KEEP A CART IN SYNC — the two subscriptions every store integration uses.
// Update optimistically on price.changed; undo if the engine later refuses:
on('price.changed', (pricing) => cart.update({ total: pricing.grandTotal }));
on('evaluate.rejected', () => cart.rollback());
// 2. RENDER A MINI-CART AS SOON AS THE CONFIGURATOR IS USABLE.
// Safe to call late — 'ready' replays to late subscribers:
once('ready', () => renderMiniCart(commerce.readBom().lines));
// 3. SHOW YOUR OWN "SAVING…" INDICATOR AROUND EVERY ENGINE ROUND-TRIP:
on('evaluate.started', () => statusBar.text('Checking with the engine…'));
on('evaluate.completed', () => statusBar.text('Saved'));
on('error', () => statusBar.text('Something went wrong — retry'));
```
#### Next: events your own team invents (rules)
Permalink: https://configurator-platform.imagine.io/sdk/index.html#ev-rules
The events above are built in. But your team can also define **rules** in the imagine.io admin — “when THIS is configured, do THAT” — and one of the things a rule can do is _fire a custom event with a payload you chose_. Your code subscribes with `onBackendEvent`. The win: the “when” lives in the admin, so business people can change it without a code release.
```
import { onBackendEvent, ui } from '@imagineio/configurator-sdk';
// Your handler always receives ONE object shaped like this:
// { ruleId: 41, // which admin rule fired it
// name: 'premium_fabric_chosen', // the name your team chose
// payload: { … }, // the data your team chose to send
// placementId: 'p3' } // which placed product triggered it (if any)
// Admin rule: "WHEN a premium fabric is selected → fire premium_fabric_chosen
// with { fabric, leadWeeks }"
onBackendEvent('premium_fabric_chosen', ({ payload }) => {
ui.notify({ type: 'warning', duration: 0,
message: `${payload.fabric} has a ${payload.leadWeeks}-week lead time` });
});
// Admin rule: "WHEN the total crosses $20,000 → fire high_value_config".
// Sales moves the threshold in the admin next quarter — this code never changes:
onBackendEvent('high_value_config', ({ payload }) => {
crm.createLead({ value: payload.grandTotal, config: location.href });
});
```
Good to know
**Register at boot** — events don't replay (only `ready` and `scene.ready` do). **A crashing handler hurts nothing** — it's logged and the others keep running. And **events can't veto**: by the time one fires, the change was already applied or refused — blocking a combination is a backend rule's job, not a listener's.
Every change, checked by the engine
### Rule & constraint evaluation
Permalink: https://configurator-platform.imagine.io/sdk/index.html#evaluation
Guide
Prefer a walkthrough? Work with Custom Rules and Constraints · Work with Placement Logic.
Every change a shopper makes — an option, a product added or moved, a layout, the room — is sent to the engine as one _mutation_ on `POST /evaluate/`. The engine applies your system's **rules** (when this, do that) and **constraints** (this is not allowed), and answers with an envelope: the resolved configuration, what is now hidden or unavailable, the price, messages, and any events or custom effects your rules emit — or a **422** with a code and the reasons. The SDK applies that answer itself: it repaints the scene, hides and greys options, updates the price, shows the messages, rolls back a rejected change. This section is about **reading** the same answer, so your code can react to it.
The short version, one page each: [how server-side constraint and rule evaluation works](https://configurator-platform.imagine.io/docs/concepts/server-side-constraint-and-rule-evaluation/index.html), [how a rule differs from a constraint](https://configurator-platform.imagine.io/docs/concepts/rules-vs-constraints/index.html), and the two responses besides 200: [409 catalog changed](https://configurator-platform.imagine.io/docs/errors/409-catalog-changed/index.html) and [422 rejected by a constraint](https://configurator-platform.imagine.io/docs/errors/422-rejected-by-constraint/index.html).
Where rules live
Rules and constraints are authored in the imagine.io admin and evaluated by the engine. The frontend never re-derives one — pricing and validity have exactly one source. What you get in the browser is the _result_, on every change, in three forms: push (`evaluate.*` events), pull (`evaluation.last()`), and React (`useEvaluation()`).
#### When an evaluation runs
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eval-when
One round-trip per mutation. The SDK paints optimistically, then reconciles with the engine's answer; a rejected mutation is rolled back. There is one round-trip the shopper does not cause: the **`noop` focus re-evaluate**, described in the table and below — the SDK re-asks the engine whenever the _selection_ changes, so focus-scoped rules run at selection time rather than on the next real change.
| `mutation.type` | What the shopper (or your code) did | Payload |
| --- | --- | --- |
| `selectSystemOption` | picked a scene-level option — `options.select(setId, optionId)`, the sidebar | `{ optionSetId, optionId }` |
| `selectOption` | picked an option on one piece | `{ placementId, optionSetId, optionId }` |
| `clearSystemSelection` / `clearSelection` | cleared a pick | `{ optionSetId }` / `{ placementId, optionSetId }` |
| `addPlacement` | `products.add`, a sidebar tile, a placement-target click | `{ productGraphId, variantId?, placementGroup, position?, sequence? }` |
| `removePlacement` / `movePlacement` / `setTransform` | delete, reorder, drag | `{ placementId, … }` |
| `changeVariant` | swapped a piece for another variant | `{ placementId, variantId }` |
| `applyPreset` / `setRoomDimensions` | a layout, the room | `{ presetId }` / `{ width, depth, height }` |
| `restoreState` | a saved design or share link opened | `{ savedState }` |
| `noop` | _nothing_ — the SDK's own background re-evaluate, fired ~120 ms after the selection changes (a piece or a component selected, or everything deselected). No state changes; the engine recomputes what depends on `context.focus` — option availability, overrides, messages for the focused piece | `{}` + `context.focus` |
Request — real sample from a live scene · what the SDK sends
```
{
"systemId": 2,
"catalogVersion": 939,
"mutation": {
"type": "selectSystemOption",
"optionSetId": 18,
"optionId": 160
},
"state": {
"…": "the full current state — room, selections, placements — so the engine is stateless"
}
}
```
##### `context.focus` and the `noop` re-evaluate
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eval-focus
Every mutation also carries **what is selected**, so the engine can apply focus-scoped rules (“when _this_ variant is selected, hide that option set”, a per-piece message): `context.focus = { placementId, variantId, componentId }` — the selected piece, its variant, and the selected component slot or `null` when the whole piece is the target. Nothing selected → no `context` at all.
Selection is not a mutation, so on its own it would never reach the engine, and a rule written against the focus would only fire on the shopper's _next_ change. The SDK closes that gap with the `noop` mutation: an empty change with the new focus attached, sent ~120 ms after the selection settles (rapid clicks collapse to one), and again on deselect so the engine clears focus-scoped availability. It behaves differently from everything else in the table, on purpose:
| A real mutation | The `noop` re-evaluate |
| --- | --- |
| announced on `evaluate.started` / `evaluate.completed` / `evaluate.rejected` | announced too — the same three events, flagged `internal: true` (and `mutation.type === 'noop'`); `evaluation.last()`, `history()`, `pending()` and `useEvaluation()` move as well, so a focus-scoped rule's answer is observable. Skip it in analytics with one check: `if (payload.internal) return;`. `price.changed` does not fire for it — the price did not change |
| shows the busy veil and freezes input | never — plain selection stays instant |
| a `422` rolls back the optimistic paint and toasts the reason | a `422` is ignored — it re-probes state, so a constraint the shopper did not just trigger is never surfaced |
| queued in order, nothing dropped | dropped when a real mutation is pending or in flight (that one already carries the current focus), and superseded by any real mutation that arrives while it waits |
Request — the focus re-evaluate · what the SDK sends after a piece is selected
```
{
"systemId": 2,
"catalogVersion": 939,
"mutation": {
"type": "noop",
"context": { "focus": { "placementId": "p_2", "variantId": 311, "componentId": null } }
},
"state": { "…": "unchanged" }
}
```
What this means for you
Rules that read the focus — hide an option set, grey an option, show a message for the selected piece — work at selection time with no code of yours; the result arrives in the same envelope and the SDK applies it as usual. If you watch `evaluate.*` to count changes, you are counting only real ones. An engine that does not understand `noop` answers `422`, which the SDK ignores; nothing else is affected.
#### The response, field by field
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eval-response
Every round-trip answers with one envelope. The columns: what a field _is_ (with its exact shape), _when_ it is present, what the SDK already does with it, and what is left for you. Everything below is on the record `evaluation.last()` returns and on the `evaluate.completed` / `evaluate.rejected` payload — the SDK normalises the raw body first (snake_case variants accepted, a `422` 's fields lifted out of `errorResponse` when the engine nests them), so what you read is always the shape shown here.
First, the status — it decides which fields you get
| HTTP | Meaning | Fields that matter | The SDK does |
| --- | --- | --- | --- |
| `200` | `applied: true` — the engine accepted the mutation and ran the cascade | `resolvedState`, `pricing`, the option maps, `messages` / `events` / `customEffects`, `addedPlacements` / `removedPlacements` | repaints from `resolvedState`, applies every effect, fires `evaluate.completed` then `price.changed` |
| `422` | `rejected: true` — a **constraint** refused it; nothing changed on the engine's side | `code`, `errors[]`, `blockingMutation`, `previousState`, often `messages[]` (a rule's explanation); `resolvedState` is `null` | rolls back the optimistic paint, keeps its current state, toasts `errors[0].message`, fires `evaluate.rejected` |
| `409` | `staleCatalog` — the client's `catalogVersion` is behind the engine's | `refetchCatalog: true`, `catalogVersion` (the current one) | refetches the catalog and retries the same mutation once with the fresh version — you never see the 409 |
Then the fields
| Field | What it is · shape | When | The SDK does | You can |
| --- | --- | --- | --- | --- |
| `applied` · `rejected` · `status` | the verdict as booleans, plus the raw HTTP status. Exactly one of the two booleans is true on any answer you see | always | branches everything below on them | treat `applied` as “the scene changed” and `rejected` as “show why” |
| `code` · `errors[]` | the constraint that refused: `code` is its id (`MAX_UNITS_EXCEEDED`, `INVALID_PLACEMENT_ID`, …); `errors[]` = `[{ code, message }]`, the first one being the human sentence | `422`; `null` / `[]` on `200` | toasts `errors[0].message` once, generically, for every mutation type; never for the `noop` re-evaluate | count rejections per `code`, roll back a cart line, replace our toast with your own copy — `on('evaluate.rejected')` carries both |
| `blockingMutation` · `previousState` | the engine's note on a refusal: whether it treated the mutation as hard-blocked, and the state it kept (the one before the attempt — same shape as `resolvedState`) | `422` only | exposes them; the SDK's own state already equals `previousState`, so nothing is repainted | diff `previousState` against what the shopper tried, for support tooling |
| `resolvedState` | the whole configuration _after_ the cascade — the truth the optimistic paint was guessing at. `{ systemId, room: { width, depth, height }, selections: { [optionSetId]: optionId }, placements: [...] }`. Each placement: `{ id, variantId, placementGroup, sequence, transform: { position[3], rotation[3] }, selections, effectiveSelections, bindings[], overrides, locked, lockVariantId, edge, variantName, productGraphName }` | `200`; `null` on `422` | replaces its state with it and repaints the scene from it; also the source of `useProducts()`, `scene.readBounds()` and what a saved design stores | mirror it to your own store; it is complete and stateless, so it is also what to send to your backend |
| `placements[].selections` · `effectiveSelections` | per piece: what the shopper picked on it (`selections`), and what applies after defaults and rules (`effectiveSelections`) — both `{ [optionSetId]: optionId }` | on every placement | `useOptionSets().getEffectiveSelection` reads the effective one for the focused piece | read `effectiveSelections` for a spec sheet; `selections` tells you which of those were the shopper's own picks |
| `placements[].bindings[]` | per piece, per option set the engine bound to it: `{ optionSetId, sequence, available: [optionId], default }` — _which options this piece may take_, in the order the panel should show them. An option set absent here is not offered on the piece at all | on every placement; `[]` for a piece with no product-level sets | narrows the product-level pickers to `available`; `productOptionSets` in `useOptionSets()` and `catalog.listProductOptionSets(id)` are built from it | explain a greyed tile: `evaluation.explainOption(setId, optionId, { placementId })` → `reason: 'not_available_on_placement'` |
| `placements[].overrides` | what rules changed on the piece, keyed by **slot name**: `componentSlots: { [slotName]: componentId \| null }` (a swapped part; `null` = the part unloaded), `visibility: { [slotName]: false }` (a hidden part), `materials: { [slotName]: materialRef }` (a finish a rule set), `transforms: { [slotName]: { position_delta?: [x, y, z], rotation?: [x, y, z], scale?: [x, y, z] } }` (metres added to the catalog position; rotation in degrees, absolute), and `optionSetAllowlist: [optionSetId]` (which option sets the piece shows at all) | on a placement a rule touched; otherwise `{}` | applies them to the 3D piece every render and keeps them across re-evaluations; a slot set to `null` is hidden; the allowlist filters the panel | read them for a spec sheet (“right arm removed by rule 31”) — they are the engine's record of what a rule did to the piece |
| `placements[].locked` · `lockVariantId` | a rule's `mark_locked` effect: the piece is frozen, optionally to one variant | when a rule locks it | no drag or rotate, its options cannot be changed, a banner says so | explain _why_ in your own UI — the rule's `messages[]` usually carries the reason |
| `optionVisibility` | `{ [optionSetId]: { [optionId]: false } }` — options a rule **hid**, system-wide (`hide_option`). Checked before availability | `200`; missing or `{}` = nothing hidden | removes them from every picker before render; `catalog.listOptions` and `useOptionSets().visibleOptions` exclude them | nothing — but `explainOption(...).reason === 'hidden_by_rule'` tells you why one is gone |
| `optionAvailability` | same shape, for options a rule **greyed** — shown, not selectable (`disable_option` at system scope; placement scope arrives as a narrowed `bindings[].available` instead) | `200`; missing = everything selectable | renders them disabled with a “Not available” reason; `optionDisabledPropsFor` reads it | your own tooltip or upsell (“available with the 900 base”) — `reason: 'disabled_by_rule'` |
| `defaultOptionOverrides` | `{ [optionSetId]: optionId }` — a rule changed a set's default | `200`, when a rule did | applies it wherever nothing was picked yet; the shopper's own picks win | — |
| `pricing` | the engine's numbers — the only ones that count. `{ currency, grandTotal, placements: { [placementId]: { basePrice, unitPrice, adjustments: [{ optionSetId, optionSetLabel, optionId, label, amount }] } }, aggregateAdjustments: [...] }`. `unitPrice` = `basePrice` + its adjustments; `grandTotal` = every `unitPrice` + the aggregate adjustments (scene-wide rules, bundles) | `200`; `null` on `422` — the price did not change | updates the price display, the selection panel's per-piece price and the quote; fires `price.changed` with this object | sync a cart line per `placementId`, log the delta, show an itemised breakdown from `adjustments[]` — it is already labelled for display |
| `messages[]` | a rule's `show_message`: `{ ruleId, text, severity: 'info' \| 'success' \| 'warning' \| 'error', display: 'toast' \| 'inline' \| 'modal', placementId? }` | `200` and `422` (a constraint's explanation), and on `/initial/`. Re-sent on every answer while the rule stays fired | `toast` and `inline` → the toast queue (info/success auto-dismiss after 5 s, warning/error stay until closed); `modal` → a blocking dialog, opened only when the message _newly_ appears, so it does not reopen after OK | route them to your own UI: read them here and register your own `NotificationContainer` / `Modal` to suppress ours |
| `events[]` | a rule _told_ you something (`emit_event`): `{ ruleId, name, payload, placementId? }` | when a rule emitted one | dispatches each to `onBackendEvent(name, fn)` subscribers, after the state is applied | open a popup, start a flow, notify your backend — the “when” lives in the admin |
| `customEffects[]` | a rule asked for something the SDK has no verb for: `{ ruleId, type, params, placementId? }` | when a rule used a custom effect type | dispatches each to `registerEffectHandler(type, fn)`; a type with no handler is dropped silently | implement the type — this is how a rule can drive _your_ feature |
| `customDiagnostics[]` · `warnings[]` | non-blocking notes. `customDiagnostics` (a rule's `warn` / `emit_info`) have the `messages[]` shape; `warnings` are the engine's own (`{ code, message }` or a string) | either status | diagnostics → the message dispatcher (toasts); warnings → the console in dev. Two engine-internal codes (`CONSTRAINT_NOT_IMPLEMENTED`, `STALE_SELECTION`) are dropped at the source and never reach you | surface warnings your own way — they are on the record |
| `addedPlacements[]` · `removedPlacements[]` | pieces the engine added or removed as a _consequence_ of the mutation, not as the mutation: `[{ id, variantId, productGraphId, reason, constraintId }]`. `reason` says why — a mutually-exclusive replace, a preset's max-count trim, an anchor auto-loaded for a hosted piece | `200`, when the cascade changed the piece list | paints / removes them and fires `product.added` / `product.removed` for each, so your listeners see them like any add or delete | keep an external cart in step without diffing the placement list yourself |
| `catalogVersion` · `refetchCatalog` · `schemaVersion` | the catalog version the engine used; `true` when the client's copy is stale (the `409` in disguise); the envelope schema version | always | refetches the catalog and retries once when stale; sends `catalogVersion` back on the next request | — |
| `placementBoundsExclude` | `{ componentIds: [...] }` — components that do not count toward a piece's placement footprint (a protruding handle, a decorative trim) though they are still drawn | when the system defines any | feeds the placement strategy, so pieces butt up against the body, not the trim | — |
| `system` | the system envelope (`id`, `name`, `uiToggles`, …) when the engine echoes it | optional | surfaces it so backend-driven UI gating can refresh from an evaluate too | read `uiToggles` if a rule of yours flips chrome at runtime |
Reading order that avoids mistakes
Check `applied` first — on a `422` every field that describes the configuration is `null`, and reading `pricing.grandTotal` there throws. Treat `resolvedState` as the only state and the optimistic paint as a guess it confirms or corrects. Treat `pricing` as the only price; never sum catalog prices yourself. And read effects from the response, not from the rule definitions: `messages`, `events`, `customEffects` and the overrides are the engine's record of what actually fired for this exact state.
Response — real sample from a live scene · `200` after `selectSystemOption`; arrays trimmed
```
{
"schemaVersion": 1,
"catalogVersion": 939,
"refetchCatalog": false,
"resolvedState": {
"systemId": 2,
"room": {
"width": 4,
"depth": 3.5,
"height": 2.7
},
"selections": {
"16": 179,
"18": 160,
"19": 181,
"20": 188
},
"placements": [
{
"id": "p1",
"variantId": 86,
"placementGroup": "floor",
"sequence": 0,
"transform": {
"position": [
0,
0,
0
],
"rotation": [
0,
0,
0
]
},
"selections": {},
"overrides": {
"componentSlots": {
"leg_left_front": 355,
"leg_left_back": 355,
"leg_right_front": 355,
"leg_right_back": 355
},
"visibility": {
"arm_right": false
}
},
"bindings": [],
"effectiveSelections": {},
"edge": "left",
"variantName": "Anne End Module Left — Default",
"productGraphName": "Anne"
},
// … 4 more placements like the one above
]
},
"optionVisibility": {},
"optionAvailability": {},
"pricing": {
"currency": "USD",
"grandTotal": 8495,
"placements": {
"p1": {
"basePrice": 1299,
"adjustments": [
{
"optionSetId": 16,
"optionSetLabel": "Sofa Layouts",
"optionId": 179,
"label": "Oppsett F",
"amount": 0
},
{
"optionSetId": 19,
"optionSetLabel": "Arm Style",
"optionId": 181,
"label": "Anne Arm 1",
"amount": 0
}
],
"unitPrice": 1649
}
},
"aggregateAdjustments": []
},
"errors": [],
"warnings": [],
"placementBoundsExclude": {
"componentIds": []
}
}
```
Response — a rejection · `422` when a constraint refuses the mutation
```
{
"code": "MAX_UNITS_EXCEEDED",
"errors": [
{
"code": "MAX_UNITS_EXCEEDED",
"message": "A run may hold at most 6 units."
}
],
"blockingMutation": false,
"messages": []
}
```
#### Reading it
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eval-read
Three forms of the same record. Push when something should happen at the moment of the answer; pull when a component or a console session wants the latest; React when a component should re-render with it.
```
import { on, evaluation, useEvaluation } from '@imagineio/configurator-sdk';
// PUSH — at the moment of the answer. `applied` false + `code` = a constraint said no.
on('evaluate.completed', ({ mutation, resolvedState, pricing, messages }) => track('configured', { type: mutation.type, total: pricing?.grandTotal }));
on('evaluate.rejected', ({ mutation, code, errors }) => track('constraint_hit', { type: mutation.type, code, message: errors[0]?.message }));
// PULL — the last answer, any time. In the console this is how you debug a rule.
const last = evaluation.last(); // null before the first evaluation
last.kind; // 'completed' | 'rejected'
last.mutation.type; // 'selectSystemOption'
last.optionVisibility; // what the rules hid, after this change
last.durationMs; // how long the engine took
evaluation.history(); // the last 20, newest first
evaluation.pending(); // true while a round-trip is in flight — a busy indicator
// WHY is this option not offered? The engine's answer, not a guess.
evaluation.explainOption(10, 102); // { visible: false, available: false, selectable: false, reason: 'hidden_by_rule' }
evaluation.explainOption(5, 151, { placementId: 'p1' }); // reason: 'not_available_on_placement' — the piece's bindings exclude it
// REACT — re-renders on every evaluation.
function EngineStatus() {
const { last, pending } = useEvaluation();
if (pending) return Checking…;
if (last?.rejected) return {last.errors[0]?.message};
return {last?.pricing?.grandTotal};
}
```
Three things to know
**The engine is the authority.** Never recompute a price, a visibility or a validity locally from the catalog; read it here. **A rejection is not an error.** A 422 is the engine doing its job — the SDK rolls back and tells the shopper; your listener gets `code` to decide what else should happen. **The SDK's own focus re-evaluations are announced too** (a selection with no state change — `mutation.type === 'noop'`), flagged `internal: true`; a listener that only wants real changes checks that flag.
#### Reference — everything this section used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#eval-ref
| Function | What it does |
| --- | --- |
| evaluation.last() | the last record, or null |
| evaluation.history() | the last 20, newest first |
| evaluation.pending() | a round-trip is in flight |
| evaluation.subscribe(fn) | every new record, outside React |
| evaluation.explainOption(setId, optionId, { placementId? }) | why an option is / is not offered |
| useEvaluation() | React: `{ last, history, pending }` |
| on('evaluate.completed' \| 'evaluate.rejected' \| 'evaluate.started', fn) | the push form |
| onBackendEvent(name, fn) · registerEffectHandler(type, fn) | where `events[]` and `customEffects[]` are delivered |
Step by step
### Guides
Permalink: https://configurator-platform.imagine.io/sdk/index.html#guides
Twelve walkthroughs. Each starts from a running configurator, changes one thing end to end, and closes with a reference of every function it used. Read the one you need — none depends on another.
Customize Theme & Layout Change one token, build a whole theme, replace the layout, or bring your own option panel.
Override Button Functionality Add to or replace what the built-in buttons do.
Add a Custom Button A button that changes the 3D scene or opens your own UI, and where it can go.
Add Custom 3D Functionality Move objects, load your own object into the scene, animate it.
Customize or Create Quote Templates Your own quote or bill-of-materials document.
Integrate with E-Commerce Platforms Run inside a storefront and hand the configuration to its cart.
Add Custom Popups Your own dialogs, opened from SDK events and buttons.
Integrate Custom APIs Call your services from inside the configurator.
Work with Custom Rules and Constraints React to what the engine allows, blocks and prices.
Work with Placement Logic Where a piece may go, and your own placement strategies.
Customize the Loading Screen Your brand on screen while the scene loads.
Adding Custom Dimension Code Your own measurements and labels in the scene.
Guide
### Customize Theme & Layout
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-theme-layout
This guide
Puts the scene full-screen with floating controls, changes different parts of the theme, builds a complete new theme from those parts, and replaces the whole page layout — and shows how a custom option panel keeps _system-level_ option sets and the _selected product's_ option sets apart, so a UI you design can never mix them up.
Change the overall theme or customize individual parts of the configurator, including its layout.
Every example below is verified against the SDK as shipped. Each example is independent — do only the ones you need, in any order. The one rule that applies to all of them: **your call wins**. Anything you apply from app code outranks the backend's theme, and re-applying replaces rather than stacks.
#### Example 1 — Full-screen scene with floating controls
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-theme-5
A layout need not keep the shape of the default shell. Here the 3D scene fills the viewport and every control floats above it: a rail of categories down one edge, one flyout open at a time, and the selected piece's own options in a card on the opposite side.
Two things follow. An arrangement like this is **not reachable by restyling `parts.Sidebar`**, which renders every option set in one vertical list, so the panel is built on the headless hooks instead (Customise the UI › Headless). And once you own the panel, **the two levels of option set become the layout itself**: the scene's own sets in the rail, the selected piece's sets in the card. Different place, different colour, so the two can never be mistaken for one another.
One file, or several
Everything below is **one file** — shell, option UI and CSS — so it can be pasted into a project and run as it stands. The CSS is a template literal in a ` ` tag inside the component, which keeps the layout self-contained; a plain `.css` file imported alongside works just as well. Split it into as many modules as suits your project — `registerLayout` only ever receives the finished component.
Two things a headless shell must get right
**Subscribe before you resolve.** Call `useComponentRegistry()` immediately before `ui.resolveComponent`. Without it, a component registered _after_ mount will not re-render inside your shell: the resolve ran once and nothing asked React to run it again.
**Replace `SelectionActionPanel` when your shell has its own.** The built-in pill carries the same price, move, duplicate and delete; mounted alongside a panel of yours, every action appears twice.
```
import { useMemo, useState } from 'react';
import {
parts, ui,
useBootStatus, useComponentRegistry, useGenerateAssets, useOptionSets, usePrice,
useProduct, useSelection, useSelectionActions, useSystem, useToolbar,
} from '@imagineio/configurator-sdk';
/* ───────────────────────────── styles ─────────────────────────────────────
Inlined so the layout is one file. This palette is its own rather than the
theme record's, because translucent panels over a live 3D render need their
own opacity and shadow scale. */
const CSS = `
.sx { --ink:#1F1D1A; --soft:#6B665D; --accent:#7A4A2B; --accent-lit:#C98F5E; --ivory:#FFFDF8;
--glass:rgba(255,253,248,.84); --line:rgba(31,29,26,.10);
--shadow:0 18px 44px -14px rgba(31,29,26,.34), 0 2px 6px -2px rgba(31,29,26,.12);
--dark:rgba(28,26,23,.90); --dark-line:rgba(255,253,248,.14);
--blur:saturate(160%) blur(20px);
position:absolute; inset:0; overflow:hidden; color:var(--ink);
background:var(--color-background,#f4f1ea);
font-family:"Public Sans",system-ui,-apple-system,sans-serif; }
/* The scene is the page. */
.sx__stage { position:absolute; inset:0; overflow:hidden; }
/* One overlay plane; transparent to the pointer so the scene stays draggable. */
.sx__over { position:absolute; inset:0; z-index:2; pointer-events:none; }
.sx__over > * { pointer-events:auto; }
.sx-glass { background:var(--glass); -webkit-backdrop-filter:var(--blur); backdrop-filter:var(--blur);
border:1px solid var(--line); box-shadow:var(--shadow); }
.sx-top { position:absolute; top:16px; left:16px; right:16px; display:flex;
align-items:flex-start; justify-content:space-between; gap:12px; pointer-events:none; }
.sx-top > * { pointer-events:auto; }
.sx-bar { display:flex; align-items:center; gap:12px; padding:10px 18px; border-radius:999px; }
.sx-mark { font-family:"Fraunces",Georgia,serif; font-weight:600; font-size:15px;
letter-spacing:.22em; color:var(--accent); }
.sx-sys { font-size:13px; font-weight:500; color:var(--soft); }
.sx-actions { display:flex; align-items:center; gap:10px; padding:8px 10px 8px 18px; border-radius:999px; }
.sx-total { display:flex; flex-direction:column; align-items:flex-end; line-height:1.1; margin-right:4px; }
.sx-total b { font-family:"Fraunces",Georgia,serif; font-size:19px; font-weight:600; font-variant-numeric:tabular-nums; }
.sx-total span { font-size:9px; letter-spacing:.18em; text-transform:uppercase; color:var(--soft); }
.sx-btn { display:inline-flex; align-items:center; gap:7px; height:36px; padding:0 16px;
border-radius:999px; border:1px solid var(--line); background:rgba(255,253,248,.7);
color:var(--ink); font:inherit; font-size:13px; font-weight:600; white-space:nowrap; cursor:pointer; }
.sx-btn:disabled { opacity:.45; cursor:default; }
.sx-btn svg { width:15px; height:15px; flex:0 0 auto; }
.sx-btn--primary { background:var(--accent); border-color:var(--accent); color:var(--ivory); }
/* Category rail — each face is the CURRENT choice, so the rail is also a summary. */
.sx-rail { position:absolute; left:16px; top:50%; transform:translateY(-50%); display:flex;
flex-direction:column; gap:8px; max-height:calc(100vh - 200px); overflow-y:auto; padding:8px;
border-radius:22px; scrollbar-width:none; }
.sx-rail::-webkit-scrollbar { display:none; }
.sx-rail button { position:relative; display:block; width:46px; height:46px; flex:0 0 auto;
padding:3px; border:0; border-radius:14px; background:transparent; cursor:pointer;
box-shadow:inset 0 0 0 2px transparent; transition:box-shadow .15s ease; }
.sx-rail button:hover { box-shadow:inset 0 0 0 2px rgba(31,29,26,.18); }
.sx-rail button[data-open] { box-shadow:inset 0 0 0 2px var(--accent); }
.sx-face { display:grid; place-items:center; width:100%; height:100%; border-radius:11px;
background-color:#EDE7DC; background-size:contain; background-repeat:no-repeat;
background-position:center; overflow:hidden; font-size:11px; font-weight:700; color:var(--soft); }
.sx-tip { position:absolute; left:calc(100% + 10px); top:50%; transform:translateY(-50%);
padding:5px 11px; border-radius:999px; background:var(--dark); color:var(--ivory); font-size:11px;
font-weight:600; letter-spacing:.06em; text-transform:uppercase; white-space:nowrap;
opacity:0; pointer-events:none; transition:opacity .12s ease; }
.sx-rail button:hover .sx-tip, .sx-rail button:focus-visible .sx-tip { opacity:1; }
/* One category open at a time — progressive disclosure, not one long list. */
.sx-fly { position:absolute; left:90px; top:50%; transform:translateY(-50%); width:330px;
max-width:calc(100vw - 120px); max-height:min(70vh,620px); display:flex; flex-direction:column;
border-radius:16px; }
.sx-fly__head { display:flex; align-items:flex-start; justify-content:space-between; gap:10px;
padding:14px 14px 10px 18px; border-bottom:1px solid var(--line); }
.sx-fly__head h2 { margin:0; font-size:10px; font-weight:700; letter-spacing:.18em;
text-transform:uppercase; color:var(--soft); }
.sx-fly__head p { margin:3px 0 0; font-family:"Fraunces",Georgia,serif; font-size:17px; font-weight:600; }
.sx-fly__body { overflow-y:auto; padding:14px 18px 18px; }
.sx-x { flex:0 0 auto; width:28px; height:28px; border:1px solid var(--line); border-radius:50%;
background:transparent; color:var(--soft); font-size:17px; line-height:1; cursor:pointer; }
.sx-swatches { display:grid; grid-template-columns:repeat(auto-fill,minmax(84px,1fr)); gap:10px; }
.sx-sw { display:flex; flex-direction:column; gap:6px; padding:0; border:0; background:none;
color:inherit; font:inherit; text-align:left; cursor:pointer; }
.sx-sw:disabled { opacity:.35; cursor:not-allowed; }
.sx-sw i { display:grid; place-items:center; aspect-ratio:1; border-radius:10px;
background-color:#EDE7DC; background-size:cover; background-position:center;
box-shadow:inset 0 0 0 1px var(--line); font-style:normal; font-size:12px;
font-weight:700; color:var(--soft); }
.sx-sw[data-on] i { box-shadow:inset 0 0 0 2px var(--accent); }
.sx-sw em { font-style:normal; font-size:11px; line-height:1.3; color:var(--soft); }
.sx-sw[data-on] em { color:var(--ink); font-weight:600; }
.sx-sw--dark i { background-color:#3A352E; box-shadow:inset 0 0 0 1px var(--dark-line); color:rgba(255,253,248,.6); }
.sx-sw--dark[data-on] i { box-shadow:inset 0 0 0 2px var(--accent-lit); }
.sx-sw--dark em { color:rgba(255,253,248,.62); }
.sx-sw--dark[data-on] em { color:var(--ivory); }
/* The selected piece — opposite corner, opposite colour. Impossible to confuse. */
.sx-insp { position:absolute; right:16px; bottom:92px; width:330px; max-width:calc(100vw - 32px);
max-height:min(62vh,560px); display:flex; flex-direction:column; background:var(--dark);
-webkit-backdrop-filter:var(--blur); backdrop-filter:var(--blur);
border:1px solid var(--dark-line); border-radius:16px; color:var(--ivory);
box-shadow:0 20px 48px -14px rgba(0,0,0,.55); }
.sx-insp__head { display:flex; align-items:flex-start; justify-content:space-between; gap:12px;
padding:15px 18px 12px; border-bottom:1px solid var(--dark-line); }
.sx-insp__head span { font-size:9px; font-weight:700; letter-spacing:.2em;
text-transform:uppercase; color:var(--accent-lit); }
.sx-insp__head h2 { margin:3px 0 0; font-family:"Fraunces",Georgia,serif; font-size:17px;
font-weight:600; line-height:1.25; }
.sx-insp__head b { flex:0 0 auto; font-family:"Fraunces",Georgia,serif; font-size:16px;
font-weight:600; font-variant-numeric:tabular-nums; }
.sx-insp__body { overflow-y:auto; padding:14px 18px; }
.sx-insp__body section + section { margin-top:16px; }
.sx-insp__body h3 { margin:0 0 9px; font-size:9px; font-weight:700; letter-spacing:.18em;
text-transform:uppercase; color:rgba(255,253,248,.5); }
.sx-insp__acts { display:flex; flex-wrap:wrap; gap:6px; padding:12px 18px 15px;
border-top:1px solid var(--dark-line); }
.sx-pill { height:30px; padding:0 12px; border-radius:999px; border:1px solid var(--dark-line);
background:transparent; color:var(--ivory); font:inherit; font-size:12px; font-weight:600; cursor:pointer; }
.sx-pill:disabled { opacity:.35; cursor:default; }
.sx-pill--rm { margin-left:auto; color:#E9A08A; border-color:rgba(233,160,138,.4); }
.sx-dock { position:absolute; bottom:18px; left:50%; transform:translateX(-50%); display:flex;
align-items:center; gap:4px; padding:7px 8px; border-radius:999px;
max-width:calc(100vw - 32px); overflow-x:auto; scrollbar-width:none; }
.sx-dock::-webkit-scrollbar { display:none; }
.sx-dock button { min-width:36px; height:36px; padding:0 10px; border:0; border-radius:999px;
background:transparent; color:var(--ink); font:inherit; font-size:13px; font-weight:600; cursor:pointer; }
.sx-dock button:hover:not(:disabled) { background:rgba(31,29,26,.08); }
.sx-dock button:disabled { opacity:.3; cursor:default; }
.sx-dock button[data-on] { background:var(--accent); color:var(--ivory); }
.sx-dock hr { width:1px; height:20px; border:0; background:var(--line); margin:0 4px; }
.sx-empty { font-size:12px; color:var(--soft); margin:0; }
@media (max-width:820px) {
.sx-top { top:10px; left:10px; right:10px; flex-wrap:wrap; gap:8px; }
.sx-actions { margin-left:auto; }
.sx-rail { left:10px; right:10px; top:auto; bottom:74px; transform:none; flex-direction:row;
max-height:none; overflow-x:auto; overflow-y:hidden; }
.sx-tip { display:none; }
.sx-fly, .sx-insp { left:10px; right:10px; top:auto; bottom:142px; width:auto;
max-width:none; max-height:44vh; transform:none; }
.sx-fly:has(~ .sx-insp) { display:none; }
.sx-dock { bottom:12px; }
}
`;
/* ───────────────────────────── helpers ─────────────────────────────────── */
const initials = (s) => String(s || '?').trim().slice(0, 2).toUpperCase();
// Every price in the shell goes through here, so the top bar and the card can never
// disagree. Cents appear only when a price actually has them.
function money(n) {
if (n == null || !Number.isFinite(Number(n))) return '—';
try {
return new Intl.NumberFormat(ui.getLocale(), {
style: 'currency', currency: ui.getCurrency() || 'USD',
minimumFractionDigits: 0, maximumFractionDigits: 2,
}).format(Number(n));
} catch { return ui.formatMoney(Number(n)); }
}
// Finish swatches: option.value is the material id.
const materialFor = (o, option) =>
(option && (o.materials?.[option.value] ?? o.materials?.[String(option.value)])) || null;
function face(option, material) {
const image = option?.thumbnail || material?.thumbnail || material?.textures?.diffuse || null;
const colour = material?.color || null;
return {
style: {
backgroundImage: image ? `url(${image})` : undefined,
backgroundColor: !image && colour ? colour : undefined,
},
bare: !image && !colour,
};
}
function Swatches({ set, o, dark }) {
const options = o.visibleOptions(set.id, o.getOptionsForSet(set) || []);
const chosen = o.getEffectiveSelection(set.id);
if (options.length === 0) return
No options available.
;
return (
{options.map((opt) => {
const material = materialFor(o, opt);
const f = face(opt, material);
const d = o.optionDisabledPropsFor(set.id, opt) || {};
const on = String(opt.id) === String(chosen);
return (
);
})}
);
}
/* ── scene-level: the rail and its flyout ───────────────────────────────── */
function SceneOptions() {
// PINNED to scene scope: these must not change when a piece is selected.
const o = useOptionSets({ placementId: null });
const sets = o.sceneOptionSets ?? [];
const [openId, setOpenId] = useState(null);
if (sets.length === 0) return null;
// Derived, never synced back into state: if a layout change rebuilds the sets,
// the lookup yields null and the flyout closes itself.
const open = sets.find((s) => String(s.id) === String(openId)) ?? null;
const chosenFor = (set) => {
const id = o.getEffectiveSelection(set.id);
return (o.getOptionsForSet(set) || []).find((x) => String(x.id) === String(id)) ?? null;
};
return (
<>
{open && (
{open.name}
{chosenFor(open)?.name ?? 'Not set'}
)}
>
);
}
/* ── product-level: the selected piece ──────────────────────────────────── */
function Inspector() {
// No argument: this scope FOLLOWS the selection, so reads and writes land on that piece.
const o = useOptionSets();
const { placementId } = useSelection();
const { panelActions, priceInfo } = useSelectionActions();
const piece = useProduct(placementId);
if (!placementId) return null;
const sets = o.productOptionSets ?? [];
const off = panelActions?.disabledActions ?? {};
return (
);
}
/* ── the shell ──────────────────────────────────────────────────────────── */
export default function StudioLayout({ Scene }) {
const t = useToolbar();
const { name } = useSystem();
const { grandTotal } = usePrice();
const { loading } = useBootStatus();
const { handleGenerateAssets, isGenerating } = useGenerateAssets();
const busy = t.isLayoutLoading || loading;
// Subscribe to the override registry, THEN resolve. Without the subscription an
// override registered after mount never re-renders here.
const version = useComponentRegistry();
const { Save, Generate } = useMemo(() => ({
version,
Save: ui.resolveComponent('SaveProjectButton', parts.SaveProjectButton),
Generate: ui.resolveComponent('GenerateAssetsButton', parts.GenerateAssetsButton),
}), [version]);
return (
{/* The scene is the page — this box is what the canvas fills. */}
{/* Mount these or the buttons look right and do nothing. */}
);
}
/* ── register ───────────────────────────────────────────────────────────── */
// Register over the ACTIVE key, or force one as here. Registering 'default' while the
// backend has selected another shell succeeds and changes nothing.
ui.registerLayout('studio', StudioLayout);
ui.setLayout('studio');
// The built-in floating pill carries the same price / move / delete the Inspector shows,
// so leaving it mounted would show every action twice.
ui.registerComponent('SelectionActionPanel', () => null);
```
Check it
The canvas is the full viewport — no letterboxing, and the page never scrolls. The rail shows one tile per scene-level set, each wearing the swatch of what is currently chosen, so it doubles as a summary of the specification; hovering a tile names it. Clicking one opens the flyout beside it and clicking it again closes it. **Click a product in the scene** and the dark card appears with that piece's own sets, its unit price and its actions — and nothing in the rail changes, which is the `{ placementId: null }` pin doing its job. Click empty floor and the card disappears. In the dock, `2D` flips the view and its own label, and undo and redo grey out correctly at the ends of the history.
#### Example 2 — Change one part of the theme
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-theme-1
Pass a record with only the fields you want to change. Everything you leave out keeps its default. The record shape is `config.{ colors, sizing, typography, buttons }` — a free-form `tokens: {…}` object is silently ignored, which is worth knowing because the symptom is “my theme did nothing” with no error.
```
import { ui } from '@imagineio/configurator-sdk';
// Just the brand colour. Hover and light shades derive from it; every surface that reads
// the brand family (header, dialogs, PDF accents) follows.
ui.applyTheme({ name: 'acme', config: { colors: { primary: '#b45309' } } });
// Just the typography.
ui.applyTheme({ name: 'acme', config: {
typography: { fontFamily: '"Inter", "Inter Fallback", sans-serif', baseSize: 14, labelSize: 11, fontWeight: 600 },
}});
// Just the shape of things: square corners, tighter tiles, flat buttons.
ui.applyTheme({ name: 'acme', config: {
sizing: { radius: 2, gap: 8, cardWidth: 360 },
buttons: { buttonRadius: 2, shadow: 'none', buttonStyle: 'filled' },
}});
```
Check it
Open DevTools → Elements → ` `. Your values appear as inline custom properties (`--color-primary`, `--font-family-base`, `--radius-xl` …). If a value you passed is missing, the console will have told you why — a malformed colour, an unknown key — `applyTheme` validates and reports rather than failing silently.
Every variable it writes — and what each derives from — is listed in the derived-token table. You need that list only for CSS-level theming; a record gets all of them written for you.
#### Example 3 — Build a complete new theme
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-theme-2
A full theme is three layers, each doing what the one below cannot: the **record** for everything the schema names; **CSS on `data-part`** for what it does not (letter-spacing, a rule under a heading); and **labels** for wording. `surface` is the field people miss — set only `background` and every card and dialog stays white on your tinted page.
```
import { ui } from '@imagineio/configurator-sdk';
const BRAND = { ink: '#1c1917', paper: '#f5efe6', cream: '#fdfaf2', accent: '#b45309', font: '"Cormorant Garamond", Georgia, serif' };
// 1. The record — every token the schema names.
ui.applyTheme({
name: 'nordhus',
config: {
colors: {
primary: BRAND.accent, text: BRAND.ink, textMuted: '#78716c',
background: BRAND.paper,
surface: BRAND.cream, // cream, not white — what cards and dialogs read
border: '#e3dccd',
},
sizing: { radius: 2, gap: 8 },
typography: { fontFamily: BRAND.font, fontWeight: 600, labelSize: 10 },
buttons: { buttonRadius: 2, shadow: 'none', buttonStyle: 'filled' },
},
});
// 2. CSS for what tokens cannot say. Written against data-part — the published contract —
// never against our class names, which are implementation and may change.
ui.applyCustomCss(`
[data-part="option-set/title"] { letter-spacing: .18em; text-transform: uppercase; }
[data-part="option-set/title"]::after { content: ''; display: block; height: 1px; background: currentColor; opacity: .25; margin-top: 6px; }
[data-part="option-card"] { border-width: 1px; }
`);
// 3. Wording. Merged, not replaced — it coexists with an admin's translation. Use the keys
// from the label table (`save.label`, `generate.label`, …): an unknown key is silently ignored.
ui.setLabels({ 'save.label': 'Save my design', 'generate.label': 'Get images' });
```
Where to call it
Anywhere in your app code — before `mount()` or after. The backend's own theme is applied during boot and again when the shell mounts, and both yield to a theme you applied. Two things to know: a record **named** after a numbered preset (`'Theme 3'`) also selects that preset's palette; and a record's `name` chooses the page shell (`'Theme 2'` → wizard, `'Theme 3'` → showroom, `'Theme 4'` → showcase) — any other name keeps the default shell. To pick a shell independently of the name, set `layout: 'wizard'` on the record. Full detail in Theme tokens. If a rule seems to do nothing, look at the console: `applyCustomCss` warns when a `data-part` name matches nothing in the UI — the valid names are the ones in the data-part table under _Customise the UI_.
To take it all off: `ui.applyTheme(null)` and `ui.applyCustomCss('')`. Every derived token returns to the stylesheet default — a theme cannot outlive itself.
#### Example 4 — Replace the whole layout
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-theme-3
A layout is a React component that receives `Scene` and composes the page from `parts.*`. It owns _where_ things sit; every part keeps its own behaviour — Save still opens the save dialog, Generate still runs the pipeline. Register it over the key the backend has selected, or it will never be the one resolved.
```
import React from 'react';
import { ui, parts, quote, useGenerateAssets, useToolbar } from '@imagineio/configurator-sdk';
function BrandShell({ Scene }) {
const { isLayoutLoading } = useToolbar();
// The generate pipeline as a hook — screenshots, upload, progress. You place the button;
// you do not reimplement any of that.
const { handleGenerateAssets, isGenerating } = useGenerateAssets();
// SUBSCRIBE, then resolve. Resolving alone honours an override registered BEFORE mount and
// silently ignores every later one — nothing asks React to resolve again. The version this
// returns changes on each registration, so it is the memo’s dependency.
const version = useComponentRegistry();
const { Save, Generate, Toolbar } = useMemo(() => ({
version,
Save: ui.resolveComponent('SaveProjectButton', parts.SaveProjectButton),
Generate: ui.resolveComponent('GenerateAssetsButton', parts.GenerateAssetsButton),
Toolbar: ui.resolveComponent('SceneToolbar', parts.SceneToolbar),
}), [version]);
return (
NORDHUS
{/* minHeight: 0 — or the scene row grows past the page */}
{/* a COMPONENT — never {Scene} */}
{/* our toasts, positioned by you */}
{/* The four things a shell must mount, or buttons look right and do nothing: */}
{/* save / export / AR / generated-assets dialogs */}
{/* ui.registerModal content */}
{/* ui.registerSlot content */}
);
}
// Over the ACTIVE key. The backend may have selected 'showroom' — registering 'default' then
// does nothing, and the call succeeds, which is the most confusing failure available.
ui.registerLayout(ui.activeLayout() ?? 'default', BrandShell);
// Or force it, outranking backend and URL: ui.setLayout('default').
```
Check it
Your header and footer render; the 3D scene sits in `
`; **Save opens the save dialog** and **Generate shows progress** — if either does nothing, `parts.Modals` is missing. Select a product in the scene: the panel switches to that product's options. `ui.activeLayout()` returns the key you registered over.
#### Example 5 — Your own option panel: keep the two levels apart
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-theme-4
The simplest custom panel is ` ` inside your layout — it already handles everything below. Build your own only when its markup will not do. When you do, there is one thing to get right, and it is the reason this example exists.
Option sets come in **two levels**. **Scene-level** sets are the system's — layout, a scene-wide finish, “add a product” — and belong in your layout wherever you like: a header strip, a wizard step, a drawer. **Product-level** sets are different in kind: they are 3D triggers the engine binds to whichever piece is selected (its width, its door style, its own finish). You are not touching that when you customise the UI. They must appear on their own when a piece is selected and disappear when it is deselected — and rendering one flat list mixes the two, so Width and Frame Size show up scene-wide next to Cabinet Finish. `useOptionSets()` hands you the two levels already separated:
```
import { ui, parts, useOptionSets, useSelection } from '@imagineio/configurator-sdk';
// One set, rendered your way. Same component for either level — only the LIST differs.
function SetTiles({ set, o }) {
const options = o.visibleOptions(set.id, o.getOptionsForSet(set)); // hidden ones already dropped
const selected = o.getEffectiveSelection(set.id); // after defaults + rules
return (
);
}
// A. Scene-level controls, PINNED to scene scope — they must not change when a piece is
// selected, which is what lets them live in a header.
function SceneControls() {
const o = useOptionSets({ placementId: null });
return ;
}
// B. The selected product's sets — FOLLOW the selection. Nothing selected → renders nothing.
// Select a piece → its bound sets appear, in the engine's order, with per-piece values.
function ProductDrawer() {
const o = useOptionSets();
const { placementId } = useSelection();
if (!placementId) return null;
return ;
}
// C. As the Sidebar override — INSIDE parts.SidebarFrame, with the props the render site gave you.
// The frame is our panel's chrome without its content (floating card on desktop, tab body on
// mobile, bare column when `embedded`). It is what puts your panel where ours was — see the note.
ui.registerComponent('Sidebar', (props) => (
));
// Or straight inside your own layout (Example 4), where YOUR markup already places them —
// no frame needed there:
```
| Field | What it lists | Order | When nothing is selected |
| --- | --- | --- | --- |
| `sceneOptionSets` | the system's scene-level sets | the backend's | unchanged — it never depends on the selection |
| `productOptionSets` | the sets bound to the focused piece | the binding sequence | `[]` |
| `optionSetList` / `optionSets` | every set in the catalog | catalog | unchanged |
Why the frame
**The default shell positions nothing.** It pads the scene to leave a strip free and renders the panel as a child of the scene box; our `Sidebar` supplies its own floating card there (absolute, over the canvas). An override that returns a bare fragment therefore lands in normal flow _after_ the full-height canvas — below the fold, clipped by `overflow: hidden` — and the strip where the sidebar was is an empty band in the scene colour. No error, nothing to click: “the sidebar went white”. ` ` is the chrome our panel draws around its content, on every breakpoint and in every shell; forward the props (`embedded` matters — the docked shells pass it) and your panel sits exactly where ours did. Inside your own layout (Example 4) your ` ` already does that job, so render the controls directly there.
Two rules
**A set can be in both lists.** A scene-wide finish that a piece also binds is real semantics, not a duplicate: the scene control sets every piece that has no pick of its own; the product drawer sets just that piece. Render both and the user has both.
**Selection and options travel together.** `useOptionSets()` with no argument follows the selection, so `getEffectiveSelection` and `select` in the drawer read and write _that piece's_ values. `{ placementId: null }` pins a panel to the scene; pass a specific id to build a picker for one piece without selecting it.
Check it
The panel sits in the sidebar strip, in our card, not below the canvas — if the strip is blank, the override is not rendering inside `parts.SidebarFrame`. With nothing selected: the header shows the scene sets; the drawer is empty. Click a product in the scene: the drawer fills with that product's sets and nothing in the header changes. Pick an option in the drawer: only that piece changes. Click empty floor to deselect: the drawer empties again.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-theme-ref
Each entry opens the function's full definition in the reference, with its signature, arguments and a captured response where it returns data.
| Used in | Function | What it did here |
| --- | --- | --- |
| Examples 2–3 | ui.applyTheme(record \| id \| null) | applied one part of the theme, then the complete record; `null` takes it off |
| Example 3 | ui.applyCustomCss(css) | CSS on the `data-part` contract for what tokens cannot express |
| Example 3 | ui.setLabels(map) | renamed UI text without replacing components |
| Example 4 | ui.registerLayout(key, Shell) | registered the brand shell over the active key |
| Example 4 | ui.activeLayout() | read the key the backend selected, to register over it |
| Example 4 | ui.setLayout(key \| null) | the alternative: force a shell, outranking backend and URL |
| Example 4 | ui.resolveComponent(name, Default) | rendered parts through the override registry so `registerComponent` overrides still win inside the shell (documented with `registerComponent`) |
| Example 5 | ui.registerComponent(name, Impl) | installed the custom panel as the `Sidebar` |
| Example 5 | parts.SidebarFrame | our panel's chrome around the custom panel, so it sits where ours did instead of falling below the canvas |
| Example 4 | quote.open() | the footer's “View quote” button |
| Example 4 | useGenerateAssets() | the generate pipeline as a hook — handler and progress for your own button |
| Example 4 | useToolbar() | `isLayoutLoading`, to disable actions while a layout loads |
| Example 5 | useOptionSets({ placementId? }) | `sceneOptionSets`, `productOptionSets`, `getOptionsForSet`, `visibleOptions`, `optionDisabledPropsFor`, `getEffectiveSelection`, `select` |
| Example 5 | useSelection() | the selected piece's `placementId`, to show or hide the product drawer |
| Example 4 | parts.* | `Sidebar`, `SceneToolbar`, `SaveProjectButton`, `GenerateAssetsButton`, `ChatBar`, `NotificationContainer`, `Modals`, `ModalHost`, `SlotHost` — the components the shell composed |
| Example 1 | useComponentRegistry() | subscribed the shell to the override registry, so a component registered after mount re-renders inside it |
| Example 1 | useSelectionActions() | `panelActions` and `priceInfo` — the selected piece's move / duplicate / delete and its unit price |
| Example 1 | useProduct(placementId) | the selected placement's catalog record, for the piece's name |
| Example 1 | useToolbar() | the whole dock: `is3D`, `toggleView`, `isOn`, `toggleDimensions`, `toggleWalls`, `canUndo` / `handleUndo`, `canRedo` / `handleRedo` |
| Example 1 | usePrice() | the live total in the floating top bar |
| Example 1 | useSystem() | the system name beside the wordmark |
| Example 1 | useBootStatus() | `loading`, to disable the actions until boot finishes |
| Example 1 | ui.formatMoney(n, currency) | every price in the shell — the top bar total and the selected piece's unit price |
| Example 1 | ui.registerComponent(name, Impl) | suppressed `SelectionActionPanel`, whose actions the Inspector already carries |
Guide
### Override Button Functionality
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-buttons
This guide
Adds extra behaviour to an existing button's click while keeping what it already does, then replaces a button's behaviour outright — covering the buttons the configurator creates for you: Save, Generate Assets, the 2D/3D and view toggles, undo/redo, the selection panel's move/duplicate/delete, the option cards and the quote.
Modify or extend the behavior of existing configurator buttons.
Every built-in button does its work in two halves, and you can reach either. Its **behaviour** is dispatched as an _intent_ — a plain object like `{ type: 'view.mode', mode: '2d' }` — through a middleware chain you can join with `addMiddleware`. Its **markup** is a component you can replace with `ui.registerComponent`, which hands you the built-in as `Default`. So “add to a button” is middleware that calls `next()`, or a wrapper that renders `Default`; “replace a button” is middleware that never calls `next()`, or a component that never renders `Default`. All four are below.
#### Example 1 — Add to what a button does, and keep what it does
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-buttons-1
One middleware sees every button. Code _before_ `await next()` runs before the SDK's own behaviour; code _after_ it runs once that behaviour has finished. It may be async, so you can await your own API first.
```
import { addMiddleware, ui } from '@imagineio/configurator-sdk';
const off = addMiddleware(async (intent, next) => {
// BEFORE — the Save button's click, on its way to our dialog. Record it, gate it, enrich it.
if (intent.type === 'ui.modal.open' && intent.key === 'save') {
await analytics.track('save_clicked');
}
const result = await next(); // OUR behaviour runs here, unchanged
// AFTER — the 2D/3D toggle has switched; tell the shopper.
if (intent.type === 'view.mode') {
ui.notify({ type: 'info', message: `Switched to ${intent.mode.toUpperCase()} view` });
}
return result;
});
// off() stops intercepting.
```
To add to a button's _markup_ instead — a badge, a tooltip, a wrapper — override the component and render `Default` inside it. Nothing about the button's behaviour changes, because `Default` is the real button.
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('GenerateAssetsButton', ({ Default, ...props }) => (
{/* the built-in, doing exactly what it did */}
2 credits {/* yours */}
));
```
Check it
Click Save: our dialog opens _and_ your `analytics.track` fired first. Click 2D/3D: the view switches _and_ a toast appears. The Generate button still generates, with your badge beside it. A middleware that throws is skipped and the button still works — a broken extension never breaks a button.
#### Example 2 — Replace what a button does
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-buttons-2
Don't call `next()` and the SDK's behaviour never runs — yours does instead. Return `{ cancelled: true }` so callers see a deliberate stop rather than a failure.
```
import { addMiddleware, commerce } from '@imagineio/configurator-sdk';
addMiddleware((intent, next) => {
// Whatever calls quote.open() — your button, your post-save hook — opens YOUR page with our data. Ours never opens.
if (intent.type === 'quote.open') {
openMyQuotePage(commerce.readBom());
return { cancelled: true };
}
// Delete asks YOUR confirm first; only a yes reaches the engine.
if (intent.type === 'product.remove') {
return myConfirm('Remove this piece?').then((ok) => (ok ? next() : { cancelled: true }));
}
return next();
});
```
To replace a button _completely_ — its look and its click — override the component and don't render `Default`. You receive the same props the built-in gets (see the table in Override a component), so your button slots into the same place, disabled at the same times.
```
import { ui, scene } from '@imagineio/configurator-sdk';
// Save now sends the design PDF to your CRM instead of opening our Save dialog.
ui.registerComponent('SaveProjectButton', ({ disabled, className }) => (
));
// The whole selection panel, your markup — `actions` are ours, already wired to the engine.
ui.registerComponent('SelectionActionPanel', ({ actions, priceInfo }) => (
));
```
Check it
Trigger `quote.open()` (from your own button — the SDK has none): your page opens, ours doesn't. Click Save: no dialog — your notification instead. Middleware and component overrides compose: a replaced Save button that still dispatches an intent is still seen by your middleware.
#### The buttons you get for free, and how to reach each one
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-buttons-3
Every button the configurator creates automatically, the intent its click dispatches (what middleware sees), and the component that renders it (what `registerComponent` replaces). Intents marked _engine_ round-trip to the backend; the rest are local.
| Button | Where | Intent (`intent.type` + payload) | Component |
| --- | --- | --- | --- |
| Save | header, mobile bar | `ui.modal.open` { key: 'save' } | `SaveProjectButton` |
| Generate Assets | header, mobile bar | `assets.generate` { families } | `GenerateAssetsButton` |
| 2D / 3D | toolbar | `view.mode` { mode: '2d' \| '3d' } | `SceneToolbar` (one component, all toolbar buttons — rebuild it on `useToolbar()`) |
| Walls | toolbar | `view.walls` { next } |
| Dimensions | toolbar | `view.dimensions` { next } |
| Fullscreen | toolbar | `view.fullscreen` { next } |
| Undo / Redo | toolbar | `history.undo` · `history.redo` |
| Reset scene | toolbar | `scene.reset` |
| Move left / right | selection panel | `product.move` { placementId, direction } — engine (`{ placementId, sequence }` from `products.move`) | `SelectionActionPanel` |
| Duplicate | selection panel | `product.duplicate` { placementId } — engine |
| Delete | selection panel | `product.remove` { placementId } — engine |
| An option card | sidebar | `option.select` { optionSetId, optionId } — engine | `OptionThumbnail` · `FinishThumbnail` |
| A layout card | sidebar | `layout.change` { optionSetId, optionId } — engine | `LayoutThumbnail` |
| An “add” card / insert tile | sidebar, scene | `product.add` { productGraphId, variantId, … } — engine | `OptionThumbnail` |
| View quote | shells, your buttons | `quote.open` | — (open it from anywhere with `quote.open()`) |
**API calls dispatch the same intents.** `products.add`, `products.remove`, `products.move`, `options.select` and `quote.open` go through the same middleware chain as the buttons — so a host's own “Add” button is gated by the host's own middleware, exactly like ours.
Hiding instead
To remove a toolbar button rather than change it, don't override — the backend's `uiToggles` already gate each one, and `ui.setToggles({ fullscreen: false })` does the same from code. Overriding is for when the button should _do_ something different. The same map switches the live status panel off: `uiToggles.liveStatus: false` hides it in every layout (desktop, the mobile Status tab, and the wizard / showroom / showcase shells); a host's `ui.setToggles({ liveStatus: true })` brings it back, because host toggles outrank the backend's.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-buttons-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Examples 1–2 | addMiddleware((intent, next) => …) | ran code before/after a button's behaviour, or instead of it; the full intent list and payloads are in its entry |
| Examples 1–2 | ui.registerComponent(name, Impl) | wrapped `Default` to add markup; ignored it to replace the button |
| Examples 1–2 | ui.notify({ type, message }) | the toast after the toggle and after the CRM upload |
| Example 2 | commerce.readBom() | the data handed to your own quote page |
| Example 2 | scene.buildPdf() | the design PDF the replaced Save button sends to your CRM |
| Example 2 | quote.open() | dispatches `quote.open` — the intent the replacement swallows |
| The buttons you get for free | useToolbar() | every toolbar action and state, for rebuilding `SceneToolbar` as your own |
| The buttons you get for free | ui.setToggles(map) | hide a toolbar button instead of overriding it |
Guide
### Add a Custom Button
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-custom-button
This guide
Adds two new buttons and defines what each does: one that changes the _3D scene_ (turn the selected piece; jump to the plan view), and one that changes the _UI_ (open a dialog of your own). Then the third form — a button that runs a named action — and where a button can be placed.
Create new buttons and define their behavior using the SDK.
A new button is one call: `ui.registerButton({ slot, label, onClick })`. It renders as one of ours — same class, same theme colours and radius, disabled while a layout loads — in whichever _slot_ you name, and its `onClick` is plain code that calls the SDK. What the button _does_ is up to you; the SDK gives you the verbs.
#### Example 1 — A button that changes the 3D scene
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-custom-button-1
The `selection-panel` slot appears beside move / duplicate / delete whenever a piece is selected, and its `ctx` carries the selected `placementId`. `products.transform` is the same call the drag gizmo makes — metres and degrees, local, no engine round-trip.
```
import { ui, products, scene } from '@imagineio/configurator-sdk';
// Turn the selected piece a quarter turn.
ui.registerButton({
slot: 'selection-panel',
label: 'Rotate 90°',
title: 'Turn this piece a quarter turn',
onClick: ({ placementId }) => { // the slot's ctx: the selected piece
const piece = products.getSelected();
const [rx = 0, ry = 0, rz = 0] = piece?.rotation ?? [];
products.transform(placementId, piece?.position, [rx, ry + 90, rz]); // metres, degrees
},
});
// Straight to the plan view, from the toolbar.
ui.registerButton({ slot: 'toolbar', label: 'Top view', onClick: () => scene.view.to2D() });
// Other 3D verbs a button can call:
// scene.camera.focusOn(placementId) frame one piece
// scene.hideComponent(slotOrComponentId) hide a part — a door, a handle
// products.changeVariant(placementId, id) swap the piece for another variant
// scene.applyPreset(presetId) load a whole arrangement
```
Check it
Select a piece: **Rotate 90°** appears in the selection panel; click it and the piece turns. `products.transform` returns what it applied, including `freeMovable` — `false` means the piece is in a run and the layout will put it back on the next render, so use `products.move` for those. **Top view** switches to 2D; `scene.view.is3D()` reads `false`.
#### Example 2 — A button that opens your own UI
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-custom-button-2
Register a dialog under a key, then a button that opens it. Your component receives `data` (whatever you passed to `openModal`) and `close`. Your component is the dialog's **content**: the SDK supplies the backdrop, centring, themed panel, Escape and click-outside, so even this unstyled markup opens as a proper dialog. Restyle the frame with `[data-part="modal/panel"]`.
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerModal('book-designer', ({ data, close }) => (
Book a designer
We'll call you about the {data?.from} you are working on.
));
ui.registerButton({
slot: 'sidebar-top', // above the option sets
label: 'Book a designer',
variant: 'primary', // filled with the theme's brand colour
onClick: () => ui.openModal('book-designer', { from: 'configurator' }),
});
```
The third form: register a _named action_ and point the button at it. The click then also reaches middleware as `action.share`, so it can be logged or gated like any built-in.
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerAction('share', () => shareCurrentDesign());
ui.registerButton({ slot: 'toolbar', label: 'Share', action: 'share' });
```
Check it
**Book a designer** renders as a filled brand button above the option sets; clicking it opens your dialog with the data you passed; _Book a call_ closes it. **Share** runs your action and `ui.listActions()` lists `share`. Every `registerButton` returns an unregister — call it and the button is gone.
#### Where buttons can go
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-custom-button-3
| slot | Where it renders | `ctx` your onClick receives |
| --- | --- | --- |
| `toolbar` | the scene toolbar — beside 2D/3D, walls, dimensions | `{ isMobile }` |
| `selection-panel` | the floating panel over a selected piece — beside move / duplicate / delete | `{ placementId, actions }` |
| `sidebar-top` | above the option sets | `{ placementId }` (the selected piece, or null) |
| `sidebar-bottom` | below the option sets | `{ placementId }` |
| `overlay` | over the 3D canvas — position it yourself with absolute CSS | — |
When a button isn't enough
`registerButton` is the shorthand for the common case. For a control whose _look_ it cannot express — an input, a form, a floating bar — use `ui.registerSlot(slot, Component)` with the same slot names; a slot takes any component, and several registrations in one slot render in order. Every custom layout keeps these slots working by mounting `parts.SlotHost` (see Replace the whole layout).
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-custom-button-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Examples 1–2 | ui.registerButton({ slot, label, onClick \| action, variant?, title?, icon? }) | every new button on this page |
| Example 1 | products.getSelected() | the selected piece's current position and rotation |
| Example 1 | products.transform(placementId, position, rotation) | turned the piece — metres, degrees, local |
| Example 1 | scene.view.to2D() | the plan view (`to3D`, `toggle`, `is3D` beside it) |
| Example 1 | scene.camera.focusOn(placementId) | frame one piece — another 3D verb for a button |
| Example 1 | scene.hideComponent(slotOrComponentId) | hide a physical part by slot name, component name or id — another 3D verb for a button |
| Example 2 | ui.registerModal(key, Component) | your dialog, receiving `{ data, close }` |
| Example 2 | ui.openModal(key, data?) | opened it, passing data |
| Example 2 | ui.registerAction(name, fn) | the named verb a button can point at with `action:` |
| Where buttons can go | ui.registerSlot(slot, Component) | the general form, for controls a button cannot express |
Guide
### Add Custom 3D Functionality
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-3d
This guide
Three things a host does in the 3D scene that the built-in UI does not: move an object from code, load an object of your own into the scene and play an animation on it, and play an animation on an object that is already there.
Extend the configurator with your own custom features and functionality.
The scene has three layers you can reach, from safest to rawest. **Verbs** — `products.transform`, `products.move`, `scene.transformComponent` — change the scene through the SDK, so the engine and the saved state stay in step. **Renderers** — `scene.registerRenderer` — let you wrap how one _kind_ of component is drawn, inside our React-three-fiber tree, with our built-in handed to you as `Default`. **Raw access** — `scene.onReady` — hands you the live `scene`, `camera` and `renderer` for anything else.
#### Example 1 — Move an object
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-3d-1
Which verb depends on what the piece is. A _free-movable_ piece (the catalog flags it) takes an absolute position and rotation — metres and degrees, the same call the drag gizmo makes. A piece _in a run_ is positioned by its sequence, so you move it by changing that. A _part_ of a piece — a shelf, a door — takes a delta by slot name. All three act on the live scene, so they run inside `scene.onReady`: before it fires there is nothing to move, and a call made too early is a no-op.
```
import { products, scene } from '@imagineio/configurator-sdk';
// Everything below needs a scene to act on. onReady fires once it exists — and straight away if it
// already does — so this is safe at module scope, in an effect, or from a button.
scene.onReady(async () => {
// A free-movable piece: absolute position (metres) and rotation (degrees). Local — no
// engine round-trip — and it persists with the saved scene.
const r = products.transform('p1', [1.5, 0, 0], [0, 45, 0]);
// → { placementId: 'p1', position: [1.5, 0, 0], rotation: [0, 45, 0], freeMovable: true }
// freeMovable: false → the piece is in a run and the layout will put it back. For those:
await products.move({ placementId: 'p1', sequence: 3 }); // engine round-trip; the run re-lays out
// A PART of a piece, by slot: a delta, metres / degrees. Survives re-evaluates.
scene.transformComponent('shelf', { position: [0, 0.05, 0] });
// Bring the camera to it — after a short delay, not on onSettled(). On initial load the SDK
// frames the whole scene itself once everything has settled, and that reset lands at the same
// moment onSettled() resolves, overriding a focus fired there. A 3 s wait clears it.
await new Promise((r) => setTimeout(r, 3000));
scene.camera.focusOn('p1');
});
```
Check it
`products.transform` returns what it applied; `useProducts()` (or `products.getSelected()`) shows the new position on the next read. If `freeMovable` came back `false`, the piece snapped back on the next render — that is the run doing its job, not a bug; use `products.move`.
#### Example 2 — Load your own object into the scene and animate it
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-3d-2
`scene.onReady` gives you the live scene. Load your model with the `GLTFLoader`, add it, and drive its `AnimationMixer` from a frame loop. Two rules make it work: **call `invalidate()` every tick** — the canvas renders on demand, so without it nothing repaints — and **register a disposer**, because everything you add is yours to remove.
```
import { scene } from '@imagineio/configurator-sdk';
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'; // your three — same copy as ours
scene.onReady(({ THREE, scene: three, invalidate, registerDisposable }) => {
let mixer, raf;
const clock = new THREE.Clock();
new GLTFLoader().load('/models/plant.glb', (gltf) => {
gltf.scene.position.set(1.2, 0, 0.4);
three.add(gltf.scene);
mixer = new THREE.AnimationMixer(gltf.scene);
mixer.clipAction(gltf.animations[0]).play(); // the model's own animation
const tick = () => {
mixer.update(clock.getDelta());
invalidate(); // ask for this frame — REQUIRED
raf = requestAnimationFrame(tick);
};
tick();
});
// Teardown: stop the loop, take the object out. The SDK calls this when the scene unmounts.
registerDisposable(() => { cancelAnimationFrame(raf); mixer?.stopAllAction(); });
});
```
Entitlement
Raw scene access is an organisation-level entitlement (`exposeThreejsScene` on your catalog). Without it `onReady` never fires — the verbs and renderers above still work. Ask your imagine.io contact to enable it.
Check it
Your model appears and moves; the `scene` `onReady` handed you finds it with `getObjectByName('…')`. Remove `invalidate()` and it freezes — that is the on-demand loop, working as designed. Call the function `onReady` returned and the object is gone.
#### Example 3 — Play an animation on an existing object
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-3d-3
Two routes. The clean one: register a renderer for the component you want to animate, wrap the built-in in a group and turn the group with `useFrame`. The SDK keeps owning the mesh, materials and swaps — a door-style change re-resolves `Default` underneath your group and the animation keeps running.
```
import { useRef } from 'react';
import { useFrame, useThree } from '@react-three/fiber'; // peer dependency — already installed
import { scene } from '@imagineio/configurator-sdk';
function SwingingDoor({ Default, ...props }) {
const hinge = useRef();
const { invalidate } = useThree();
useFrame(({ clock }) => {
if (!hinge.current) return;
hinge.current.rotation.y = Math.sin(clock.elapsedTime) * 0.6; // ±35°
invalidate(); // the canvas renders on demand — ask for the next frame
});
// The built-in carries its own position/rotation on its root, so this group pivots at the
// PRODUCT origin, not the door's edge. For a true hinge, offset the group to the hinge line
// and counter-offset the child.
return ;
}
// The key is the component's SLOT NAME — what scene.listComponents() reports for each piece
// (`door_left`, `seat_3`, …). Case-insensitive. A catalog component's own kind or name also
// matches, so a name like 'Anne 3 Seater' works too — but the slot is the stable one.
scene.registerRenderer('door_left', SwingingDoor);
```
The raw route, when you need a specific _piece_ rather than a kind: from `onReady`, find its root by name — every placed piece is `placement- ` — and drive an `AnimationMixer` on it exactly as in Example 2.
```
import { scene } from '@imagineio/configurator-sdk';
scene.onReady(({ THREE, scene: three, invalidate, registerDisposable }) => {
const piece = three.getObjectByName('placement-p1'); // the placed piece's root Object3D
const clip = new THREE.AnimationClip('nudge', 1, [
new THREE.VectorKeyframeTrack('.position', [0, 0.5, 1], [0,0,0, 0,0.1,0, 0,0,0]),
]);
const mixer = new THREE.AnimationMixer(piece);
mixer.clipAction(clip).play();
// …the same tick / invalidate / disposer loop as Example 2
});
```
Check it
The door swings; a door-style swap keeps swinging, because `Default` re-resolved underneath your group. If nothing moves, the key did not match: `scene.listComponents()` shows every component in the live scene with its `slotName` and `name` — register under the `slotName`. `scene.listRenderers()` lists what you registered. Prefer this route over the raw one whenever the thing you animate is a component: it survives swaps and re-evaluates for free.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-3d-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Example 1 | products.transform(placementId, position, rotation) | moved a free piece — metres, degrees, local |
| Example 1 | products.move({ placementId, sequence }) | moved a piece within its run — engine round-trip |
| Example 1 | scene.transformComponent(slot, { position?, rotation? }) | nudged one part of a piece by a delta |
| Example 1 | scene.camera.focusOn(placementId) | framed the moved piece |
| Examples 2–3 | scene.onReady(fn) | the live scene — `{ THREE, scene, camera, renderer, invalidate, registerDisposable }` |
| Example 3 | scene.registerRenderer(kind, Component) | wrapped how a component kind draws; `Default` is the built-in |
| Example 3 | scene.listRenderers() | confirm the registration landed |
Guide
### Customize or Create Quote Templates
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-quote
This guide
Two examples: brand the shipped quote — your company, your columns, your terms — with one object; then build a quote document of your own as a React component. Either way the result is _one design on every surface_: the on-screen dialog and every PDF the SDK produces.
Modify the design and layout of existing quote templates, or create entirely new custom quote templates using the SDK functions.
The quote is the one surface where “looks like ours” is actively wrong — it goes to a customer on _your_ letterhead. So the SDK ships a deliberately plain document and two ways past it: a **spec** that reshapes the shipped template (Example 1), and a **template registration** that replaces it with your component (Example 2). Both read the same data.
| You call | On-screen quote (`quote.open()`) | PDFs — Save, Generate Assets, download | Use it for |
| --- | --- | --- | --- |
| `quote.setDocument(spec)` | **yes** — the shipped template reads it | **yes** — every PDF the SDK produces | branding: company, title, columns, terms, accent, logo. The one call that covers both surfaces — start here. |
| `quote.registerTemplate(key, Comp)` | **yes** — replaces the shipped template with your component | **yes** — the same component is rendered into the PDF pages | your own design, on screen and in every PDF — one component |
| `quote.registerPdf(fn)` / `registerPdfEndpoint` | no | **yes** — takes precedence over the template; one registration covers every PDF | a text-based PDF rendered your way, when the rendered template is not enough |
Where to look
The **on-screen quote** is a dialog that only `quote.open()` shows — the SDK ships no Quote button; your code calls it. The **PDFs** are what Save and Generate Assets produce, and they follow the same design: the spec brands the shipped document, and a registered template is rendered into the pages as-is. Register a template, click Save, open the file — it is your component.
#### Example 1 — Modify the existing template
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-quote-1
One object, no component, **both surfaces**: the shipped on-screen template reads it live, and so does every PDF the SDK produces. Set it before or after `mount()`. Unset fields keep their defaults; `columns` is both which and in what order.
```
import { quote } from '@imagineio/configurator-sdk';
quote.setDocument({
company: 'Acme Interiors', // letterhead line (logoUrl beside it, if you have one)
title: 'Estimate', // instead of the system name
columns: ['item', 'qty', 'total'], // from: item · sku · options · qty · unit · total
terms: 'Prices valid 30 days. E&OE.',
notes: 'Delivery quoted separately.',
accent: '#0b7285', // rules and headings
images: { max: 2, types: ['lifestyle'] }, // which generated renders appear, and how many
arQr: true, arQrLabel: 'Scan to view in your room',
});
```
Check it
Call `quote.open()` — from the console, or from your own code — and the dialog shows your company on top, _Estimate_ as the heading, exactly three columns in your order, your terms at the foot. The same object also brands the quote PDF and the bill-of-materials PDFs — see Brand every document for the full field list and the two fields that are quote-only.
#### Example 2 — Build your own template
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-quote-2
Your component becomes the quote everywhere: the dialog `quote.open()` shows, and the PDF that Save, Generate Assets and the download button produce — the SDK renders the same component into the PDF pages. (The dialog opens only when your code calls `quote.open()` — see the note after this example.) A template is a component receiving `{ quote, close }`. `quote` is `quote.read()` — every line with its options already resolved to _names_ and every price already _formatted_, plus totals, the system, the generated renders and the AR link.
```
import { quote, parts } from '@imagineio/configurator-sdk';
/**
* A branded quote document.
*
* `quote.registerTemplate` hands you the whole `quote.read()` object — already priced,
* already currency-formatted, with option ids resolved to names — plus a `close` callback.
* Everything visual below is ours; the SDK renders what we return and nothing around it.
*/
const CSS = `
.nq { --ink:#12161c; --muted:#6b7480; --line:#e3e7ec; --brand:#1f3a5f; --accent:#c8a24a;
--bg:#fff; color:var(--ink); background:var(--bg);
font:14px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
max-width:820px; margin:0 auto; padding:36px 40px; }
@media (prefers-color-scheme:dark){ .nq{ --ink:#e8ecf1; --muted:#9aa4b2; --line:#2a3038;
--brand:#8fb3e0; --accent:#d8b969; --bg:#12161c; } }
.nq__top{ display:flex; justify-content:space-between; align-items:flex-start;
gap:24px; padding-bottom:20px; border-bottom:2px solid var(--brand); }
.nq__mark{ font-size:19px; font-weight:700; letter-spacing:.16em; color:var(--brand); }
.nq__tag{ margin-top:2px; font-size:11px; letter-spacing:.14em; text-transform:uppercase; color:var(--muted); }
.nq__meta{ text-align:right; font-size:12px; color:var(--muted); }
.nq__meta b{ display:block; font-size:15px; color:var(--ink); font-weight:600; }
.nq__hero{ margin:22px 0 4px; border:1px solid var(--line); border-radius:10px; overflow:hidden; }
.nq__hero img{ display:block; width:100%; height:auto; }
.nq h3{ margin:28px 0 10px; font-size:11px; letter-spacing:.14em; text-transform:uppercase; color:var(--muted); font-weight:600; }
.nq table{ width:100%; border-collapse:collapse; }
.nq th{ text-align:left; font-size:11px; letter-spacing:.08em; text-transform:uppercase;
color:var(--muted); font-weight:600; padding:0 0 8px; border-bottom:1px solid var(--line); }
.nq th.num,.nq td.num{ text-align:right; white-space:nowrap; }
.nq td{ padding:13px 0; border-bottom:1px solid var(--line); vertical-align:top; }
.nq__item{ font-weight:600; }
.nq__chips{ margin-top:6px; display:flex; flex-wrap:wrap; gap:5px; }
.nq__chip{ font-size:11.5px; color:var(--muted); background:color-mix(in srgb,var(--brand) 8%,transparent);
border:1px solid var(--line); border-radius:999px; padding:2px 9px; }
.nq__chip b{ color:var(--ink); font-weight:600; }
.nq__totals{ margin-top:18px; margin-left:auto; width:min(320px,100%); font-size:13px; }
.nq__totals div{ display:flex; justify-content:space-between; padding:7px 0; }
.nq__totals .grand{ margin-top:6px; border-top:2px solid var(--brand); padding-top:12px;
font-size:19px; font-weight:700; }
.nq__note{ margin-top:10px; font-size:11.5px; color:var(--muted); }
.nq__foot{ margin-top:34px; padding-top:16px; border-top:1px solid var(--line);
display:flex; justify-content:space-between; align-items:center; gap:16px; flex-wrap:wrap; }
.nq__empty{ padding:26px 0; color:var(--muted); }
.nq__btn{ font:inherit; font-weight:600; padding:9px 18px; border-radius:7px; cursor:pointer;
border:1px solid var(--line); background:transparent; color:var(--ink); }
@media print{ .nq{ padding:0; max-width:none; } .nq__btn{ display:none; } }
`;
function NordhusQuote({ quote: q, close }) {
const lines = q.lines ?? [];
const extras = q.additionalLines ?? [];
const hero = (q.images?.ready ?? []).find((a) => a.type === 'lifestyle' || a.type === 'silo');
return (
Total includes a scene-level adjustment not itemised above.
)}
{/* Ours, dropped into your layout. `images.ready` also holds the AR .glb and the
PDF, which break in an — these two parts filter for you. */}
);
}
// Registered under a KEY so several designs can coexist (the backend's `system.quoteTemplate`
// picks one per channel), AND under 'default' so it renders even with no key selected.
quote.registerTemplate('nordhus', NordhusQuote);
quote.registerTemplate(NordhusQuote);
quote.setTemplate('nordhus');
```
| `quote.read()` field | What it holds |
| --- | --- |
| `system` | `{ id, name }` — what is being quoted |
| `lines[]` | one per placed product: `placementId`, `sku`, `name`, `qty`, `unitPrice` / `unitPriceFormatted`, `lineTotal` / `lineTotalFormatted`, `adjustments[]`, and `selections[]` as `{ setName, optionName }` |
| `additionalLines[]` | scene-level costs from aggregate option sets, counted by the engine and part of the total: `optionSetId`, `optionId`, `setName`, `label`, `count`, `unitAmountFormatted`, `amountFormatted` |
| `totals` | `lineCount`, `subtotal`, `grandTotal` (+ `*Formatted`), `hasSceneLevelAdjustment` — `grandTotal` is the engine's number, never a local sum |
| `images` | `{ images[], ready[], uploadedImageUrl }` — the generated renders; hand it to `parts.QuoteRenders` / `parts.QuoteQr` |
| `currency`, `quotedAt`, `metadata` | for your own formatting and your own fields |
Check it
`quote.activeTemplate()` returns `'nordhus'`. Open the quote: your document, one row per placed product — the same rows `commerce.readBom()` reports — options as names, prices formatted like the configurator. _Close_ closes it. Unregister (the function `registerTemplate` returned) or `setTemplate(null)` and the shipped document is back.
On screen
The PDFs need nothing more. The _dialog_ opens only when your code calls `quote.open()` — the SDK adds no button. Call it from your own UI, or at the moments that matter: `on('project.saved', () => quote.open())` after a save, `on('assets.generated', () => quote.open({ waitForImages: true }))` once the renders are in. Not on the Save _click_: the quote and the save dialog share one slot, so open it after.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-quote-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Example 1 | quote.setDocument(spec) | reshaped the shipped template — company, title, columns, terms, accent, images, AR code |
| Example 2 | quote.registerTemplate(key?, Component) | your document, receiving `{ quote, close }` — on screen and in every PDF |
| Example 2 | quote.setTemplate(key \| null) | selected your design in code, outranking the backend key |
| Example 2 | quote.activeTemplate() | which design is live |
| Example 2 | quote.read() | the data your template receives — named selections, formatted prices, totals, images |
| Example 2 | quote.images() | the generated renders on their own, if you read them outside a template |
| Example 2 | quote.open({ waitForImages? }) | opens the on-screen quote at your moment — the examples themselves open nothing |
| Example 2 | on('project.saved' \| 'assets.generated', fn) | the moments after a save and after a render run |
| Example 2 | commerce.readBom() | the raw rows behind `quote.read()`, for an ERP or your own maths |
| Example 2 | parts.QuoteRenders · parts.QuoteQr | the render strip and the AR code, filtered from `quote.images` |
Guide
### Integrate with E-Commerce Platforms
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-ecom
This guide
Three Shopify examples: let your store's own UI select options and show the configurator's price; keep a cart payload in sync so billing always has the latest values; and send whatever else Shopify needs — cart token, customer id, the saved design's link — along with the configuration.
Connect the configurator with any e-commerce platform, including a Shopify integration example.
Two shapes of integration exist and the SDK supports both. When the configurator runs **on your store page** (a theme section, a headless storefront), you call the SDK directly — that is this guide. When it runs **in an iframe** on your store, the same verbs and events cross the frame as a postMessage bridge that activates on its own — see The e-commerce bridge for the wire protocol; every command there has the same name as the function here. Nothing in this guide is Shopify-specific until the last step of each example: the payloads are plain data any platform's cart API accepts.
#### Example 1 — Drive options and read the price from your store
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-ecom-1
Your store already has a variant picker, a swatch strip, a “size” dropdown. Point it at `options.select` and the configurator follows; the engine re-prices and tells you through `price.changed`. Option and set ids are the ones in your imagine.io catalog — every event echoes them back, so you can also learn them by clicking around.
```
import { options, commerce, on, usePrice } from '@imagineio/configurator-sdk';
// Your swatch strip → the configurator. Scene-wide when nothing is selected, the selected
// piece when one is — the same rule the built-in sidebar follows.
document.querySelector('#finish-swatches').addEventListener('change', (e) => {
options.select(10, Number(e.target.value)); // optionSetId, optionId
});
// The configurator → your price badge. Fires after every engine round-trip that re-priced.
on('price.changed', (pricing) => {
document.querySelector('#price').textContent = formatMoney(pricing.grandTotal);
});
// Or read it on demand — the same numbers, never computed locally:
const { grandTotal, currency, lines } = commerce.readBom();
// In React: live, re-rendering on every re-price.
function PriceBadge() { const { grandTotal, currency } = usePrice(); return {grandTotal} {currency}; }
```
Check it
Pick a swatch: the scene updates and `option.selected` fires with `{ optionSetId, optionId }`. Whenever a change makes the engine re-price — a variant or product change always does — `price.changed` follows with the engine's `{ grandTotal, placements }`. `commerce.readBom().grandTotal` reads the same number. In an iframe, the parent gets the identical events over the bridge.
#### Example 2 — Keep the cart in sync for billing
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-ecom-2
Build the cart payload from `quote.read()`: one line per placed product, the chosen options already resolved to _names_ (what a merchant needs to fulfil the order), prices already formatted. Rebuild it on every change so billing never sees a stale total. The one thing the SDK cannot know is **your Shopify variant ids** — the mapping from a configurator line to a variant is yours.
```
import { quote, project, on } from '@imagineio/configurator-sdk';
// Your mapping, keyed on `line.variantId` — the id the engine actually places.
const VARIANT_BY_ID = {
2348: 'gid://shopify/ProductVariant/9001', // Single Door 9"
2376: 'gid://shopify/ProductVariant/9002', // Double Door 24"
};
function buildCart() {
const q = quote.read();
const items = [], unmapped = [];
for (const line of q.lines) {
const variantId = VARIANT_BY_ID[line.variantId];
// A line with no variant is the realistic failure. Record it — never drop it: a cart
// silently missing a line checks out at a plausible-looking wrong price.
if (!variantId) { unmapped.push({ placementId: line.placementId, variantId: line.variantId, name: line.name }); continue; }
items.push({
variantId, quantity: line.qty,
properties: Object.fromEntries(line.selections.map((s) => [s.setName, s.optionName])), // 'Finish': 'Oak'
});
}
const token = project.getShareToken(); // only a SAVED design has a link worth attaching
return { items, unmapped, total: q.totals.grandTotalFormatted,
attributes: { configuration: q.system.name, ...(token ? { design_url: project.shareUrl() } : {}) } };
}
// Rebuild on every change that can affect billing.
for (const e of ['product.added', 'product.removed', 'option.selected', 'layout.changed', 'price.changed']) {
on(e, () => syncDraftCart(buildCart()));
}
// The last step is the only Shopify-specific one — pick the API that fits where you run:
// /cart/{variant}:{qty},…?attributes[design_url]=… cart permalink — no token, no backend, no CORS
// POST /cart/add.js { items } on the shop's own domain — keeps per-line properties
// Storefront API cartCreate / cartLinesAdd headless — tokenised
// (Per-line `properties` do not survive a permalink — Shopify's limit, not ours. Use add.js or the API when you need them.)
```
Check it
Change anything — an option, a product, the layout — and the payload rebuilds; `items.length > 0` (nothing mapped means your key is wrong, not that the cart is empty) and `items.length + unmapped.length` equals `commerce.readBom().lines.length`, so nothing is ever lost. Each item's `properties` has option _set_ names as keys and option names as values. `design_url` is present only after a save.
#### Example 3 — Send configurator data to Shopify (and Shopify data to the configurator)
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-ecom-3
Three channels, for three kinds of information. **Metadata** for ids that must travel _with_ the configuration — the cart token, the customer, your order draft — it is saved, shared and restored along with the design. **The saved design's link** for the order record, so support can reopen exactly what was bought. **The PDF** for the customer's confirmation.
```
import { commerce, project, scene, on } from '@imagineio/configurator-sdk';
// Shopify → configuration: attach your ids. Namespaced, size-limited, round-trips with save/share.
commerce.setMetadata('project', 'shopify', { cartToken: cart.token, customerId: customer.id });
commerce.setMetadata('placement', 'shopify', { lineKey: '…' }, { placementId: 'p1' }); // per piece
const mine = commerce.readMetadata('project', 'shopify'); // back again, e.g. after a reopen
// Configuration → Shopify: save, then put the link and the reference on the order.
const { shareUrl, pdfUrl } = await project.save({ projectName: 'Order 1042', customer: { email } }, {
buildPdf: () => scene.buildPdf(), // the design PDF, uploaded and linked for you
});
await shopify.cart.updateAttributes({ design_url: shareUrl, design_pdf: pdfUrl });
// Everything that happens, to your analytics — one firehose listener.
on('*', (name, payload) => track(`configurator.${name}`, payload));
```
Check it
`setMetadata` returns `true` when accepted and `false` — with a console warning — when the value would exceed the limit (`commerce.LIMITS`: 4 KB per placement, 64 KB per project); it never throws. `readMetadata` returns exactly what you set; `serializeMetadata()` is what save/share persists, so your ids survive a reopen from a share link. The `'*'` listener receives `(name, payload)` — name first.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-ecom-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Example 1 | options.select(optionSetId, optionId) | your store's picker driving the configurator (`selectForScene` / `selectForProduct` to force a scope) |
| Examples 1–3 | on(event, handler) | `option.selected`, `price.changed`, the cart-sync set, and the `'*'` firehose — full list under Events |
| Example 1 | usePrice() | the live price in a React badge |
| Examples 1–2 | commerce.readBom() | the raw rows and the engine's total, on demand |
| Example 2 | quote.read() | lines with named selections and formatted prices — the cart payload's source |
| Example 3 | commerce.setMetadata(scope, ns, value, { placementId? }) | attached Shopify's ids to the configuration |
| Example 3 | commerce.readMetadata(scope, ns) | read them back after a reopen |
| Example 3 | project.save(details, { buildPdf }) | saved the design; returned `shareUrl` and `pdfUrl` for the order |
| Example 3 | scene.buildPdf() | the design PDF for the confirmation |
| All | the e-commerce bridge | the same verbs and events over postMessage when the configurator is in an iframe |
Guide
### Add Custom Popups
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-popup
This guide
One popup of your own, opened two ways: from a button you add, and automatically when a rule your team wrote in the admin fires — either as a custom effect type you implement, or as a named event the rule emits.
Add your own custom popups and control their behavior.
A popup is a component registered under a key with `ui.registerModal`; anything can open it with `ui.openModal(key, data)`. The SDK renders it inside its own dialog frame — a backdrop that dims and blurs the page (every dialog of ours does the same; `--modal-backdrop-blur` sets how much, `0` turns it off), a centred themed panel, Escape and click-outside — so it stacks, dims and dismisses like ours with no styling of yours, and your component receives `data` and `close`. What differs is _who calls openModal_ — and the interesting case is a rule, because then the “when” lives in the admin where business people can change it without a release.
#### Example 1 — The popup, and a button that opens it
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-popup-1
```
import { ui } from '@imagineio/configurator-sdk';
// The popup. `data` is whatever openModal was given; `close` dismisses it.
ui.registerModal('promo', ({ data, close }) => (
{data?.title ?? 'Offer'}
{data?.code &&
Use code {data.code} at checkout.
}
{data?.body &&
{data.body}
}
));
// A button that opens it, styled like ours, in the toolbar.
ui.registerButton({
slot: 'toolbar', label: 'Offers',
onClick: () => ui.openModal('promo', { title: 'Weekend offer', code: 'WEEKEND' }),
});
// From anywhere else, the same call: ui.openModal('promo', {…}); ui.closeModal() closes whatever is open.
```
Check it
Click **Offers**: your popup, with your data, dimming the page like our dialogs. _Got it_ closes it. Every custom layout keeps this working by mounting `parts.ModalHost` (see Replace the whole layout).
#### Example 2 — Open it when a rule fires
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-popup-2
Rules are authored in the imagine.io admin and evaluated by the engine — the frontend never re-derives one. A rule can hand output to your code in two forms, and both arrive on the response of the evaluation that fired it. Register for the form your team chose.
```
import { ui, registerEffectHandler, onBackendEvent } from '@imagineio/configurator-sdk';
// 2a. A CUSTOM EFFECT TYPE. Admin rule: "WHEN the base run has 4+ units → effect show_popup
// { title: 'Bundle offer', body: '…' }". The SDK does not know show_popup; this defines it.
registerEffectHandler('show_popup', (eff) => {
// eff = { ruleId, type: 'show_popup', params: { title, body }, placementId? }
ui.openModal('promo', eff.params);
});
// 2b. A NAMED EVENT. Admin rule: "WHEN a promo finish is chosen → emit promo_applied { code }".
onBackendEvent('promo_applied', ({ ruleId, payload, placementId }) => {
ui.openModal('promo', { title: 'Promo applied', code: payload.code });
});
```
| Rule output | Your subscription | Handler receives | Use when |
| --- | --- | --- | --- |
| a custom **effect type** | `registerEffectHandler(type, fn)` | `{ ruleId, type, params, placementId? }` | the rule should _do_ something the SDK has no verb for; one handler per type, last wins |
| a named **event** | `onBackendEvent(name, fn)` | `{ ruleId, name, payload, placementId? }` | the rule is _telling_ you something; any number of listeners |
| the built-in `show_message` effect | — nothing to write | — | a plain toast / inline notice / modal with admin-written text; use it before reaching for code |
Check it
Make the change the rule watches for; the evaluation returns and your popup opens with the rule's `params` or `payload`. A handler that throws is logged and skipped — it never breaks the render. An effect type with no handler is dropped silently, so a popup that never appears usually means the _name_ differs between the admin rule and your `registerEffectHandler`. Learn the events your rules emit by logging the firehose: `on('*', (name, payload) => console.log(name, payload))`.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-popup-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Example 1 | ui.registerModal(key, Component) | the popup, receiving `{ data, close }` |
| Examples 1–2 | ui.openModal(key, data?) | opened it — from the button and from both rule handlers |
| Example 1 | ui.closeModal() | close from outside the popup |
| Example 1 | ui.registerButton({ slot, label, onClick }) | the Offers button |
| Example 2 | registerEffectHandler(type, fn) | gave the admin's `show_popup` effect a meaning |
| Example 2 | onBackendEvent(name, fn) | listened for the rule's `promo_applied` event |
| Example 2 | events your own team invents | how rules, events and effects fit together |
| Example 2 | ui.notify({ type, message }) | the lighter alternative when a toast is enough |
Guide
### Integrate Custom APIs
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-api
This guide
Makes entries on your own platform from the configurator — a CRM record, a lead, an analytics row — on every accepted change and on save. Then the two companions: asking your API _before_ the engine acts, and pulling your data _in_ at boot.
Connect your own APIs and external services with the configurator.
There is nothing to configure: your API is just code you call, and the SDK gives you three places to call it from. **After** something happened — an event. **Before** it happens — middleware, which can wait for your answer and say no. **At the start** — the sticky `ready` event.
#### Example 1 — Send entries to your platform
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-api-1
Subscribe to the events that change what is being configured, and post an entry with the current bill of materials attached. `product.added` fires only when the engine _accepted_ the change — a rejected add never looks like one.
```
import { on, commerce, project, scene } from '@imagineio/configurator-sdk';
async function postEntry(event, payload) {
const bom = commerce.readBom(); // lines + the engine's total, never computed locally
await fetch('https://api.yourco.com/entries', {
method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
body: JSON.stringify({ event, payload, grandTotal: bom.grandTotal, lines: bom.lines, at: new Date().toISOString() }),
});
}
for (const e of ['product.added', 'product.removed', 'option.selected', 'layout.changed']) {
on(e, (payload) => postEntry(e, payload));
}
// The big one: a saved design is a lead. Save, then send the record with its links.
async function submitLead(customer) {
const { shareUrl, pdfUrl } = await project.save({ projectName: 'Web lead', customer }, { buildPdf: () => scene.buildPdf() });
await fetch('https://api.yourco.com/leads', { method: 'POST', body: JSON.stringify({ customer, shareUrl, pdfUrl, bom: commerce.readBom() }) });
}
```
Check it
Change an option: one POST, `event: 'option.selected'`, the BOM total in the body. Add a product: another. Your platform sees every accepted change. For a firehose instead of a list, `on('*', (name, payload) => …)` — name first.
#### Example 2 — Ask your API before the engine acts
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-api-2
Middleware may be `async`. Await your API, then either call `next()` — the SDK proceeds — or return `{ cancelled: true }` and tell the shopper why. Nothing reaches the engine until you decide.
```
import { addMiddleware, ui } from '@imagineio/configurator-sdk';
addMiddleware(async (intent, next) => {
if (intent.type === 'product.add') {
const { inStock, eta } = await fetch(`https://api.yourco.com/stock?variant=${intent.variantId}`).then((r) => r.json());
if (!inStock) {
ui.notify({ type: 'error', message: `Out of stock — back ${eta}` });
return { cancelled: true }; // the engine never hears about it
}
}
return next();
});
```
Check it
With your API answering _no_: the add does not happen, the toast shows, the BOM is unchanged, and no `product.added` fires. With _yes_: the add proceeds exactly as before and Example 1 posts its entry. If your API is down, decide the failure mode deliberately — `try/catch` around the fetch and `next()` in the catch to fail open, or cancel to fail closed.
#### Example 3 — Pull data in at boot
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-api-3
`ready` is _sticky_: a subscriber that arrives after boot still runs, immediately. Fetch from your platform there and apply it through the same verbs your UI would use.
```
import { on, options, commerce } from '@imagineio/configurator-sdk';
on('ready', async () => {
const prefs = await fetch('https://api.yourco.com/prefs', { credentials: 'include' }).then((r) => r.json());
if (prefs.finish) options.select(prefs.finishOptionSetId, prefs.finish); // the customer's usual finish
commerce.setMetadata('project', 'yourco', { customerId: prefs.customerId }); // and carry their id with the design
});
```
Where the SDK's own calls are concerned
These three examples are about _your_ API. The SDK's calls to the imagine.io engine authenticate with your API key and need nothing from you. If your platform must render the quote PDF, that is quote.registerPdfEndpoint — the SDK POSTs the quote to your URL and expects a PDF back.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-api-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Examples 1, 3 | on(event, handler) | the accepted-change events, and the sticky `ready` |
| Examples 1, 3 | commerce.readBom() | the BOM attached to every entry |
| Example 1 | project.save(details, { buildPdf }) | the saved design's `shareUrl` and `pdfUrl` for the lead |
| Example 1 | scene.buildPdf() | the PDF attached to the save |
| Example 2 | addMiddleware(async (intent, next) => …) | awaited your stock API before the add; cancelled on no |
| Example 2 | ui.notify({ type, message }) | told the shopper why |
| Example 2 | products.add({ productGraphId, variantId }) | the add being gated |
| Example 3 | options.select(optionSetId, optionId) | applied the customer's preference |
| Example 3 | commerce.setMetadata(scope, ns, value) | carried your customer id with the design |
Guide
### Work with Custom Rules and Constraints
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-rules
This guide
One rule and one constraint, end to end: where each is created, how the engine applies it, what arrives in the browser, and what — if anything — you write. Plus the one case where the frontend adds a constraint of its own.
Learn how to create and manage custom rules and constraints.
#### Where rules and constraints live
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-rules-1
Both are **authored in the imagine.io admin** and **evaluated by the engine** on every change. The frontend never re-derives one — it would drift from the backend's answer, and pricing and validity must have exactly one source. So “create a rule” is an admin task; what this guide covers is the browser side: the engine's answer arrives on every evaluation, and the SDK applies it for you.
| | A **rule** says | A **constraint** says |
| --- | --- | --- |
| In words | “ _when_ this is configured, _do_ that” | “this configuration is _not allowed_ ” |
| The engine's answer | effects on the response: an option hidden or greyed, a component swapped, a material set, a message, a custom event or effect | the mutation is _rejected_ — HTTP 422 with a code and a reason; nothing changes server-side |
| What the SDK does | applies every built-in effect (visibility, availability, swaps, materials, `show_message`) and routes custom ones to your handlers | rolls back the optimistic change, tells the shopper why, and fires `evaluate.rejected` |
| What you write | nothing for built-in effects; a handler for a custom event or effect type | nothing; optionally a listener to sync your own state |
#### Example 1 — A rule: “when the run has four or more wall units, tell the shopper about the bundle”
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-rules-2
Created in the admin as a rule with a `show_message` effect. There is no frontend code: the message rides on the evaluation that fired it and the SDK shows it — `display: 'toast'` as a notification (warnings and errors persist until dismissed), `'modal'` as a dialog that opens once per firing rather than nagging on every re-evaluation.
```
// What the engine sends back when the rule fires — on response.messages[]. You do not write this;
// the admin rule produces it and the SDK renders it.
{ "ruleId": 31, "text": "Bundle discount applied — 10% off wall units", "severity": "success", "display": "toast" }
// The other built-in effects need no code either. A rule that HIDES or GREYS options arrives as
// optionVisibility / optionAvailability and the sidebar follows; a custom panel reads the same
// answer through the hook — never re-derive the rule:
const { visibleOptions, optionDisabledPropsFor } = useOptionSets();
const shown = visibleOptions(set.id, getOptionsForSet(set)); // hidden by a rule → not in the list
const { disabled, disabledReason } = optionDisabledPropsFor(set.id, opt); // greyed by a rule → disabled, with the reason
// When the rule should do something the SDK has no verb for, the admin gives it a custom effect type
// or emits a named event, and you give that a meaning — see Add Custom Popups, Example 2.
```
Check it
Make the change the rule watches for. The toast appears with the admin's text and stays as long as its severity says. A hidden option disappears from the built-in sidebar _and_ from `visibleOptions()`; a greyed one shows its reason on hover. If a message never appears, the rule did not fire — check its condition in the admin, not your code.
#### Example 2 — A constraint: “a run may hold at most six units”
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-rules-3
Created in the admin as a constraint. When a seventh add arrives, the engine rejects the evaluation: **422**, a code, a reason. The SDK rolls the optimistic add back, shows the reason to the shopper, and fires `evaluate.rejected` so anything you keep in step — a cart, an analytics row — can roll back too.
```
import { on } from '@imagineio/configurator-sdk';
on('evaluate.rejected', ({ mutation, applied, code }) => {
// applied is false; mutation.type says what was attempted ('addPlacement', 'selectOption', …).
track('constraint_hit', { code, attempted: mutation?.type });
});
// The rejection body: { code: 'MAX_UNITS_EXCEEDED', errors: [{ code, message: 'A run may hold at most 6 units.' }] }
```
Sometimes the business wants a check the backend does not have yet, or one that depends on something only the browser knows. That is a **frontend constraint**: middleware that vetoes the action before the engine hears it. It is a stop-gap, not a substitute — the engine remains the authority on what is valid, and a check that matters should move to the admin.
```
import { addMiddleware, commerce, ui } from '@imagineio/configurator-sdk';
const MAX_UNITS = 6;
addMiddleware((intent, next) => {
if (intent.type === 'product.add' && commerce.readBom().lines.length >= MAX_UNITS) {
ui.notify({ type: 'warning', message: `This design is limited to ${MAX_UNITS} units` });
return { cancelled: true }; // no request is made; no evaluate.rejected either
}
return next();
});
```
Check it
Backend constraint: the add is attempted, the engine answers 422, the piece never stays, the shopper sees the reason, and your `evaluate.rejected` listener fires once with `applied: false`. Frontend constraint: the add is _not_ attempted — your toast shows, the count is unchanged, and no rejection fires because the engine was never asked.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-rules-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Where rules and constraints live | events your own team invents | how rules, events and effects reach the browser |
| Example 1 | useOptionSets() | `visibleOptions` and `optionDisabledPropsFor` — a rule's hide/grey answer, read not re-derived |
| Example 1 | registerEffectHandler(type, fn) | a rule's custom effect type, given a meaning |
| Example 1 | onBackendEvent(name, fn) | a rule's named event |
| Example 2 | on('evaluate.rejected', fn) | heard the engine's rejection; `evaluate.completed` is its counterpart |
| Example 2 | addMiddleware((intent, next) => …) | the frontend constraint — a veto before the engine is asked |
| Example 2 | commerce.readBom() | the unit count the frontend constraint checked |
| Example 2 | ui.notify({ type, message }) | told the shopper why |
| Example 1 | Add Custom Popups → when a rule fires | a rule that opens your own UI |
Guide
### Work with Placement Logic
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-placement
This guide
Two placement implementations of your own — a grid, then a wall of frames that also offers a slot for the next piece — and the placeholder anchors a shopper clicks, drawn in your colour and shape. Example 1 is the complete file; Examples 2–4 build one piece at a time.
Understand and customize how products are placed and positioned in the configurator.
#### What a strategy is
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-placement-what
The engine decides _what_ is in the run and in what order; a **placement strategy** decides _where each piece is drawn_. Out of the box the SDK arranges pieces itself — products chain side-by-side in rows, corners turn the run, and the backend supplies each row's height — and most integrations never touch any of this. Write a strategy only when your product needs a different arrangement: a grid of rugs, a circle of chairs, a wall of frames. It is a plain object with an `id` and up to three functions, and it is chosen either in code (`placement.setStrategy(id)`) or by the backend — a system whose placement id matches one you registered uses yours, with no code at all.
| Function | Called | Returns | Units |
| --- | --- | --- | --- |
| `computeLayout(pieces, ctx)` | every render, with the scene pieces in placement order | one `{ position, rotation }` per piece, same order | metres; rotation in **radians** |
| `computeTargets(pieces, ctx)` | while a product is held on the cursor (`products.anchor`) | the candidate spots: `{ id, position, rotation, footprint, valid?, reason?, meta }[]` | metres; rotation in **degrees** |
| `resolveTarget(target, ctx)` | when the shopper clicks a spot | optional — what the click means. The default builds a `product.add` from the target (product, `anchor`, transform); write your own only to add fields | — |
`ctx` carries `getProduct(piece)` and `getDims(piece)` (metres, from the rendered geometry), and for targets the `candidate` being placed and the final `layout`. `placement.kit` has the arithmetic the built-ins use — `dimsOf`, `chain`, `gapCentres`, `toDegrees` — so a strategy is usually short. Example 1 is the complete file; Examples 2–3 build one up piece by piece.
Two gotchas
**The SDK ships no tile.** With no `placement.registerTargetRenderer(C)`, candidate spots are neither drawn nor clickable — drawing is yours; hit-testing and validity stay ours. And a renderer is only half of it: **no built-in strategy implements `computeTargets`**, so on a stock configurator there are no candidate spots for it to draw. Registering a renderer alone shows nothing, and nothing is logged — you need a strategy supplying targets too (Example 1).
**Footprints: metres vs inches.** `ctx.getDims()` is measured metres; the catalog `width` is inches (×0.0254). A constant gap overlaps pieces — a module is ~0.9 m wide.
#### Example 1 — The modular run: an insertion slot between every piece
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-placement-1
One self-contained file — the full modular arrangement that opens an insertion slot between every piece, **plus the tile renderer that makes the slots visible**. All three registrations (strategy, activation, renderer) live at the bottom, so importing this one file is the whole setup. It contains JSX, so name it `placement-lab.jsx`.
**`placement-lab.jsx` the **modular** strategy — an insertion slot between every piece (computeTargets + relational anchors), with its tile renderer**
```
import React from 'react';
import { placement } from '@imagineio/configurator-sdk';
// Footprint of a piece in METRES. Two sources, in this order: the MEASURED GLB
// (ctx.getDims — already metres, authoritative), else the catalog width/depth, which are
// INCHES and must be converted. Getting this wrong is what flings a run apart.
const IN_TO_M = 0.0254;
function dimsOf(inst, ctx = {}) {
const id = inst?.productId ?? inst?.variantId ?? inst;
const measured = ctx.getDims?.(id);
const product = ctx.getProduct?.(id);
const catalogW = product?.width > 0 ? product.width * IN_TO_M : 0.9;
const catalogD = product?.depth > 0 ? product.depth * IN_TO_M : 0.9;
return {
width: measured?.width > 0 ? measured.width : catalogW,
depth: measured?.depth > 0 ? measured.depth : catalogD,
};
}
const RAD_TO_DEG = 180 / Math.PI;
// One candidate tile. rotation is DEGREES here (the layout half uses radians), so the tile
// aligns with the leg it sits on — matters on the second arm of an L.
function mkTile(index, position, heading, incoming, anchorId) {
return {
id: `slot-${index}`,
position,
rotation: [0, -heading * RAD_TO_DEG, 0],
footprint: { width: incoming.width, depth: incoming.depth },
// WHERE it lands, expressed RELATIONALLY: "before the head" or "after this piece".
anchor: { placementId: anchorId, edge: index === 0 ? 'start' : 'after' },
meta: { index },
};
}
// Lay the run AND find the slot centres in one walk, so a tile can never drift from where a
// piece will actually land. `ctx.openSlots` is the SDK saying "tiles ARE the add UI" — only
// then do we widen the run to open a gap the candidate's width wide at each insertion point.
function slotsFor(pieces, ctx = {}) {
const incoming = ctx.candidate && ctx.openSlots !== false
? dimsOf({ productId: ctx.candidate.variantId ?? ctx.candidate.productId }, ctx) : null;
const slotW = incoming ? incoming.width : 0;
const layout = [], slots = [];
let cursor = 0;
if (slotW) { slots.push({ centre: cursor + slotW / 2, index: 0 }); cursor += slotW; } // before the first
pieces.forEach((inst, i) => {
const { width } = dimsOf(inst, ctx);
layout.push({ position: [cursor + width / 2, 0, 0], rotation: [0, 0, 0] });
cursor += width;
if (slotW) { slots.push({ centre: cursor + slotW / 2, index: i + 1 }); cursor += slotW; } // after each
});
return { layout, slots, incoming, total: cursor };
}
const modular = {
id: 'lab-modular',
label: 'modular run + insertion slots',
// HALF 1 — where existing pieces are DRAWN (radians). Opens gaps when a piece is armed.
computeLayout(pieces, ctx = {}) {
return slotsFor(pieces, ctx).layout;
},
// HALF 2 — where a NEW piece may go: one tile per gap, read off ctx.layout (the geometry
// actually RENDERED, including any corner the SDK corrected — walking it ourselves would
// send tiles marching off through empty floor).
computeTargets(pieces, ctx = {}) {
const laid = Array.isArray(ctx.layout) && ctx.layout.length === pieces.length ? ctx.layout : null;
const incoming = ctx.candidate
? dimsOf({ productId: ctx.candidate.variantId ?? ctx.candidate.productId }, ctx) : null;
if (!incoming) return []; // nothing armed -> no slots
if (!laid) { // bare call, no layout in ctx -> our own walk
const { slots } = slotsFor(pieces, ctx);
return slots.map((s) => mkTile(s.index, [s.centre, 0, 0], 0, incoming, pieces[s.index - 1]?.id ?? null));
}
const out = [], half = incoming.width / 2;
laid.forEach((entry, i) => {
const p = entry.position || [0, 0, 0];
const heading = -(entry.rotation?.[1] ?? 0); // computeLayout emits -heading
const dx = Math.cos(heading), dz = Math.sin(heading);
const back = dimsOf(pieces[i], ctx).width / 2 + half;
// the gap the layout opened in front of this piece...
out.push(mkTile(i, [p[0] - dx * back, p[1] ?? 0, p[2] - dz * back], heading, incoming, pieces[i - 1]?.id ?? null));
// ...and one past the last piece, to extend the run.
if (i === laid.length - 1)
out.push(mkTile(i + 1, [p[0] + dx * back, p[1] ?? 0, p[2] + dz * back], heading, incoming, pieces[i]?.id ?? null));
});
return out;
},
// What picking a tile MEANS. Note the anchor is RELATIONAL — never put a slot index in
// `sequence` (that field is a backend sort key; an array index lands the piece anywhere).
resolveTarget(target, ctx) {
return {
type: 'product.add',
productId: ctx?.candidate?.productId ?? null,
variantId: ctx?.candidate?.variantId ?? ctx?.candidate?.productId ?? null,
anchor: target.anchor ?? null,
transform: { position: target.position, rotation: target.rotation },
meta: target.meta ?? null,
};
},
};
/* ── TILE RENDERER — REQUIRED. The SDK ships no tile of its own: without one registered,
* arming falls back to plain append and nothing is ever drawn, so the strategy above looks
* completely dead. The SDK positions/rotates the parent group and owns hit-testing; this
* component just draws at the LOCAL origin. `state` is 'idle' | 'hovered' | 'invalid'. */
const VALID = '#00d3a7';
const HOVER = '#7c5cff';
const INVALID = '#e5484d';
const colourFor = (state) => (state === 'invalid' ? INVALID : state === 'hovered' ? HOVER : VALID);
function SlotTile({ target, state }) {
const w = target?.footprint?.width > 0 ? target.footprint.width : 0.6;
const d = target?.footprint?.depth > 0 ? target.footprint.depth : 0.6;
const r = Math.max(w, d) / 2;
const colour = colourFor(state);
return (
{/* faint fill so the spot reads as an area, not just an outline */}
);
}
/* ── WIRE ALL THREE. Registration is a module side effect: importing this file once
* (before the configurator boots) is all the host has to do. */
placement.registerStrategy(modular);
placement.setStrategy('lab-modular');
placement.registerTargetRenderer(SlotTile);
// Now clicking a product in the sidebar arms it and a tile appears in EVERY gap —
// pick one and the piece inserts exactly there.
```
One import wires it all up. Registration is a side effect of the module, so import the file once at the top of your entry file (`main.jsx`) — a top-level import there guarantees it runs before the configurator boots:
```
// main.jsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import './placement-lab.jsx'; // ← registers the strategy + activates it + registers the tile renderer
```
Heads-up
A backend `system.placementStrategy` **beats** the runtime `setStrategy` override. If your system payload ships a strategy id, `lab-modular` will not activate until the backend clears that field or selects `lab-modular` itself.
#### Example 2 — A grid
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-placement-2
Three across, then a new row. Only `computeLayout` — this strategy draws, and adding still appends to the run through the sidebar as before.
```
import { placement } from '@imagineio/configurator-sdk';
placement.registerStrategy({
id: 'showroom-grid', label: '3-up grid',
computeLayout(pieces, ctx) {
const gapX = 1.0, gapZ = 1.2; // or from ctx.getDims(piece).width + 0.1
return pieces.map((_, i) => ({ position: [(i % 3) * gapX, 0, Math.floor(i / 3) * gapZ], rotation: [0, 0, 0] }));
},
});
placement.setStrategy('showroom-grid'); // or leave it to the backend: a system whose placement id is 'showroom-grid' picks it up
```
Check it
Three pieces sit at x = 0, 1, 2 m — `scene.readBounds()` reads their positions back. `placement.listStrategies()` now returns your id — it lists **host registrations only**, so the five built-ins never appear in it and their absence is not a sign anything failed; `placement.clearStrategy()` hands control back to the backend's choice. Registering the same id again replaces it (last wins); a strategy without `computeLayout` is rejected and never throws.
#### Example 3 — A wall of frames: the strategy, and the anchor you draw
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-placement-3
Two frames per row, rows stacked upward — and, because this one also implements `computeTargets`, holding a product (`products.anchor`) shows one spot: the next empty cell. There is no `resolveTarget`: the target carries a _relational_ anchor (“after the last piece”) and the SDK's default turns the click into the engine add. **Now the placeholder itself.** There is deliberately no built-in tile — a spot marker is a brand decision. Register one renderer and every strategy's targets use it. It is R3F code drawn at the **local origin**: the SDK positions and turns the group for you, tracks hover, and blocks clicks on invalid spots. You get `target` (its footprint, reason, meta) and `state` — `'idle'`, `'hovered'` or `'invalid'`. One file, one paste — all three registrations live at the bottom of the block.
```
import { Html } from '@react-three/drei'; // peer dependency — for the reason label
import { placement } from '@imagineio/configurator-sdk';
// ── 1. the strategy: where pieces sit, and where the next one may go ──
const COLS = 2, GAP_X = 1.0, GAP_Y = 0.8; // two per row, rows 0.8 m apart, upward
const cell = (i) => [(i % COLS) * GAP_X, Math.floor(i / COLS) * GAP_Y, 0];
placement.registerStrategy({
id: 'gallery-wall', label: 'Wall of frames',
computeLayout(pieces) {
return pieces.map((_, i) => ({ position: cell(i), rotation: [0, 0, 0] })); // radians
},
computeTargets(pieces, ctx) {
if (!ctx.candidate) return []; // nothing held → nothing to offer
const { width, depth } = placement.kit.dimsOf(ctx.candidate, ctx); // the tile is the size of the incoming piece
const last = pieces[pieces.length - 1];
return [{
id: 'next-cell', position: cell(pieces.length), rotation: [0, 0, 0], footprint: { width, depth },
anchor: last ? { placementId: last.id, edge: 'after' } : null, // "after the last piece" — relational, never an index
}];
},
// No resolveTarget. The default builds the add from the target: product, anchor, transform.
});
// ── 2. the placeholder: yours to draw. Local origin — the SDK positions the group. ──
placement.registerTargetRenderer(({ target, state }) => {
const r = Math.min(target.footprint.width, target.footprint.depth) / 2;
const color = state === 'invalid' ? '#e5484d' : state === 'hovered' ? '#f5a524' : '#0b7285'; // your palette
return (
{/* a ring on the floor … */}
{state === 'invalid' && target.reason && ( // … and why, when it is off-limits
{target.reason}
)}
);
});
// A footprint outline instead of a ring: on the same mesh.
// Return null to hide a spot entirely (it stays un-pickable) — the right way to hide a rejected one.
// ── 3. switch it on (a backend placement id, if the system ships one, wins over this) ──
placement.setStrategy('gallery-wall');
```
Check it
Switch to `gallery-wall`: two pieces on the first row, the third above them. Hold a product — `products.anchor({ productId, variantId })`, or click one in the sidebar — and a teal ring appears at the next empty cell, amber under the cursor, red with a reason where a strategy says no. Click it: the SDK resolves the anchor against the current run to an engine `sequence`, dispatches the same `product.add` intent the sidebar uses (so your middleware applies), and the ring goes. To offer several cells — every empty cell of a fixed grid, say — return one target per cell, with `valid: false` and a `reason` on the ones a rule forbids: they are shown but inert, and the engine is never asked. Registering the renderer after the scene mounted repaints immediately; you do not have to register before boot.
Not seeing it?
Three usual causes. **Nothing is drawn** — there is no built-in tile; register a renderer (the second half above) or the spots exist but are invisible. **Your strategy is not the active one** — `placement.listStrategies()` must include it, and a backend `system.placementStrategy` id _beats_ `setStrategy`, so on a system that ships one either clear it in the admin or select yours there. **The spot is offered but the piece appends** — the anchor's `placementId` was not found in the run (stale after a change) and the SDK falls back to append rather than guess; derive anchors from the `pieces` you were just given, not from state you cached.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-placement-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Examples 1–3 | placement.registerStrategy({ id, computeLayout, computeTargets?, resolveTarget? }) | both implementations |
| Examples 1–3 | placement.setStrategy(id) | chose one in code; the backend's placement id chooses it with none |
| Example 2 | placement.listStrategies() | your registered ids — host registrations only; built-ins are not listed |
| Example 2 | placement.clearStrategy() | back to the backend's choice |
| Examples 1, 3 | placement.computeTargets(pieces, ctx) | what the SDK calls on your strategy while a product is held |
| Example 1 | placement.resolveTarget(target, ctx) | the click, when the default descriptor is not enough; Example 3 relies on the default |
| Examples 1, 3 | products.anchor({ productId, variantId }) | held a product so the slots appeared; products.unanchor() cancels |
| Examples 1, 3 | placement.registerTargetRenderer(({ target, state }) => …) | the placeholder anchors, in your colour and shape |
Guide
### Customize the Loading Screen
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-loader
This guide
The screen a shopper sees while the configurator boots — restyled, then replaced with your own.
Customize the loading screen to match your brand and improve user experience.
The loading screen is a component like the sidebar or the toolbar: `ui.registerComponent('LoadingScreen', …)` replaces **every** loading UI the SDK shows, because they are all one component: the full-page boot overlay that `mount()` shows from first paint until the scene is ready (its `detail` line reads “Loading products… 3/12” while the 3D assets arrive), the busy veil during engine round-trips and `ui.setLoading`, the chat panel while it loads, and the embed route's loader. Yours receives the same props ours does: `message`, `detail`, `progress` (0–100 or undefined when unknown), `overlay` (true for the boot screen), `compact` (true for the in-context pill — the busy veil and panels loading in place; render a small one-line form), and `Default` — ours, to wrap. Register it **before** `mount()`: the boot screen is the first thing painted.
#### Example 1 — Restyle ours
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-loader-1
Keep our screen, change its words and look. Wrap `Default`, or don't touch it at all and let the theme do it — `--color-bg`, `--color-primary` and `--font-family-base` restyle the loader like everything else.
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('LoadingScreen', ({ Default, message, ...rest }) => (
{/* your wrapper — a logo above ours */}
));
```
Check it
Reload: our spinner and progress, under your logo, with your words. Nothing else changed — the product-loading phase updates the same screen's `detail` and `progress`, so it is branded too.
#### Example 2 — Replace it
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-loader-2
Ignore `Default` and render your own. The props tell you what to say and which form to take: `overlay` is `true` for the full-page boot screen (ours also renders inline, without it, when placed by hand in a custom layout); `compact` is `true` for the small in-context form — the busy veil during engine round-trips and a panel loading in place — so render a one-line pill there, not a page. Two files: the component, and the CSS it now needs.
```
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('LoadingScreen', ({ message, detail, progress, overlay, compact }) => {
// compact = the small in-context form: the busy veil during engine round-trips, a panel loading in place.
if (compact) return {message};
// Otherwise the full page. overlay is true for the boot screen; false when you place it by hand in a layout.
return (
NORDHUS
{message}
{typeof progress === 'number' && } {/* undefined while the size is unknown */}
{detail && {detail}} {/* "3 of 12 products" — ours, optional */}
);
});
```
The CSS is not optional
Replacing a component replaces its _markup_. Our stylesheet only knows the built-in's `.loading-screen*` classes, so an override with its own class names renders with no background, no size and no `z-index` — in normal flow, under the scene canvas, where it reads as “nothing happened”. The page form must pin itself full-viewport above the canvas; the pill must stay small and in flow. This stylesheet does both, on theme tokens:
```
/* Replacing an SDK component replaces its MARKUP. The SDK stylesheet only styles the built-in's
.loading-screen* classes, so an override with its own class names starts with ZERO CSS: it
renders in normal flow, no background, no z-index — under the scene canvas that reads as
"nothing happened". These rules restore what the built-in got for free, per variant.
Theme tokens throughout, so it follows the active theme / sales-channel palette. */
.nord-loader {
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
gap: var(--spacing-sm, 8px);
height: 100%;
background: var(--bg-primary, #fff);
color: var(--text-primary, #111);
font-family: inherit;
}
/* overlay — the boot loader. Without position / inset / z-index the override paints in flow
and the canvas covers it. This is the rule whose absence makes the override look like a no-op. */
.nord-loader--page {
position: fixed;
inset: 0;
width: 100%;
height: 100%;
z-index: 10000;
}
.nord-loader__mark {
font-size: 13px;
font-weight: 600;
letter-spacing: 0.28em;
text-transform: uppercase;
opacity: 0.75;
}
.nord-loader p { margin: 0; font-size: 14px; }
.nord-loader small { opacity: 0.6; font-size: 12px; }
.nord-loader progress {
width: 180px;
height: 4px;
border: 0;
border-radius: 999px;
accent-color: var(--color-primary, #111);
}
/* compact — the busy veil (EvaluatingOverlay) and the chat panel loading in place.
In flow, small, one line: must NOT be full-viewport. */
.nord-loader--pill {
display: inline-flex;
align-items: center;
gap: 8px;
height: auto;
padding: 6px 14px;
border-radius: 999px;
background: var(--bg-secondary, #f4f4f5);
color: var(--text-primary, #111);
font-size: 13px;
box-shadow: 0 2px 10px rgb(0 0 0 / 12%);
}
.nord-loader--pill::before {
content: '';
width: 12px;
height: 12px;
border: 2px solid currentcolor;
border-right-color: transparent;
border-radius: 50%;
animation: nord-loader-spin 0.7s linear infinite;
}
@keyframes nord-loader-spin { to { transform: rotate(360deg); } }
@media (prefers-reduced-motion: reduce) { .nord-loader--pill::before { animation-duration: 2.4s; } }
```
Check it
Reload: your screen, full page, while boot runs; it disappears the moment the scene is ready. Then select a piece or pick an option: the brief busy veil shows _your_ pill, not our spinner — one component, every loader. The words are still ours — pass `message` through and translate or replace it. Return `null` and there is no loading screen at all, which is a valid choice when your own page already shows one.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-loader-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Examples 1–2 | ui.registerComponent('LoadingScreen', Impl) | replaced the loading screen everywhere it is shown; `Default` to wrap |
| Example 1 | ui.applyTheme(tokens) | the no-code route — the loader follows the theme |
| — | parts.LoadingScreen | ours, if you want to place it yourself in a custom layout |
Guide
### Adding Custom Dimension Code
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-dims
This guide
The dimension lines a shopper toggles on — first with your own label added (inches next to our metres), then replaced with your own drawing.
Add your own custom dimension code to handle specific measurement logic.
Dimensions are measured by the SDK from the _rendered_ geometry — not from catalogue numbers — so what you see is what a piece actually occupies once placed. The display is a component, `SceneDimensions`, rendered **inside the 3D canvas** and toggled by the toolbar's _Dimensions_ button. Override it with `ui.registerComponent`; yours receives `bbox` — the run's bounding box in metres: `minX maxX minZ maxZ w d height` — and `Default`, ours. Because it renders inside the canvas, it is R3F code: ` `, ` `, and drei's ` ` for text.
#### Example 1 — Imperial dimensions, drawn like ours
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-dims-1
The same two dimension lines the SDK draws — width along the front, depth along the left, end ticks, a label at the midpoint — in inches and your colour. The lines are drawn here rather than by wrapping `Default`: `Default` renders the built-in _metric_ labels, so wrapping it can only add a second label next to the metres, never replace them.
```
import { Html, Line } from '@react-three/drei'; // peer dependencies — already installed
import { ui } from '@imagineio/configurator-sdk';
// Same geometry constants the built-in overlay uses, so the lines land identically.
const Y = 0.02; // lie just above the floor
const OFF = 0.28; // push the dimension line outside the run
const TICK = 0.09; // end-tick half-length
const COLOR = '#ff0000';
const inches = (m) => `${(m * 39.3701).toFixed(1)}"`;
const labelStyle = {
padding: '2px 7px', borderRadius: 5, background: 'rgba(20, 21, 22, 0.92)',
color: '#fff', fontSize: 12, fontWeight: 600, whiteSpace: 'nowrap', pointerEvents: 'none',
};
// `Default` is deliberately NOT rendered. It draws the SDK's own metric labels, so wrapping it
// can only ADD to the metres, never replace them. Replacing means drawing the lines ourselves.
ui.registerComponent('SceneDimensions', ({ bbox }) => {
if (!bbox || !(bbox.w > 0) || !(bbox.d > 0)) return null; // nothing measured yet
const { minX, maxX, minZ, maxZ, w, d } = bbox;
const frontZ = maxZ + OFF; // width dimension runs along the front edge
const leftX = minX - OFF; // depth dimension runs along the left edge
const line = (pts, key) => ;
return (
{/* WIDTH (X span) along the front */}
{line([[minX, Y, frontZ], [maxX, Y, frontZ]], 'w')}
{line([[minX, Y, frontZ - TICK], [minX, Y, frontZ + TICK]], 'wt0')}
{line([[maxX, Y, frontZ - TICK], [maxX, Y, frontZ + TICK]], 'wt1')}
{inches(w)}
{/* DEPTH (Z span) along the left */}
{line([[leftX, Y, minZ], [leftX, Y, maxZ]], 'd')}
{line([[leftX - TICK, Y, minZ], [leftX + TICK, Y, minZ]], 'dt0')}
{line([[leftX - TICK, Y, maxZ], [leftX + TICK, Y, maxZ]], 'dt1')}
{inches(d)}
);
});
```
Check it
Click **Dimensions** in the toolbar (or `scene.toggle.dimensions()`): red lines with inch labels where the metric ones used to be. Add a piece — they follow, because `bbox` is re-measured from the geometry after every settle. To keep the metres _and_ add inches, render ` ` inside the group as well and drop your two width/depth lines.
#### Example 2 — Replace the display
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-dims-2
Ignore `Default` and draw your own — a floor outline and one label, say. Positions are metres in the scene's frame; the box's corners are the four combinations of `minX/maxX` and `minZ/maxZ`.
```
import { Html, Line } from '@react-three/drei';
import { ui } from '@imagineio/configurator-sdk';
ui.registerComponent('SceneDimensions', ({ bbox }) => {
if (!bbox || !(bbox.w > 0)) return null;
const { minX, maxX, minZ, maxZ, w, d } = bbox, y = 0.005;
const outline = [[minX, y, minZ], [maxX, y, minZ], [maxX, y, maxZ], [minX, y, maxZ], [minX, y, minZ]];
return (
{(w * 100).toFixed(0)} × {(d * 100).toFixed(0)} cm footprint
);
});
```
Check it
Toggle dimensions: a dashed footprint on the floor and a single label; none of our lines. Returning `null` hides the overlay entirely — with the toolbar button then a no-op, so hide the button too with the backend's `uiToggles` if that is what you want. Whatever you draw does not affect what the engine measures or prices — this is display only.
#### Example 3 — Dimensions outside the canvas
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-dims-3
For a panel in your own page — “Will it fit?” against a room the shopper typed — you want numbers, not a component. `scene.readBounds()` is the same measurement as data: the run's `total` and every `piece` 's world box.
```
import { scene, on } from '@imagineio/configurator-sdk';
async function refreshFit(roomWidthM) {
await scene.onSettled(); // geometry is final for this change
const { total, pieces } = scene.readBounds(); // metres; null before the scene exists
fitPanel.textContent = total.w <= roomWidthM
? `Fits: ${(total.w * 100).toFixed(0)} cm of ${roomWidthM * 100} cm`
: `${((total.w - roomWidthM) * 100).toFixed(0)} cm too wide — ${pieces.length} pieces`;
}
on('scene.ready', () => refreshFit(room.width));
for (const e of ['product.added', 'product.removed', 'option.selected', 'layout.changed']) on(e, () => refreshFit(room.width));
```
Check it
Your panel reads the same width our dimension line draws — one measurement, two displays. If you need the per-piece boxes for something (collision with the shopper's own furniture, a dimensioned export), `pieces[i].worldBox` carries `min/max` in world metres, and `placementId` ties each back to the BOM line.
#### Reference — everything this guide used
Permalink: https://configurator-platform.imagine.io/sdk/index.html#howto-dims-ref
| Used in | Function | What it did here |
| --- | --- | --- |
| Examples 1–2 | ui.registerComponent('SceneDimensions', Impl) | the dimension display — `{ bbox, Default }`, rendered inside the canvas |
| Examples 1–2 | scene.toggle.dimensions() | shows / hides it — what the toolbar button calls |
| Example 3 | scene.readBounds() | the same measurement as plain data |
| Example 3 | scene.onSettled() | waited for the geometry to be final before reading |
| Example 3 | on(event, fn) | re-read after every change that moves geometry |
| Example 2 | scene.registerRenderer(kind, Comp) | the neighbour: drawing your own _pieces_, not their measurements |
Every callable, with an example
### API reference
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fullref
Every function, hook, and component, each with a runnable example — arguments taken from the real signatures. Functions that return data also show a **Response** block — a real sample captured from a live scene — and every hook shows a **Returns** block: its exact return keys, transcribed from the source, with values from that same scene. Either way you can see every available key without trying it yourself. Pick a namespace in the sidebar, or filter below. **Where ids come from:** every catalog id in these examples (`productId`, `variantId`, `optionSetId`, `optionId`) is defined in your imagine.io catalog — your onboarding contact provides the catalog sheet — and every live payload echoes them back: each `commerce.readBom()` line, each `option.selected` event, each placement in a response carries the ids it was built from, so you can also learn them from the running configurator. `placementId` s (`'p1'`, `'p2'`, …) are minted by the engine per placed product.
#### The namespaces
Permalink: https://configurator-platform.imagine.io/sdk/index.html#api
One import, namespaced by concern. Actions group under objects; React hooks stay flat so ESLint's rules-of-hooks keeps working. A method and the event it causes share a name (`products.add` → `product.added`). Everything on this page is a named export of the one package:
```
import {
mount, boot, configure, // lifecycle
products, options, scene, ui, quote, // namespaces
placement, commerce, project, history, copilot, catalog, config,
parts, // built-in components:
useOptionSets, useToolbar, useSelection, usePrice, useLabels, // hooks, flat
on, once, onBackendEvent, // events
} from '@imagineio/configurator-sdk';
```
| Namespace | What lives there |
| --- | --- |
| `mount` · `boot` · `configure` | lifecycle — render, boot headless, register-many-with-teardown |
| `products` | placed pieces — add, move, transform, variant, select, duplicate, arm, hosted |
| `options` | select (by name or id), selectForProduct / forScene, effective |
| `scene` | camera, view (2D/3D), toggles, presets, component verbs, renderers, context |
| `ui` | theme, layouts, components, slots, routes, labels, toggles, modals, canvas-only |
| `quote` | read, templates, PDF + endpoint, generated assets (silo / lifestyle / AR) |
| `placement` | strategies, tile renderer, config, the geometry kit |
| `commerce` | BOM, metadata round-trip |
| `project` | save, load, restore, share links + tokens |
| `history` | undo / redo (+ canUndo / canRedo for your own buttons) |
| `copilot` | the AI chat — availability probe and runtime pointing |
| `catalog` · `config` | catalog lookups; API key, channel |
| `parts` | ~50 built-in components for composing a custom shell |
| `use*` (flat) | 19 hooks — useOptionSets, useToolbar, useSelection, usePrice, useLabels… |
#### Products
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-products
placementId
Most functions below take a **placement id** — the id the engine minted when the product was placed. Real ids look like `'p1'`, `'p2'`, …; the `'p1'` in these examples is a placeholder — use the id of a piece that actually exists in your scene. Get a real one from `products.getSelected()` after clicking a piece, from the `product.added` event's `placementIds`, or from `commerce.readBom().lines[i].placementId`. An id the scene doesn't know is refused by the engine (422 `INVALID_PLACEMENT_ID`) — in dev the SDK also logs which ids exist.
##### `products.add`
Place a product in the scene — an `addPlacement` round-trip; the engine validates it, assigns the placement id and sequence, and returns the whole authoritative scene. Optional: `sequence` to insert at a sort-key (omitted → appended), `placementGroup` for the row, and for a **hosted** product (one that mounts on another, e.g. an appliance on a cabinet) `hostPlacementId` + `hostVariantId` so the engine anchors it to that host. The new id arrives in the `product.added` event's `placementIds`.
```
await products.add({ productGraphId: 5, variantId: 12 }); // append to the run
await products.add({ productGraphId: 5, variantId: 12, sequence: 2 }); // insert at sort-key 2
await products.add({ productGraphId: 40, variantId: 41, hostPlacementId: 'p1', hostVariantId: 12 }); // mount on p1
```
Response — every engine mutation returns this envelope; values from a real call, one example entry per collection
```
{
"applied": true, // the engine accepted and applied the change
"rejected": false, // true on a 422 — nothing changed server-side
"resolvedState": { // the full authoritative scene AFTER the change
"systemId": 1,
"room": { "width": 4, "depth": 3.5, "height": 2.7 },
"selections": { "1": 65, "2": 12 }, // scene-level optionSetId → optionId
"placements": [
{
"id": "p1",
"variantId": 9,
"variantName": "Single Door 9\"",
"productGraphName": "Base Cabinet",
"placementGroup": "floor",
"sequence": 0,
"transform": { "position": [0, 0, 0], "rotation": [0, 0, 0] },
"selections": { }, // this placement's own picks
"bindings": [ ] // option sets bound to it
}
// … one entry per placed product
]
},
"removedPlacements": null, // or [{ id, variantId, reason }] when a rule cascade-removed pieces
"addedPlacements": null, // or [{ id, variantId, reason }] when a rule auto-added one
"optionAvailability": { "13": { "74": false } }, // options a rule just disabled
"warnings": [], "messages": [], "events": [],
"pricing": { // authoritative — echoed on every response
"currency": "USD",
"grandTotal": 22661,
"placements": {
"p1": { "basePrice": 489, "unitPrice": 824, "adjustments": [ ] },
"p7__host": { "basePrice": 489, "unitPrice": 824, "hostOf": "p7" } // engine-billed host cabinet
// … one entry per placement
},
"aggregateAdjustments": []
}
}
```
##### `products.remove`
Remove a placed product by id.
```
products.remove('p1'); // remove a placed product by id
```
Response — the standard evaluate envelope (full live sample under products.add)
```
{
"status": 200, // 200 applied · 422 rejected (nothing changed)
"applied": true,
"rejected": false,
"resolvedState": { "placements": ["…"] }, // the full authoritative scene
"removedPlacements": ["…"], // pieces the engine removed (cascades)
"addedPlacements": ["…"], // pieces the engine auto-added (rules)
"warnings": [], "messages": [],
"pricing": { "currency": "USD", "grandTotal": 22661, "placements": { "…": "…" } }
}
```
##### `products.move`
**Reorder** a placed product within its run by giving it a new sort-key `sequence` — the engine re-lays the run out and may snap the value (a tall unit to the run edge), so re-read it from the response. `placementGroup` only when moving to another row; `position` / `rotation` may ride along. For a one-step reorder use `products.moveLeft()` / `moveRight()`. Called _without_ `sequence` but with a `position` / `rotation`, it behaves as `products.transform` (free-movable pieces, no engine call).
```
// Reorder: put the piece at sort-key 2 (sequences are sort keys — gaps are fine)
await products.move({ placementId: 'p1', sequence: 2 });
```
Response — the standard evaluate envelope (full live sample under products.add)
```
{
"status": 200, // 200 applied · 422 rejected (nothing changed)
"applied": true,
"rejected": false,
"resolvedState": { "placements": ["…"] }, // the full authoritative scene
"removedPlacements": ["…"], // pieces the engine removed (cascades)
"addedPlacements": ["…"], // pieces the engine auto-added (rules)
"warnings": [], "messages": [],
"pricing": { "currency": "USD", "grandTotal": 22661, "placements": { "…": "…" } }
}
```
##### `products.transform`
Set a **free-movable** product's position (metres) and rotation (degrees) directly — exactly what the drag gizmo does. Local only: no engine round-trip, and it persists with the scene state. Applies to pieces the catalog flags `movable` that aren't host-anchored; a piece inside a run is positioned by its `sequence`, so use `products.move` for those (the SDK logs a warning in dev if you try). Returns `null` if the id isn't a placement in the scene.
```
products.transform('p1', [1.2, 0, 0], [0, 90, 0]); // metres, degrees
// → { placementId: 'p1', position: [1.2, 0, 0], rotation: [0, 90, 0], freeMovable: true }
// freeMovable:false means the piece is in a run — the layout will override this on screen
```
Response
```
{
"placementId": "p1",
"position": [1.2, 0, 0], // metres
"rotation": [0, 90, 0], // degrees
"freeMovable": true // false → in a run; use products.move({ sequence })
}
```
##### `products.changeVariant`
Swap a placed product's variant in place (e.g. a base unit for its wider variant). The engine re-evaluates: rules that depend on the variant re-fire and per-variant option availability is recomputed. Takes an object — the positional `(placementId, variantId)` form is accepted too.
```
await products.changeVariant({ placementId: 'p1', variantId: 88 });
// also accepted: products.changeVariant('p1', 88)
```
Response — the standard evaluate envelope (full live sample under products.add)
```
{ "status": 200, "applied": true, "rejected": false, "resolvedState": { "…": "…" }, "pricing": { "…": "…" } }
// 422 → { applied: false, rejected: true, code: 'INVALID_PLACEMENT_ID' | … } — nothing changed
```
##### `products.select`
Select a placed product.
```
products.select('p1'); // select a placed product
```
##### `products.deselect`
Clear the current product selection — the one `products.select` (or a click) set. The selection panel closes and `selection.changed` fires with `placementId: null`.
```
products.deselect(); // nothing selected afterwards
products.getSelected(); // → null
```
##### `products.getSelected`
The **placement id** of the currently selected product (a string like `'p1'`), or `null` when nothing is selected. This is the id every other `products.*` call wants.
```
const id = products.getSelected(); // 'p1' | null
if (id) await products.changeVariant({ placementId: id, variantId: 88 });
```
Response — real sample from a live scene · `products.getSelected()`
```
"p1"
```
##### `products.moveLeft`
Move the **selected** piece one slot left in its run — the same thing the selection panel's button does (a reorder round-trip; the engine re-sequences). Select first. Resolves to `true` when dispatched, `false` when nothing is selected or the piece can't move (already at the start, or a free-movable piece — drag those / use `transform`).
```
products.select('p1');
await products.moveLeft(); // true — or false: "Already at the start"
```
##### `products.moveRight`
Move the **selected** piece one slot right in its run. Same contract as `moveLeft`: select first; resolves to `true` / `false`.
```
products.select('p1');
await products.moveRight(); // true — or false: "Already at the end"
```
##### `products.duplicate`
Duplicate the **selected** piece: an `addPlacement` round-trip for the same product, inserted at the selected piece's position in the run (the engine assigns the new piece's sequence). Resolves to `false` when nothing is selected or the piece is a run end (only one allowed).
```
products.select('p1');
await products.duplicate(); // true → a product.added event follows with the new placementId
```
##### `products.deleteSelected`
Delete the **selected** piece — a `removePlacement` round-trip, confirm-then-commit: the piece disappears only when the engine applies it, and stays (with a toast) if a rule blocks the removal. Resolves to `false` when nothing is selected. For a piece by id use `products.remove(id)`.
```
products.select('p1');
await products.deleteSelected(); // true → product.removed fires once the engine confirms
```
##### `products.anchor`
Hold a product on the cursor so the USER picks its spot — step one of click-to-place. Nothing is added yet: the scene opens insertion tiles/"+" gaps, and the click places it (validated server-side).
```
products.anchor({ productId: 5, variantId: 12 });
// scene shows the insertion spots — the user's click completes the add
```
##### `products.unanchor`
Cancel the held product (close the insertion tiles without placing).
```
products.unanchor(); // cancel the held product (close the insertion tiles without placing)
```
##### `products.getAnchored`
The product currently held for placement, or null.
```
const anchored = products.getAnchored(); // the product currently held for placement, or null
```
Response — real sample from a live scene · `products.getAnchored()`
```
{
"productId": 9,
"variantId": 9,
"name": "sample"
}
```
##### `products.anchorHosted`
Hold a HOSTED product (one that mounts on another product, e.g. an appliance on a cabinet): compatible host slots highlight and the click places it on the chosen host.
```
// Pass the catalog product record — the SDK reads the name and 3D model from it:
products.anchorHosted(product);
// Only have an id? Supply what the record would have carried:
products.anchorHosted(productId, { name: 'Oven', modelUrl });
```
##### `products.unanchorHosted`
Cancel a held hosted product.
```
products.unanchorHosted(); // cancel a held hosted product
```
#### Options
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-options
##### `options.select`
Select an option — by id, by name, or set+option. Scope follows focus: a selected product takes the pick for itself; nothing selected applies it scene-wide. Ambiguous names refused, not guessed. Returns true when applied.
```
options.select('Fabric', 'Cognac'); // by name — or select(752), or select(75, 752)
```
Response
```
true // the option resolved and was dispatched
// false/undefined — unknown, ambiguous, or unavailable (nothing sent)
// NOTE: a backend rule can still veto it afterwards — listen for the
// 'evaluate.rejected' event to roll external state back
```
##### `options.selectByIds`
Same as select, with the explicit (optionSetId, optionId) pair — and the same scoping: applies to the currently selected product, or scene-wide when nothing is selectedy selected product, or scene-wide when nothing is selected. Use selectForProduct / selectForScene to force a scope.
```
options.selectByIds(75, 752); // same as select, with the explicit (optionSetId, optionId) pair - and the same scoping: applies to the currently selected product, or scene-wide when nothing is selected
```
Response
```
true // the option resolved and was dispatched
// false/undefined — unknown, ambiguous, or unavailable (nothing sent)
// NOTE: a backend rule can still veto it afterwards — listen for the
// 'evaluate.rejected' event to roll external state back
```
##### `options.selectForProduct`
Select an option scoped to one placed product.
```
options.selectForProduct('p1', 75, 752); // select an option scoped to one placed product
```
Response — the standard evaluate envelope (full live sample under products.add)
```
{
"status": 200, // 200 applied · 422 rejected (nothing changed)
"applied": true,
"rejected": false,
"resolvedState": { "placements": ["…"] }, // the full authoritative scene
"removedPlacements": ["…"], // pieces the engine removed (cascades)
"addedPlacements": ["…"], // pieces the engine auto-added (rules)
"warnings": [], "messages": [],
"pricing": { "currency": "USD", "grandTotal": 22661, "placements": { "…": "…" } }
}
```
##### `options.selectForScene`
Select a scene-wide option.
```
options.selectForScene(10, 101); // select a scene-wide option
```
Response — the standard evaluate envelope (full live sample under products.add)
```
{
"status": 200, // 200 applied · 422 rejected (nothing changed)
"applied": true,
"rejected": false,
"resolvedState": { "placements": ["…"] }, // the full authoritative scene
"removedPlacements": ["…"], // pieces the engine removed (cascades)
"addedPlacements": ["…"], // pieces the engine auto-added (rules)
"warnings": [], "messages": [],
"pricing": { "currency": "USD", "grandTotal": 22661, "placements": { "…": "…" } }
}
```
#### Scene
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-scene
##### `scene.applyPreset`
Swap the whole scene to a layout preset (server-side): the engine replaces the current placements with the preset’s, re-runs rules and pricing, and the result renders. Current placements are gone after this — it is a layout change, not a merge.
```
await scene.applyPreset(2); // a preset id — the scene configurations defined for your system
// Where the ids come from: `const { sceneConfigurations } = await load(systemId)` → { 1: { id: 1, name: 'Straight' }, 2: { id: 2, name: 'L Shaped' } }
```
Response — the standard evaluate envelope (full live sample under products.add)
```
{
"status": 200, // 200 applied · 422 rejected (nothing changed)
"applied": true,
"rejected": false,
"resolvedState": { "placements": ["…"] }, // the full authoritative scene
"removedPlacements": ["…"], // pieces the engine removed (cascades)
"addedPlacements": ["…"], // pieces the engine auto-added (rules)
"warnings": [], "messages": [],
"pricing": { "currency": "USD", "grandTotal": 22661, "placements": { "…": "…" } }
}
```
##### `scene.setRoomDimensions`
Set the room size in METRES, validated server-side: the engine re-evaluates the scene against the new box (a room too small for the current layout is refused, not clipped). Rapid calls (e.g. a slider) are coalesced into one request. Positional arguments — width, depth, height.
```
scene.setRoomDimensions(4.2, 3.0, 2.7); // width, depth, height — metres
```
Response — the standard evaluate envelope (full live sample under products.add)
```
{
"status": 200, // 200 applied · 422 rejected (nothing changed)
"applied": true,
"rejected": false,
"resolvedState": { "placements": ["…"] }, // the full authoritative scene
"removedPlacements": ["…"], // pieces the engine removed (cascades)
"addedPlacements": ["…"], // pieces the engine auto-added (rules)
"warnings": [], "messages": [],
"pricing": { "currency": "USD", "grandTotal": 22661, "placements": { "…": "…" } }
}
```
##### `scene.setRoomFootprint`
Pin the room’s floor plan (width × depth, metres) LOCALLY — no request fires now; the footprint rides along on the next change the engine evaluates. Use it to stage a size before other edits; use setRoomDimensions for an immediate validated resize (and for height).
```
scene.setRoomFootprint({ width: 4.2, depth: 3.0 }); // metres, applied with the next evaluate
```
##### `scene.reset`
Clear the scene locally — every placed product, per-product overrides and the selection are dropped, leaving an empty room. Nothing is sent to the engine and nothing saved is touched; load a preset (scene.applyPreset) or restore a save to fill it again.
```
scene.reset(); // empty scene — does not affect saved projects
```
##### `scene.camera.reset`
Reset the camera to default.
```
scene.camera.reset(); // reset the camera to default
```
##### `scene.camera.preset`
Move the camera to an explicit pose — position and look-at target in metres, optional field of view (default 45°). Takes the pose object itself, not a name.
```
scene.camera.preset({ position: [0, 1.6, 4.5], target: [0, 0.8, 0], fov: 40 }); // animates there (metres; fov optional)
scene.camera.preset({ position: [3, 2, 3], target: [0, 0.8, 0], instant: true }); // snap, no animation
```
##### `scene.camera.focusOn`
Frame the camera on a placed product. Pass the placement id — the SDK measures the piece off the live scene (centre, size, facing) and animates there. Returns `false` if that id is not rendered yet (scene not mounted, model still loading, unknown id) and leaves the camera alone.
```
scene.camera.focusOn('p3'); // frame placement 'p3' — that's it
// Ids come from scene.readBounds().pieces[].placementId — or useProducts() in React
const first = scene.readBounds()?.pieces?.[0]; // null before the scene is up
const ok = first && scene.camera.focusOn(first.placementId);
if (!ok) setTimeout(() => scene.camera.focusOn('p3'), 3000); // piece not rendered yet — and on initial
// load the SDK's own scene framing fires when
// onSettled() resolves, overriding a focus made
// there; wait it out instead
// Advanced: an explicit world point + bounding radius (metres) + facing (radians)
scene.camera.focusOn([1.2, 0.45, -0.3], 1.5);
```
##### `scene.view.toggle`
Switch between the 3D perspective view and the 2D top-down plan view — same button as the toolbar’s 2D/3D toggle.
```
scene.view.toggle(); // 2D ⇄ 3D
```
##### `scene.view.is3D`
True if the view is 3D.
```
if (scene.view.is3D()) { /* ... */ } // true if the view is 3D
```
Response — real sample from a live scene · `scene.view.is3D()`
```
true
```
##### `scene.view.to2D`
Switch to the 2D top-down view.
```
scene.view.to2D(); // switch to the 2D top-down view
```
##### `scene.view.to3D`
Switch to the 3D perspective view.
```
scene.view.to3D(); // switch to the 3D perspective view
```
##### `scene.toggle.dimensions`
Toggle dimension labels.
```
scene.toggle.dimensions(); // toggle dimension labels
```
##### `scene.toggle.walls`
Toggle wall visibility.
```
scene.toggle.walls(); // toggle wall visibility
```
##### `scene.readBounds`
Render-truth geometry as plain data — { total, pieces: [{ placementId, productId, worldBox, localBox, matrixWorld }] }. Null before the scene exists.
```
await scene.onSettled();
const { total, pieces } = scene.readBounds();
// total.w/h/d — the whole run; pieces[i].worldBox — one placement's box
```
Response — real sample from a live scene · `scene.readBounds()`
```
{
"total": {
"min": [
-0.06761482591448242,
// … 2 more items like the one above
],
"max": [
5.346166708034596,
// … 2 more items like the one above
],
"w": 5.413781533949078,
"h": 2.9049360156059265,
"d": 3.624380117261593
},
"pieces": [
{
"placementId": "p1",
"productId": 9,
"worldBox": {
"min": [
-0.0040000006556510925,
// … 2 more items like the one above
],
"max": [
0.23259999603033066,
// … 2 more items like the one above
],
"w": 0.23659999668598175,
"h": 0.9778000116348267,
"d": 0.6188700199127197
},
"localBox": {
"min": [
-0.0040000006556510925,
// … 2 more items like the one above
],
"max": [
0.23259999603033066,
// … 2 more items like the one above
],
"w": 0.23659999668598175,
"h": 0.9778000116348267,
"d": 0.6188700199127197
},
"matrixWorld": [
1,
// … 15 more items like the one above
]
},
// … 27 more items like the one above
]
}
```
##### `scene.onSettled`
Resolves (or calls fn) once pending models are decoded + measured and the scene goes quiet.
```
await scene.onSettled(); // or scene.onSettled(() => measureNow())
```
##### `scene.onReady`
Reach the raw scene. Your function receives `{ THREE, scene, camera, renderer, invalidate, registerDisposable }` once the scene exists — immediately if it already does, so registration order does not matter. **Unversioned surface**: whatever you add is yours to remove — hand a disposer to `registerDisposable` or return one, and the SDK calls it on teardown. The canvas renders _on demand_: anything you animate must call `invalidate()` each tick or nothing repaints. Available when your organisation is entitled to scene access (`exposeThreejsScene`); otherwise your function is never called.
```
const off = scene.onReady(({ THREE, scene, invalidate, registerDisposable }) => {
const marker = new THREE.Mesh(new THREE.SphereGeometry(0.05), new THREE.MeshBasicMaterial({ color: 0xff0000 }));
scene.add(marker); invalidate();
registerDisposable(() => scene.remove(marker)); // or: return () => scene.remove(marker)
});
```
##### `scene.registerRenderer`
Register a custom renderer for a component key.
```
scene.registerRenderer('cushion', MyCushionMesh); // register a custom renderer for a component key
```
##### `scene.registerMaterial`
Register a material resolver.
```
scene.registerMaterial((id, ctx) => id === 'velvet' ? myVelvet : null); // register a material resolver
```
##### `scene.registerInteraction`
Replace or wrap what a scene interaction MEANS. The handler gets `Default` — our own behaviour — so it can adjust the result instead of reimplementing it. Call `Default()` to keep the built-in behaviour; skip it to suppress it. Returns an unregister function; last registration per kind wins; a handler that throws falls back to the default rather than breaking the scene.
**The two kinds you can register.** These are the only ones the SDK dispatches — a kind you invent is stored but never fires.
| Kind | Fires when | Default behaviour you are overriding |
| --- | --- | --- |
| `'click'` | A product or one of its components is clicked. | Selects the placement (and the clicked component). |
| `'hover'` | The pointer enters _or_ leaves a product. `hovered` says which. | Highlights the piece and sets the pointer cursor. |
**What the handler receives.** One object, same shape for both kinds apart from the last two rows.
| Field | Type | What it is |
| --- | --- | --- |
| `placementId` | string | The engine's placement id — the same id `camera.focusOn`, `readBounds` and `readBom` use. |
| `instanceId` | string | The same value under the internal spelling. Kept for existing handlers. |
| `instance` | object | The scene-graph record for the piece — `productId`, `variantId`, `sequence`, `position`. |
| `Default` | function | Our behaviour. `Default()` runs it unchanged; `Default(arg)` runs it with an edited payload; never calling it suppresses it. |
| `componentId` | string \| null | `'click'` only. The clicked component, or `null` when the click hit the placement as a whole. |
| `hovered` | boolean | `'hover'` only. `true` on enter, `false` on leave. |
There is no raw scene `object` in the payload — those stay behind the `exposeThreejsScene` entitlement. For geometry call `scene.readBounds()`, which is keyed by the same `placementId`.
```
// Log every click, then select as usual
scene.registerInteraction('click', ({ placementId, componentId, Default }) => {
console.log('clicked', placementId, componentId);
Default(); // omit this line and nothing gets selected
});
// Own the whole hover lifecycle (no Default() → our highlight never runs)
const off = scene.registerInteraction('hover', ({ placementId, hovered }) => {
myTooltip.toggle(placementId, hovered); // hovered: true on enter, false on leave
});
off(); // restore the built-in behaviour
// Redirect a click: select the whole run instead of the clicked component
scene.registerInteraction('click', ({ Default, ...arg }) => Default({ ...arg, componentId: null }));
```
##### `scene.listRenderers`
List registered component renderers.
```
const renderers = scene.listRenderers(); // list registered component renderers
```
##### `scene.listMaterials`
List registered material resolvers.
```
const materials = scene.listMaterials(); // list registered material resolvers
```
##### `scene.listInteractions`
List registered interactions.
```
const interactions = scene.listInteractions(); // list registered interactions
```
##### `scene.capture`
Capture design views (images).
```
const views = await scene.capture(); // capture design views (images)
```
Response — real sample from a live scene · `scene.capture()`
```
{
"perspective": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST…",
"front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST…",
"top": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/4gHYSUNDX1BST…"
}
```
##### `scene.buildPdf`
Build the design PDF as a `Blob` (all fields optional — views are captured on demand). This is the **same builder** that produces the Generate-Assets `pdf` artefact, so the document a customer saves and the one they download are the same bill of materials, page for page. The only thing that differs is the three pictures on the cover and view pages: pass `images` to supply your own, pass `views` to supply raw captures, or pass neither and the current scene is captured for you.
```
const pdfBlob = await scene.buildPdf({
projectName: 'Nordic Living Room',
customer: { firstName: 'Ada', lastName: 'Lovelace', email: 'ada@example.com' },
// images: { perspective, front, side }, // ready data URLs — wins over `views`
// views: { perspective, front, top }, // raw captures; omitted → captured now
// shareUrl, arUrl, // printed as QR codes when provided
});
```
##### `scene.generateAr`
Generate an AR asset for the current scene.
```
scene.generateAr({ onProgress }); // generate an AR asset for the current scene
```
##### `scene.hideComponent`
Hide a component (by slot / name / id) — survives re-evaluates.
```
scene.hideComponent('door_left'); // hide a component (by slot / name / id) - survives re-evaluates
```
##### `scene.showComponent`
Show a previously hidden component.
```
scene.showComponent('door_left'); // undo a hideComponent
```
##### `scene.transformComponent`
Apply a delta transform to a component (metres / degrees).
```
scene.transformComponent('shelf', { position: [0, 0.05, 0] }); // metres/degrees
```
##### `scene.setComponentMaterial`
Override a component’s material.
```
scene.setComponentMaterial('handle', 'brass'); // override a component's material
```
##### `scene.clearComponentOverrides`
Clear all host component overrides.
```
scene.clearComponentOverrides(); // all of them
scene.clearComponentOverrides('door_left'); // or one component
```
##### `scene.listComponents`
List mounted components and their identities.
```
const components = scene.listComponents(); // list mounted components and their identities
```
#### UI
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-ui
##### `ui.registerComponent`
Swap one piece of the built-in UI for your own React component. You pick a piece by its published name (the 16 below), hand over your component, and the SDK renders yours everywhere it would have rendered its own — same props, plus one extra: `Default`, which _is_ the built-in. Render ` ` inside your component and you keep all our behavior (clicks, selection, disabled states) while adding your markup around it — that's almost always what you want, and it keeps receiving our fixes. Registering works even after `mount()` (the UI re-renders live), and the call returns an unregister function that restores the built-in.
```
const off = ui.registerComponent('OptionThumbnail', ({ Default, ...props }) => (
{/* our tile, all behavior intact */}
{props.option?.isNew && New}
));
// off() restores the built-in. Props each name receives: Customise the UI → Override components
```
All 16 names — what each is on screen, with a working starter (props shown are the ones each really receives):
| Component | On screen | Starter |
| --- | --- | --- |
| `Sidebar` | the whole option panel — desktop sidebar, mobile tab, every shell | `ui.registerComponent('Sidebar', ({ Default,...p }) =>);` |
| `OptionSetSection` | one option-set block inside the sidebar (heading + its options grid) | `ui.registerComponent('OptionSetSection', ({ Default,...p }) =>); // start every section collapsed` |
| `OptionThumbnail` | a single option tile in a generic option grid | `ui.registerComponent('OptionThumbnail', ({ Default,...p }) => <> {p.option?.isNew && **New** });` |
| `FinishThumbnail` | a single material/finish swatch tile | `ui.registerComponent('FinishThumbnail', ({ material, isSelected, onClick }) =>);` |
| `LayoutThumbnail` | a single tile in the layout picker | `ui.registerComponent('LayoutThumbnail', ({ option, isSelected, onClick }) => {MY_ICONS[option.value]});` |
| `HostedProductThumbnail` | a hosted-product card (a product that mounts on another, e.g. an appliance) | `ui.registerComponent('HostedProductThumbnail', ({ Default,...p }) => <> {p.isPlaced && _Installed_ });` |
| `AddProductToggle` | an add-a-product option set rendered as an on/off toggle | `ui.registerComponent('AddProductToggle', ({ Default,...p }) =>);` |
| `SceneToolbar` | the scene button row — 2D/3D, walls, dimensions, undo/redo… | `ui.registerComponent('SceneToolbar', ({ Default,...p }) => <> ?); // append your own button` |
| `SelectionActionPanel` | the floating panel while a piece is selected (move / duplicate / delete + price) | `ui.registerComponent('SelectionActionPanel', ({ Default,...p }) => <> {p.priceInfo && {p.priceInfo.unitPrice} });` |
| `SaveProjectButton` | the Save button (header, mobile top bar, shell CTAs) | `ui.registerComponent('SaveProjectButton', ({ Default,...p }) =>);` |
| `GenerateAssetsButton` | the generate-assets button next to it | `ui.registerComponent('GenerateAssetsButton', ({ onClick, isGenerating, disabled }) => {isGenerating ? 'Rendering…': 'Get images'});` |
| `LiveStatusPanel` | the live status panel (when the panels region is on) | `ui.registerComponent('LiveStatusPanel', () => null); // simplest useful override: hide it` |
| `ChatBar` | the AI-assistant input | `ui.registerComponent('ChatBar', ({ Default,...p }) =>);` |
| `ConfirmDialog` | confirmation prompts (overlap warnings, deletes) | `ui.registerComponent('ConfirmDialog', ({ dialog, onClose }) => dialog &&);` |
| `SceneDimensions` | the dimension callouts — renders _inside_ the 3D canvas | `ui.registerComponent('SceneDimensions', ({ bbox }) =>); // R3F code, metres` |
| `ARViewer` | the page the AR QR code opens | `ui.registerComponent('ARViewer', MyBrandedArPage); // receives no props — reads its ?src URL itself` |
##### `ui.listComponentOverrides`
List registered component overrides.
```
const componentOverrides = ui.listComponentOverrides(); // list registered component overrides
```
Response — real sample from a live scene · `ui.listComponentOverrides()`
```
[
"optionthumbnail"
]
```
##### `ui.registerLayout`
Register a whole-shell layout under a key.
```
ui.registerLayout('default', MyShell); // MyShell({ Scene }) => <…>
```
##### `ui.listLayouts`
List registered layouts.
```
const layouts = ui.listLayouts(); // list registered layouts
```
Response — real sample from a live scene · `ui.listLayouts()`
```
[
{
"key": "default",
"custom": false
},
// … 6 more items like the one above
]
```
##### `ui.activeLayout`
The layout key currently live.
```
const key = ui.activeLayout(); // 'showroom' | 'default' | …
```
Response — real sample from a live scene · `ui.activeLayout()`
```
"default"
```
##### `ui.setLayout`
Force a layout from code (outranks backend/theme); null hands control back.
```
ui.setLayout('wizard'); // force a layout; null hands control back
```
##### `ui.registerRoute`
Register a whole page for a path or matcher.
```
ui.registerRoute('/ar-viewer', MyArPage); // register a whole page for a path or matcher
```
##### `ui.listRoutes`
List registered routes.
```
const routes = ui.listRoutes(); // list registered routes
```
Response — real sample from a live scene · `ui.listRoutes()`
```
{
"paths": [],
"matchers": 0
}
```
##### `ui.setToggles`
Hide or re-enable the built-in toolbar buttons and panels per key — `false` hides, `true` shows, a key you don’t mention keeps its current state. Merges over the backend’s own toggles, so your call wins.
```
ui.setToggles({
fullscreen: false, // hide the fullscreen button
undo: false, redo: false,
walls: true, // (re-)show walls toggle
});
```
Possible values — toggle key
`toggle2d3d` the 2D / 3D view switch
`dimensions` dimension overlay on/off
`walls` wall visibility
`resetCamera` reset the camera to the default framing
`fullscreen` enter/exit fullscreen
`undo` undo the last action
`redo` redo
`liveStatus` the live status panel — the floating engine/state inspector, and its Status tab on mobile
##### `ui.getToggles`
The current host toggle overrides.
```
const toggles = ui.getToggles(); // the current host toggle overrides
```
##### `ui.registerAssetResolver`
Rewrite thumbnail/image URLs to your CDN.
```
ui.registerAssetResolver((url, ctx) => url.replace('/media/', '/cdn/')); // rewrite thumbnail/image URLs to your CDN
```
##### `ui.registerSlot`
Render YOUR component at one of the UI's five fixed slots — `toolbar`, `sidebar-top`, `sidebar-bottom`, `selection-panel`, `overlay` (each hands your component a context object; see the slots table in Customise the UI). Returns an unregister.
```
const off = ui.registerSlot('sidebar-top', ({ placementId }) => (
));
```
##### `ui.registerButton`
Add YOUR button into one of the UI's slots (styled like ours) — the convenient shorthand for `registerSlot` when all you want is a button. Give it a `slot`, a `label` (or `icon`), and an `onClick` (or the name of a registered `action`); optional `variant: 'default' | 'primary'` and `title` (tooltip). Returns an unregister. To remove or restyle one of OUR buttons, use `ui.setToggles` / plain CSS instead.
```
const off = ui.registerButton({
slot: 'toolbar',
label: 'Book a designer',
variant: 'primary',
onClick: (ctx) => openBookingFlow(ctx), // receives the slot's context object
});
```
##### `ui.listSlots`
List the slots you have put content into. Only _your_ registrations appear (the SDK's own UI is not slot-registered), so a fresh boot returns `[]`.
```
const slots = ui.listSlots(); // list registered slot content
```
Response — after `ui.registerSlot('overlay', MyCartBar)` + `ui.registerButton({ slot: 'toolbar', … })`; `[]` before any registration
```
[
"overlay",
"toolbar"
]
```
##### `ui.registerAction`
Register a host verb (dispatches as action.).
```
ui.registerAction('requestQuote', () => { /* … */ }); // register a host verb (dispatches as action.)
```
##### `ui.listActions`
List the verbs you registered with `registerAction`. Empty until you register one — built-in behavior is not on this list.
```
const actions = ui.listActions(); // list registered actions
```
Response — after `ui.registerAction('requestQuote', fn)`; `[]` before any registration
```
[
"requestQuote"
]
```
##### `ui.actions`
Live handles for registered actions (ui.actions.()).
```
const x = ui.actions; // constant
```
##### `ui.registerIcon`
Swap a glyph wherever it renders.
```
ui.registerIcon('delete', MyTrashIcon); // swap a glyph wherever it renders
```
##### `ui.listIcons`
List the glyphs you have swapped with `registerIcon`. The SDK's ~35 built-in glyphs are not listed — only your replacements — so a fresh boot returns `[]`.
```
const icons = ui.listIcons(); // list registered icons
```
Response — after `ui.registerIcon('delete', MyTrashIcon)`; `[]` before any registration
```
[
"delete"
]
```
##### `ui.registerModal`
Register a custom dialog under a key; `ui.openModal(key, data)` opens it. Your component is the dialog's **content** and receives `{ data, close }` — the SDK supplies the backdrop, centring, themed panel, Escape and click-outside, so an unstyled `
` already opens as a proper dialog. Restyle the frame through `[data-part="modal"]` and `[data-part="modal/panel"]`. Last registration per key wins; unknown keys open nothing.
```
ui.registerModal('lookbook', MyLookbook); // register a custom dialog under a key
```
##### `ui.openModal`
Open one of the SDK’s modals by key (e.g. `’quote’`), optionally passing data to it — the same entry point our own buttons use.
```
ui.openModal('lookbook'); // open a modal by key
```
##### `ui.closeModal`
Close whichever SDK modal is currently open (no-op when none is).
```
ui.closeModal(); // close the open modal
```
##### `ui.listModals`
List the custom dialogs you registered with `registerModal`. The SDK's own modals (quote, AR, save…) keep their components and are not on this list — a fresh boot returns `[]`.
```
const modals = ui.listModals(); // list registered modals
```
Response — after `ui.registerModal('lookbook', MyLookbook)`; `[]` before any registration
```
[
"lookbook"
]
```
##### `ui.setLabels`
Override any built-in UI string (key → your text). Calls merge — later calls never wipe earlier keys — and unset keys keep our default text, so you only override what you want changed. An **empty string hides** the text: headings, hints and captions render nothing, a button becomes icon-only. A key you set here **wins over the theme's** `labels` (the admin's Text & labels), whichever arrives last. Non-string values are ignored. Option-set and option names are not labels — they come from your catalog.
```
ui.setLabels({
'panel.delete': 'Remove piece',
'toolbar.resetCamera': 'Recenter view',
'save.label': 'Save my design',
});
```
**How to use this table:** find the English text you see on screen in the middle column, take its key from the left, and pass your own text for that key. The default text is exactly what the UI shows until you override it.
| Key | Default text (what you're replacing) | Where it shows |
| --- | --- | --- |
| **Selection panel** — the floating panel while a piece is selected |
| `panel.duplicate` | Duplicate | button |
| `panel.delete` | Delete | button |
| `panel.moveLeft` | Move Left | button |
| `panel.moveRight` | Move Right | button |
| **Scene toolbar** — the button row over the 3D scene (tooltips) |
| `toolbar.undo` | Undo | tooltip |
| `toolbar.redo` | Redo | tooltip |
| `toolbar.to2d` | Switch to 2D | tooltip, while in 3D |
| `toolbar.to3d` | Switch to 3D | tooltip, while in 2D |
| `toolbar.dimensions` | Dimensions | tooltip |
| `toolbar.showWalls` | Show Walls | tooltip, walls hidden |
| `toolbar.hideWalls` | Hide Walls | tooltip, walls shown |
| `toolbar.wallsGuide` | Click here to show walls again | hint after hiding walls |
| `toolbar.fullscreen` | Fullscreen | tooltip |
| `toolbar.exitFullscreen` | Exit Fullscreen | tooltip, while fullscreen |
| `toolbar.resetCamera` | Reset Camera | tooltip |
| **Page chrome** — loading, tabs, overlays |
| `loading.message` | Loading Configurator... | boot loader |
| `overlay.updating` | Updating… | overlay during an engine round-trip |
| `sidebar.open` | Open sidebar | tooltip on the collapsed-sidebar button |
| `tabs.chat` | Chat | mobile tab |
| `tabs.status` | Status | mobile tab |
| **Save** — the Save button and its dialog |
| `save.label` | Save | the Save button text |
| `save.title` | Save · Submit your design | button tooltip · dialog heading (same key, two places) |
| `save.titleDone` | Design submitted | dialog heading after submit |
| `save.snapshots` | Design snapshots | section label |
| `save.contactTitle` | Where should we send updates? | form section heading |
| `save.firstName` | First name | field label |
| `save.lastName` | Last name | field label |
| `save.email` | Email | field label |
| `save.phone` | Phone number | field label |
| `save.projectName` | Project name | field label |
| `save.projectPlaceholder` | e.g. My dream design | field placeholder |
| `save.company` | Company | field label |
| `save.address` | Address | field label |
| `save.cancel` | Cancel | button |
| `save.submit` | Submit design | button |
| `save.submitted` | Design submitted — you're all set. | success message |
| `save.shareLink` | Share link | label on the generated link |
| `save.emailLink` | Email me the link | button |
| `save.close` | Close | button |
| **Quote** — the on-screen quote document |
| `quote.empty` | Nothing configured yet. | empty state |
| `quote.item` | item | totals row, singular (“1 item”) |
| `quote.items` | items | totals row, plural (“4 items”) |
| `quote.renders` | Renders | render-grid heading |
| `quote.arScan` | Scan to view in your room | caption under the AR QR |
| `quote.downloadPdf` | Download PDF | button |
| `quote.print` | Print | button |
| `quote.close` | Close | button |
| **Export dialog** |
| `export.title` | Export to PDF | dialog heading |
| `export.screenshot` | Scene screenshot | checkbox |
| `export.productList` | Product list with selections | checkbox |
| `export.priceBreakdown` | Price breakdown | checkbox |
| **Generate assets** — the button and the results dialog |
| `generate.label` | Generate Assets | the button |
| `generate.busy` | Generating... | the button, while running |
| `assets.hero.title1` | Specification & | dialog hero heading, line 1 |
| `assets.hero.title2` | Sales Document | dialog hero heading, line 2 |
| `assets.source` | From Configuration | source tag |
| `assets.preparing` | Preparing... | status |
| `assets.generating` | Generating assets... | status |
| `assets.allReady` | All assets ready | status |
| `assets.regenerateAll` | Regenerate All | button |
| `assets.back` | Back to Configurator | button |
| `assets.silos.title` | Silos | card heading |
| `assets.silos.desc` | High-resolution product images on clean backgrounds, optimized for e-commerce and catalog use. | card text |
| `assets.lifestyle.title` | Lifestyle Imagery | card heading |
| `assets.lifestyle.desc` | Photorealistic room scenes showcasing your configuration in aspirational settings. | card text |
| `assets.ar.title` | AR | card heading |
| `assets.ar.desc` | View your configuration in augmented reality — share with clients to preview at scale in their space. | card text |
| `assets.queued` | Queued | per-asset status |
| `assets.processing` | Processing | per-asset status |
| `assets.generatingDoc` | Generating document... | per-asset status |
| `assets.failed` | Generation failed | per-asset error |
| `assets.failedBadge` | Failed | badge |
| `assets.ar.scan` | Scan to view in AR | AR card, QR caption |
| `assets.ar.generatingModel` | Generating model... | AR card status |
| `assets.ar.queued` | Queued for generation | AR card status |
| `assets.ar.ready` | Ready to view in AR | AR card status |
| `assets.ar.tapHint` | Tap the button below to view your configuration in augmented reality. | AR card, on mobile |
| **AR** — the AR modal and the page the QR code opens |
| `ar.modalTitle` | View in AR | modal heading |
| `ar.title` | View in AR | AR page heading |
| `ar.subtitle` | Scan this QR code with your mobile device | AR page |
| `ar.hint` | Point your phone camera at the code above | AR page |
| `ar.cta` | View in your space | AR page button (on a phone) |
| `ar.noModel` | No AR model URL provided. | AR page error |
| **AI chat** |
| `chat.loading` | Loading... | while the assistant connects |
| `chat.notConnected` | Not Connected | status pill |
| `chat.unavailable` | Chat Unavailable | fallback panel heading |
| `chat.unavailableHint` | The AI assistant is not connected. Please connect with the admin. | fallback panel text |
| **Shell layouts** — only when the wizard / showcase / showroom shell is active |
| `wizard.step` | Step | wizard: “Step 2 of 5” |
| `wizard.summary` | Summary | wizard: side panel heading |
| `wizard.review` | Review your configuration | wizard: final step heading |
| `wizard.reviewBtn` | Review | wizard: last-step button |
| `wizard.back` | Back | wizard: button |
| `wizard.next` | Next | wizard: button |
| `shell.totalPrice` | TOTAL PRICE | wizard: price label |
| `shell.total` | TOTAL | showcase & showroom: price label |
| `showcase.heading1` | Customize | showcase: hero heading, line 1 |
| `showcase.heading2` | your design | showcase: hero heading, line 2 |
| `showcase.intro` | Select your options below — the preview updates as you go. | showcase: intro text |
| `showcase.allOptions` | All options | showcase: section heading |
| `showcase.select` | Select | showcase: option button |
| `showroom.intro` | Configure your piece below — each option updates the preview live. | showroom: intro text |
| **Placement hints** — the toast shown after picking a product to place |
| `placement.armedPickGap` | Click a + between pieces to insert it. | default add flow |
| `placement.armedPickTarget` | _(empty)_ | when a custom placement strategy is active — set it to give your users a hint |
##### `ui.getLabel`
Read one label’s current text — your override if set, otherwise the fallback you pass. Non-reactive; for event handlers and imperative code.
```
ui.getLabel('panel.delete', 'Delete'); // 'Remove piece' after the setLabels call above, else 'Delete'
```
##### `ui.getLabels`
Read the overrides currently in effect — _only_ the keys you (or the theme) have set, not the SDK's default strings. Use it to audit what `setLabels` changed; the full list of available keys is the table under `ui.setLabels`.
```
const labels = ui.getLabels(); // your overrides only — {} before any setLabels call
```
Response — after the `setLabels` call above
```
{
"panel.delete": "Remove piece",
"toolbar.resetCamera": "Recenter view",
"save.label": "Save my design"
}
```
##### `ui.setLocale`
Set the locale used to format every number and price the SDK renders — scene totals, per-piece prices, quote and BOM figures. Takes a BCP 47 tag (`'de-DE'`, `'en-US'`, `'fr-FR'`, `'ja-JP'`, `'ar-EG'`); `'de-DE'` gives you `1.234,56` where `'en-US'` gives `1,234.56`. It also sets text direction: an RTL tag makes `ui.isRtl()` true and our layouts flip.
**This does not translate text.** Wording is `ui.setLabels()` — the locale only changes how numbers look. Call it any time, before or after boot: components re-render immediately. Pass `null` to clear back to the automatic default, which is the browser's `navigator.language`, falling back to `'en'`.
Three ways to set it, last call wins: `configure({ locale })` at boot, a theme record's `locale` field (applied by `ui.applyTheme`), or this call.
```
ui.setLocale('de-DE'); // 1.234,56 — German grouping
ui.setLocale('en-US'); // 1,234.56
ui.setLocale('ar-EG'); // ui.isRtl() is now true
ui.setLocale(null); // back to the browser's locale
// Locale formats the numbers; labels translate the words. You usually want both.
ui.setLocale('de-DE');
ui.setLabels({ 'panel.delete': 'Entfernen' });
```
##### `ui.getLocale`
The locale actually in use for formatting, e.g. `'en-US'`. Always returns a usable tag, never `null`: your `setLocale` value if you set one, otherwise the browser's `navigator.language`, otherwise `'en'`. So it can return a locale you never set — that is the one being rendered.
```
const locale = ui.getLocale(); // 'de-DE' if you set it, else the browser's, else 'en'
// Reuse the SDK's locale in your own chrome so nothing drifts
new Intl.DateTimeFormat(ui.getLocale()).format(new Date());
```
##### `ui.setCurrency`
Set the currency code prices are rendered in. Takes an ISO 4217 code; case and surrounding spaces do not matter, so `'eur'` and `'EUR'` are the same. The symbol and its placement come from the locale: the same `'EUR'` renders `€1,234` under `'en-US'` and `1.234 €` under `'de-DE'`.
**Display only — this does not convert.** Amounts come from the engine and are never recalculated. Setting `'EUR'` on prices the backend quoted in dollars relabels them as euros at the same numbers. Change what the engine charges through the sales channel (`config.setChannelId`), not here.
Which code wins, highest first:
| Source | When it applies |
| --- | --- |
| `ui.setCurrency(code)` | Whenever you have set one. Overrides the backend. |
| The channel's currency | No override set — the backend's currency for the active sales channel. |
| `'USD'` | Neither of the above. |
Pass `null` to drop your override and fall back to the channel. An unrecognised code degrades to a plain formatted number rather than throwing mid-render, so a typo shows up as a missing symbol, not a blank screen. Scene totals are rendered as whole numbers; `ui.formatMoney` keeps up to two decimals.
```
ui.setCurrency('EUR'); // €1,234 (symbol placement follows the locale)
ui.setCurrency('jpy'); // upper-cased for you
ui.setCurrency(null); // back to the channel's currency, else USD
// Currency and locale are independent — set both for a market
ui.setLocale('de-DE');
ui.setCurrency('EUR'); // 1.234 €
```
##### `ui.getCurrency`
Your `setCurrency` override, or `null` when you have not set one. **Note the difference from `ui.getLocale`**, which always resolves to something usable. `null` here does not mean prices are unformatted — it means no override is in force, so the scene total falls back to the channel's currency, or USD.
Because it reports only the override, it is the right thing to test before setting one, and the wrong thing to trust as "what the user sees". `ui.formatMoney` follows the same override, so with none set it returns a plain number with no symbol. The channel fallback applies to the SDK's own price rendering, not to that helper — if your chrome formats its own prices, set the currency explicitly rather than inferring it.
```
ui.getCurrency(); // null — no override in force
ui.formatMoney(1299); // '1,299' — no override, so no symbol
ui.setCurrency('EUR');
ui.getCurrency(); // 'EUR'
ui.formatMoney(1299); // '€1,299.00'
```
##### `ui.isRtl`
True when the active locale is right-to-left — Arabic, Hebrew, Persian, Urdu, Pashto, Sindhi or Yiddish, matched on the language part, so `'ar-EG'` and `'ar'` both count. Our layouts already flip themselves; use this to mirror chrome you render yourself. Pass a tag to test one without changing the active locale.
```
if (ui.isRtl()) document.dir = 'rtl'; // mirror your own chrome too
ui.isRtl('he-IL'); // true — test a tag without setting it
```
##### `ui.formatMoney`
Format a number as money using the active locale and the currency from `ui.setCurrency`. With no currency set it returns a grouped number and no symbol. A second argument overrides the currency for one call, which is how you render a figure in something other than the configurator's currency. Non-numeric input returns an empty string, and an unusable currency code falls back to a plain number, so it is safe to call directly in a render.
```
ui.setCurrency('EUR');
ui.formatMoney(1299); // '€1,299.00'
ui.formatMoney(1299, 'USD'); // '$1,299.00' — this call only
ui.formatMoney(null); // '' — nothing to format
```
##### `ui.formatNumber`
Format a number for the active locale.
```
ui.formatNumber(2400.5); // "2,400.5" in the active locale
```
##### `ui.applyTheme`
Apply a theme record (colors / sizing / typography / buttons). A theme **switches the shell** as well, exactly like a backend theme: a record's `layout` (or a name such as `'Theme 2'`) picks wizard / showroom / showcase, a string preset does the same, and `applyTheme(null)` returns to the default shell — the record becomes the system's theme in the store, so everything that reads it follows.
```
ui.applyTheme({ name: 'brand', config: {
colors: { primary: '#1a936f', background: '#f5f1e8', surface: '#fdfaf2' },
sizing: { radius: 2, gap: 8 },
typography: { fontFamily: '"Inter", "Inter Fallback", sans-serif' },
buttons: { buttonStyle: 'filled' },
}});
```
##### `ui.applyThemeById`
Apply a **backend** theme by its id, in one call. Fetches the Theme record from `/api/v1/themes/ /` with the SDK's own auth and applies it exactly as `ui.applyTheme(record)` would — colours, typography, logo, labels, custom CSS — so it becomes _your_ theme and the system's own theme yields to it. Resolves the record it applied, or `null` when nothing was applied: an unknown id, a network error or a malformed record leaves the current theme in place and warns once in the console — never a half-applied palette. You do not need this for the system's own theme: set `themeId` on the system in the admin and boot applies it by itself. Use it for a theme switcher, a per-customer theme your backend decides, or previewing a theme without changing the system. Like `applyTheme`, it switches the shell too when the record carries a `layout` — the same result as the system referencing that theme from the backend.
```
const record = await ui.applyThemeById(12); // GET /api/v1/themes/12/ → applied; null if it could not be
if (!record) showFallbackBrand();
// A theme switcher — every option is a Theme record id from the admin.
select.addEventListener('change', (e) => ui.applyThemeById(e.target.value));
ui.applyTheme(null); // back to the default palette
```
##### `ui.applyCustomCss`
Inject custom CSS, scoped to the configurator: every rule is prefixed with the element you passed to `mount()` (stamped `data-imagine-root`) or the app's `#root`, at zero extra specificity, so it cannot restyle the host page. Write rules against `data-part` names only — a name nothing in the UI carries is reported in the console (`[sdk/theme] applyCustomCss: unknown data-part …`) instead of failing silently. Replaces the previous custom CSS; `@import` and `javascript:` are rejected.
```
ui.applyCustomCss('[data-part="option-card"] { letter-spacing: .04em; }'); // inject scoped custom CSS (blocks @import / javascript:)
```
##### `ui.applyFontUrl`
Load a web font (https-only).
```
ui.applyFontUrl('https://fonts.googleapis.com/css2?family=Sora&display=swap');
```
##### `ui.hide`
Hide UI regions (no args = bare canvas).
```
ui.hide('sidebar', 'toolbar'); // or ui.hide() for a bare canvas
```
##### `ui.show`
Show UI regions (no args = all back).
```
ui.show(); // everything back
```
##### `ui.visible`
The current region visibility map.
```
const regions = ui.visible(); // { sidebar: false, header: true, … }
```
##### `ui.regions`
The region names (sidebar, header, toolbar, panels, chat, notifications).
```
const x = ui.regions; // constant
```
##### `ui.notify`
Show a toast notification. `message` is required; optional `title`; `duration` in ms (default 5000, `0` = stays until dismissed). Identical back-to-back notifications are deduped.
```
ui.notify({ type: 'success', message: 'Added to cart' });
ui.notify({ type: 'error', title: 'Out of stock',
message: 'Pick another fabric', duration: 0 }); // 0 = sticky
```
Possible values — `type`
`info` neutral notice — the default
`success` green confirmation (e.g. “added to cart”)
`warning` amber caution — something needs attention
`error` red failure — pair with `duration: 0` so it stays until dismissed
##### `ui.showInfo`
Show an inline info message.
```
ui.showInfo('Drag a module into the scene to start'); // show an inline info message
```
##### `ui.setLoading`
Raise the busy overlay over the whole configurator with your own message — the same overlay the SDK shows during an engine round-trip, so it also blocks input until you clear it. Pair every `setLoading(true, …)` with a `setLoading(false)`; it stays up until you do.
```
ui.setLoading(true, 'Preparing your design…'); // raise the overlay with a message
ui.setLoading(false); // dismiss it
```
##### `copilot.isAvailable`
Probe whether the AI chat runtime is reachable.
```
if (await copilot.isAvailable()) mountChatButton();
```
Response — real sample from a live scene · `copilot.isAvailable()`
```
true
```
#### Quote
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-quote
##### `quote.read`
The current quote — line items + totals.
```
const { lines, totals } = quote.read(); // totals.grandTotal, totals.subtotal
```
Response — real sample from a live scene · `quote.read()`
```
{
"quotedAt": "2026-09-01T18:07:51.291Z",
"system": {
"id": "1",
"name": "Kitchen"
},
"currency": null,
"lines": [
{
"placementId": "p1",
"productId": 9,
"variantId": 9,
"sku": null,
"name": "Single Door 9\"",
"qty": 1,
"sequence": 0,
"placementGroup": "floor",
"unitPrice": 824,
"adjustments": [
{
"optionSetId": 12,
"optionSetLabel": "Layouts",
"optionId": 1,
"label": "L-Shaped",
"amount": 0,
"optionName": "L-Shaped",
"optionSetName": "Layouts"
},
// … 7 more items like the one above
],
"selections": [
{
"setId": "1",
"setName": "Cabinet Finish",
"setType": "finish_change",
"optionId": 65,
"optionName": "Espresso",
"amount": 25
},
// … 4 more items like the one above
],
"selectionsNamed": [
{
"setId": "1",
"setName": "Cabinet Finish",
"setType": "finish_change",
"optionId": 65,
"optionName": "Espresso",
"amount": 25
},
// … 6 more items like the one above
],
"components": [],
"materials": [],
"metadata": {},
"placementIds": [
"p1"
],
"effectiveSelections": {
"1": 65,
"2": 12,
"6": 23,
"7": 31,
"8": 96,
"9": 71,
"10": 54
},
"adjustmentTotal": 335,
"lineTotal": 824,
"unitPriceFormatted": "824",
"lineTotalFormatted": "824"
},
// … 16 more items like the one above
],
"additionalLines": [],
"scene": {
"selections": [
{
"setId": "1",
"setName": "Cabinet Finish",
"setType": "finish_change",
"optionId": 65,
"optionName": "Espresso",
"amount": null
},
// … 9 more items like the one above
]
},
"images": {
"images": [
{
"id": "silo-front",
"type": "silo",
"label": "Silo 1",
"status": "idle",
"progress": 0,
"url": null,
"error": null
},
// … 7 more items like the one above
],
"ready": [],
"uploadedImageUrl": null
},
"totals": {
"lineCount": 17,
"unitCount": 22,
"subtotal": 16273,
"subtotalFormatted": "16,273",
"additionalSubtotal": 0,
"additionalSubtotalFormatted": "0",
"grandTotal": 16273,
"grandTotalFormatted": "16,273",
"hasSceneLevelAdjustment": false
},
"metadata": {}
}
```
##### `quote.registerTemplate`
Register your quote document under a key — a component receiving `{ quote, close }`. It renders in the on-screen dialog (`quote.open()`) **and** is rendered into every PDF the SDK produces, unless a `quote.registerPdf` builder exists (that wins). Nothing in the built-in UI opens the dialog; call `quote.open()` from your own button or after a save.
```
quote.registerTemplate('brand', MyQuoteTemplate); // your quote document — on screen and in every PDF
```
##### `quote.setTemplate`
Select the active quote template.
```
quote.setTemplate('brand'); // select the active quote template
```
##### `quote.listTemplates`
List registered quote templates.
```
const templates = quote.listTemplates(); // list registered quote templates
```
Response — real sample from a live scene · `quote.listTemplates()`
```
[
"sample"
]
```
##### `quote.activeTemplate`
The active quote template key.
```
const activeTemplate = quote.activeTemplate(); // the active quote template key
```
##### `quote.open`
Open the on-screen quote dialog. **Nothing in the built-in UI opens it** — the SDK ships no Quote button — so the dialog appears only when you call this: from a button you add, or after a save or a render run (`project.saved`, `assets.generated`). Dispatched as the `quote.open` intent, so middleware can observe or block it.
```
quote.open(); // open the quote view
```
##### `quote.images`
The generated images available for the quote.
```
const images = quote.images(); // the generated images available for the quote
```
Response — real sample from a live scene · `quote.images()`
```
{
"images": [
{
"id": "silo-front",
"type": "silo",
"label": "Silo 1",
"status": "idle",
"progress": 0,
"url": null,
"error": null
},
// … 7 more items like the one above
],
"ready": [],
"uploadedImageUrl": null
}
```
Possible values — `type` (per asset)
`silo` the configured product on a clean white background
`lifestyle` the product rendered in a styled room scene
`ar` a QR-ready link that opens the model in augmented reality on a phone
`pdf` the generated BOM / quote document
##### `quote.generateSilo`
Generate a silo (product-on-white) render.
```
await quote.generateSilo(); // generate a silo (product-on-white) render
```
Response
```
["https://…/silo-1.png", "https://…/silo-2.png"] // finished silo URLs
```
##### `quote.generateLifestyle`
Generate a lifestyle render.
```
await quote.generateLifestyle(); // generate a lifestyle render
```
Response
```
["https://…/lifestyle-1.png", "… more"] // finished lifestyle URLs
```
##### `quote.generateAr`
Export the LIVE scene as a.glb, upload it, and resolve with the AR link URL — the page a phone opens to view the model in augmented reality.
```
const arUrl = await quote.generateAr(); // resolves when the AR model finished uploading
```
Response
```
"https://…/model.glb" // the AR model URL — or null if generation failed
```
##### `quote.generateBomPdf`
Generate the bill-of-materials PDF as a Generate-Assets artefact. It is built by the **same function** as `scene.buildPdf` — one document, so what a customer downloads here and what gets attached to a saved project cannot disagree. It carries the AR QR page when an AR asset finished, and the reopen-design QR page when the design was opened from a share link. The cover and view pages use the AI lifestyle renders from the same run; the saved-project copy uses 3D captures of the scene instead.
```
await quote.generateBomPdf(); // generate a bill-of-materials PDF
```
Response
```
"https://…/bom.pdf" // the BOM document URL — or null if generation failed
```
##### `quote.generateAll`
Generate all asset families.
```
await quote.generateAll(); // generate all asset families
```
Response — resolves when every family settles
```
{
"silo": ["https://…/silo-1.png", "… more"],
"lifestyle": ["https://…/lifestyle-1.png", "… more"],
"ar": "https://…/model.glb", // or null if it failed
"pdf": "https://…/quote.pdf", // or null
"timedOut": [] // families that never settled
}
```
##### `quote.generationStatus`
Asset-generation progress.
```
const status = quote.generationStatus(); // per-asset progress
```
Response — real sample from a live scene · `quote.generationStatus()`
```
{
"isGenerating": false,
"progress": 0,
"silo": [
{
"id": "silo-front",
"type": "silo",
"label": "Silo 1",
"status": "idle",
"progress": 0,
"url": null,
"error": null
},
// … 2 more items like the one above
],
"lifestyle": [
{
"id": "lifestyle-1",
"type": "lifestyle",
"label": "Lifestyle 1",
"status": "idle",
"progress": 0,
"url": null,
"error": null
},
// … 2 more items like the one above
],
"ar": {
"id": "ar-viewer",
"type": "ar",
"label": "AR Viewer",
"status": "idle",
"progress": 0,
"url": null,
"error": null
},
"pdf": {
"id": "bom-pdf",
"type": "pdf",
"label": "Quote",
"status": "idle",
"progress": 0,
"url": null,
"error": null
}
}
```
##### `quote.toPdf`
Build the quote PDF as a blob.
```
const blob = await quote.toPdf(); // a PDF Blob — upload it, attach it, or POST it
```
Response
```
Blob { type: "application/pdf" } // upload it, attach it, or POST it
```
##### `quote.savePdf`
Build the quote PDF and download it — a side effect, so it returns nothing. Use `quote.toPdf()` instead when you need the Blob to upload or attach.
```
await quote.savePdf(); // build and save the quote PDF
```
#### Placement
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-placement
##### `placement.registerStrategy`
Register arrangement geometry ({ id, computeLayout, computeTargets? }).
```
const off = placement.registerStrategy({
id: 'my-grid',
computeLayout(pieces, ctx) {
return pieces.map((p, i) => ({ position: [(i % 3), 0, Math.floor(i / 3)], rotation: [0, 0, 0] }));
},
});
```
##### `placement.listStrategies`
Host-registered strategy ids.
```
const strategies = placement.listStrategies(); // host-registered strategy ids
```
Response — real sample from a live scene · `placement.listStrategies()`
```
[
"sample-grid"
]
```
##### `placement.setStrategy`
Activate a placement strategy by id — one you registered with `registerStrategy`. A backend-shipped `system.placementStrategy` still wins over this call.
```
placement.setStrategy('my-grid'); // a strategy you registered
```
##### `placement.clearStrategy`
Clear the runtime override.
```
placement.clearStrategy(); // back to backend/defaults
```
##### `placement.computeTargets`
Candidate placement targets for the current run.
```
const targets = placement.computeTargets(); // candidate spots for the armed product
```
##### `placement.resolveTarget`
What picking a target means.
```
const action = placement.resolveTarget(target); // what picking this tile means
```
##### `placement.registerTargetRenderer`
Draw candidate tiles (the SDK ships none).
```
placement.registerTargetRenderer(({ target, state }) =>
state === 'invalid' ? null : …
);
```
#### Commerce
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-commerce
##### `commerce.readBom`
The bill of materials — lines carry sku/name/price plus the INSTALLED parts: components [{slot, componentId, name}] and materials [{slot, materialId, name}], hidden/swapped-out parts already filtered.
```
const { lines, grandTotal } = commerce.readBom();
lines[0].components; // [{ slot: 'leg_left', componentId: 402, name: 'Tapered Oak Leg' }]
lines[0].materials; // [{ slot: 'seat', materialId: 'm_524', name: 'Al 524 Camel' }]
lines[0].selectionsNamed; // [{ setId, setName: 'Finish', optionId, optionName: 'Oak', amount: 25 }]
```
Response — real sample from a live scene · `commerce.readBom()`
```
{
"lines": [
{
"placementId": "p1",
"productId": 9,
"variantId": 9,
"sku": null,
"name": "Single Door 9\"",
"qty": 1,
"sequence": 0,
"placementGroup": "floor",
"unitPrice": 824,
"adjustments": [
{
"optionSetId": 12,
"optionSetLabel": "Layouts",
"optionId": 1,
"label": "L-Shaped",
"amount": 0,
"optionName": "L-Shaped",
"optionSetName": "Layouts"
},
// … 7 more items like the one above
],
"selections": {
"1": 65,
"2": 12,
"6": 23,
"7": 31,
"8": 96,
"9": 71,
"10": 54
},
"selectionsNamed": [
{
"setId": "1",
"setName": "Cabinet Finish",
"setType": "finish_change",
"optionId": 65,
"optionName": "Espresso",
"amount": 25
},
// … 6 more items like the one above
],
"components": [],
"materials": [],
"metadata": {},
"placementIds": [
"p1"
],
"effectiveSelections": {
"1": 65,
"2": 12,
"6": 23,
"7": 31,
"8": 96,
"9": 71,
"10": 54
}
},
// … 16 more items like the one above
],
"aggregateAdjustments": [],
"grandTotal": 16273,
"currency": null,
"metadata": {}
}
```
##### `commerce.collectBom`
The BOM document model — { groups, title, summary, currency }: one flat parts list (every part is a line), duplicates collapsed with qty, priced hardware as regular lines. What the built-in BOM PDF renders. Async.
```
const bomDoc = await commerce.collectBom();
// { groups: [{ name, items }], title, summary, currency } — the model our BOM PDF renders
```
Response — real sample from a live scene · `commerce.collectBom()`
```
{
"isGeneric": true,
"title": "Kitchen",
"groups": [
{
"name": "Bill of Materials",
"items": [
{
"namedSelections": [ … ],
"variantId": 59,
"placementId": "p4",
"productGraphId": 3,
"productGraphName": "Wall Cabinet",
"name": "Wall Double Door 30x30\"",
"category": "Cabinet",
"placementGroup": "wall",
"dimensions": "W 30in",
"dimensionsRaw": { … },
"basePrice": 349,
"tags": [ … ],
"componentSwaps": [ … ],
"materialOverrides": [ … ],
"_groupKey": "Bill of Materials",
"unitPrice": 534,
"adjustments": [ … ],
"qty": 5
},
// … 22 more items like the one above
]
}
],
"currency": "USD",
"summary": {
"totalItems": 28,
"totalUnique": 23,
"lineItems": 23,
"groupCount": 1,
"grandTotal": 16273,
"configuratorKey": "kitchen",
"systemName": "Kitchen",
"currency": "USD"
},
"lifestyleImages": {},
"shareUrl": null,
"arUrl": null
}
```
##### `commerce.setMetadata`
Attach host metadata that round-trips with the design.
```
commerce.setMetadata({ shopifyVariantId: 'gid://…' });
```
##### `commerce.readMetadata`
Read back the metadata your host app attached via `setMetadata` — per-placement and project-scoped blobs (survives save/share round-trips).
```
const meta = commerce.readMetadata(); // read host metadata
```
#### Project
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-project
##### `project.save`
Persist the current design and get back everything you need to link to it — the project record, its share token, and the ready-made public URL (opening that URL restores the design automatically, so you don't have to build the link yourself). Saving again on a design that came from a share link updates it in place rather than creating a duplicate.
`project.save(details, options?)`. Every field of `details` is optional, and anything not listed is ignored.
| Field | What it is |
| --- | --- |
| `projectName` | The design's title. `name` is accepted as an alias; `projectName` wins if you pass both. Omit it and the project is stored as "Untitled design". |
| `firstName / lastName` | The customer. Sent separately and also joined into the project's display name. |
| `email / phone` | How to reach them — what a lead needs. |
| `company` | Company name, for a trade or dealer flow. |
| `address` | Free-text address. |
| `note` | Anything the customer typed for you. |
| `requests` | Array of strings — the tick-boxes of your own form ("call me", "send samples"). |
| `arUrl` | The AR viewer link for this design, when you already have one. |
| `pdfUrl` | An already-hosted PDF to link to the project. To BUILD one instead, use the second argument below. |
The second argument attaches a design PDF: `{ pdfBlob }` for one you already have, or `{ buildPdf }` for a builder we call with the freshly minted `{ shareUrl, shareToken, project }` — so the document can carry a working link back to the design. Both legs are best-effort: a failed PDF never fails the save.
```
const { project, shareToken, shareUrl } = await project.save({
projectName: 'My design', // or: name: 'My design'
firstName: 'Ada', email: 'ada@example.com', // optional — whatever you collect
});
// shareUrl → give it to the customer; opening it reopens this exact design
```
##### `project.load`
**Fetch** a saved design by its share token — a read, nothing more: you get the project record (name, system, snapshot) and the scene is left exactly as it is. Apply it with `project.restore`. Use this to list or preview saved designs in your own UI; a customer opening a share URL needs neither call, because the SDK loads and restores that design during boot.
```
const p = await project.load('abc123token');
p.name; // show it in your own "my designs" list — nothing has changed on screen yet
```
##### `project.restore`
**Apply** a design fetched by `project.load` to the live scene — placements, options, per-piece overrides and camera all replace what's on screen. Local only, no request. The scene must already be running (this is the second half of the pair, which is why they are two calls: the fetch tells you which system to load, the restore needs that system mounted first).
```
const p = await project.load('abc123token'); // fetch — scene untouched
project.restore(p); // apply — the scene becomes that design
```
#### Renders
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-renders
Rendered images of the design — the same pictures the strip under the 3D scene shows. Use them to put a product photo of the shopper's configuration anywhere on your page: a hero image, a cart thumbnail, a download link. Every call works on what is on screen unless you say otherwise; these optional fields override it:
| Field | What it is |
| --- | --- |
| `systemId` | The system to read. Default: the one you booted. Naming a different system also drops the on-screen layout and selections, so that system's defaults are used. |
| `presetId` | The layout whose renders to read. Default: the layout on screen. |
| `selections` | The options to show, as `{ optionSetId: optionId }`. Default: the shopper's current selections. A set you leave out uses its default option. |
##### `renders.getViews`
The finished views of the layout's render, in the order your admin arranged them: `[{ id, name, kind, frames, startFrame, status, resolution, thumb }]`. `frames` greater than 1 means the view is a 360° spin; `thumb` is a small preview image. Only finished views are listed — a view still rendering is left out. An empty array means the layout has no render yet, which is a normal state, not an error.
```
const views = await renders.getViews();
views.forEach((v) => console.log(v.name, v.thumb));
```
##### `renders.getImage`
One image of a view, showing the selected options: `{ url, viewId, name, frame, resolution, selections }`, where `selections` is what the image actually shows. Resolves `null` when the view has no image yet.
`renders.getImage({ viewId, frame?, tier?, format? })` — `viewId` comes from `getViews`. `tier` is `'full'` (the default, full resolution) or `'preview'` (page-sized, faster). `format: 'png'` for a download; left out, you get the server's compact default (AVIF). On a 360° spin, `frame` picks the angle; without it you get the view's start frame.
```
const [first] = await renders.getViews();
const img = await renders.getImage({ viewId: first.id });
if (img) document.querySelector('#hero').src = img.url;
// a PNG of a different option, for a download link — the scene on screen is untouched
const png = await renders.getImage({ viewId: first.id, format: 'png', selections: { 12: 340 } });
```
##### `renders.getFrames`
Every frame of a view as image URLs (preview size), for building your own 360° spin: index `i` is frame `i`. A single-image view resolves with its one image; a view with no image yet with `[]`.
```
const frames = await renders.getFrames({ viewId });
let i = 0;
spinner.onclick = () => { i = (i + 1) % frames.length; spinner.src = frames[i]; };
```
##### `renders.getLayers`
**Advanced.** The separate image layers of one view, for a host building its own image viewer. Only for a system presented as images rather than 3D (`useRenderMode().mode === 'rendered'`). Resolves `{ viewId, aspect, background, base, sets }`: stack `background`, then `base[frame]`, then for each selected option `sets[optionSetId][optionId][frame]`. Rejects with `err.code === 'NO_RENDER'` while nothing has finished rendering.
```
const { base, sets } = await renders.getLayers({ viewId });
const urls = [base[0], ...Object.entries(picks).map(([set, opt]) => sets[set]?.[opt]?.[0]).filter(Boolean)];
```
#### Catalog
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-catalog
##### `catalog.getProduct`
The catalog record for a **variant id, a product id, or a product name/slug** — or `null` when this system's catalog has none. The catalog stores _variants_, so a product id resolves to that product's default variant (use `catalog.getProductVariants(id)` when you need a specific one — width and components differ per variant). System-scoped and loaded during boot, so call it after `ready`. **Where ids come from:** your catalog, a placed product (`useProduct(placementId).productId` / `.variantId`), or `commerce.readBom().lines[].productId` — an _option_ id is not a product id, which is the usual reason this returns null. In dev the SDK logs the ids that do exist.
```
catalog.getProduct(12); // a VARIANT id → that exact record
catalog.getProduct(5); // a PRODUCT id → its default variant
catalog.getProduct('Base Cabinet 600'); // a name or slug also resolves
catalog.getProduct(5)?.name; // the display name — null-safe, no separate call
```
Response — real sample from a live scene · `catalog.getProduct(9)`
```
{
"id": 9,
"productGraph": 1,
"productGraphName": "Base Cabinet",
"name": "Single Door 9\"",
"description": null,
"category": "Cabinet",
"width": 9,
"height": null,
"depth": null,
"weight": 13.4,
"basePrice": 489,
"placementType": null,
"placementGroup": "floor",
"movable": false,
"corner": false,
"edge": "",
"optionSets": [
{
"optionSetId": 2,
"sequence": 0,
"options": [
12,
// … 9 more items like the one above
],
"defaultOption": 14,
"valueProductOverrides": {
"12": 9,
"14": 17
}
},
// … 7 more items like the one above
],
"componentsConfiguration": {
"10": {
"slotName": "single_body",
"componentId": 1,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"11": {
"slotName": "full_door",
"componentId": 14,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"12": {
"slotName": "base_slab",
"componentId": 225,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"13": {
"slotName": "backsplash",
"componentId": 240,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"14": {
"slotName": "handle",
"componentId": 257,
"position": [
0.200448,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
}
},
"thumbnail": "https://api-configurator.imagine.io/assets/thumbnails/door_types/single_door.s…",
"tags": [
{
"id": 1,
"name": "kitchen"
}
],
"rules": [
{
"id": 24,
"name": "Show base_single_door feat_cabinet_width scope on product_single…",
"priority": 10,
"hard": false,
"triggerType": "variant_placed",
"effectType": "show_option",
"triggerVariant": 9,
"effectParams": {
"option_ids": [
117,
// … 3 more items like the one above
],
"mode": "narrow"
}
},
// … 2 more items like the one above
],
"components_configuration": {
"10": {
"slotName": "single_body",
"componentId": 1,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"11": {
"slotName": "full_door",
"componentId": 14,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"12": {
"slotName": "base_slab",
"componentId": 225,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"13": {
"slotName": "backsplash",
"componentId": 240,
"position": [
0,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
},
"14": {
"slotName": "handle",
"componentId": 257,
"position": [
0.200448,
// … 2 more items like the one above
],
"rotation": [
0,
// … 2 more items like the one above
],
"scale": [
1,
// … 2 more items like the one above
]
}
},
"features_configuration_ids": [
{
"optionSetId": 2,
"sequence": 0,
"options": [
12,
// … 9 more items like the one above
],
"defaultOption": 14,
"valueProductOverrides": {
"12": 9,
"14": 17
}
},
// … 7 more items like the one above
]
}
```
##### `catalog.listProducts`
Every product in this system's catalog, each with its variants — this is **where ids come from**. Every other catalog call takes an id you must already have; use this to find one, or to build your own product picker. Grouped the way a catalog reads to a person (one product, several sizes) even though the catalog stores variants; a variant with no parent product comes back as a product of its own. Sorted by name, and available after `ready`.
```
catalog.listProducts();
// [{ id: 5, name: 'Base Cabinet', variants: [{ id: 12, … }, { id: 13, … }] }, … ]
// find the id you need, then place it
const p = catalog.listProducts().find((x) => x.name === 'Base Cabinet');
await products.add({ productGraphId: p.id, variantId: p.variants[0].id });
```
Response
```
[
{
"id": 5, // the PRODUCT id — pass as productGraphId
"name": "Base Cabinet",
"variants": [ // default first; full catalog records
{ "id": 12, "name": "Base Cabinet 600", "width": 600, "…": "…" },
{ "id": 13, "name": "Base Cabinet 900", "width": 900, "…": "…" }
]
}
// … one entry per product
]
```
##### `catalog.getProductVariants`
Every variant of a **product id**, in the order the SDK would pick them — the flagged default first, then by id. Use it when the default variant `getProduct` returns isn't the one you mean: variants of the same product differ in width, components and price. Returns an empty array when the id is not a product (a variant id has no variants of its own).
```
const variants = catalog.getProductVariants(5);
variants.map((v) => [v.id, v.name, v.width]); // pick the one you want
await products.add({ productGraphId: 5, variantId: variants[1].id });
```
Response
```
[
{ "id": 12, "name": "Base Cabinet 600", "productGraph": 5, "width": 600, "…": "…" },
{ "id": 13, "name": "Base Cabinet 900", "productGraph": 5, "width": 900, "…": "…" }
]
// [] → the id is not a product in this catalog
```
##### `catalog.getOptionSet`
The option-set record — its name, its type, and its option **ids**. Turn those ids into names with `catalog.getOption`. `null` when this system has no such set.
```
const set = catalog.getOptionSet(75);
set.name; // 'Cabinet Finish'
set.options.map((id) => catalog.getOption(id).name); // ['Oak', 'Walnut', …]
```
Response — real sample from a live scene · `catalog.getOptionSet(1)`
```
{
"id": 1,
"name": "Cabinet Finish",
"type": "finish_change",
"contentKind": "options",
"childOptionSetIds": [],
"sequence": 1,
"defaultOption": 65,
"options": [
69,
// … 8 more items like the one above
],
"defaultHiddenOptions": [],
"materialTargets": [
"cabinet"
],
"priceMode": "per_placement",
"default_option_id": 65,
"materials": [
"cabinet"
]
}
```
##### `catalog.getOption`
One option record by id — its name, the value it selects, its thumbnail. This is what turns the ids in `getOptionSet(...).options` into something you can show, so the pair covers a whole option set without React. `null` when the catalog has no such option.
```
catalog.getOption(752); // { id: 752, name: 'Cognac', optionSetId: 75, … }
// a whole set, resolved
const set = catalog.getOptionSet(75);
set.options.map((id) => catalog.getOption(id));
```
Response
```
{
"id": 752,
"name": "Cognac",
"optionSetId": 75,
"value": 118, // what it selects — a product, a material, a preset…
"thumbnail": "…",
"sequence": 2
}
// null → no option with that id in this system
```
##### `catalog.listOptionSets`
Every option set in this system's catalog, in `sequence` order — scene-level and product-level alike, as full records. The discovery call for the option side, the way `listProducts` is for products. When the split matters, use the two scoped readers below.
```
catalog.listOptionSets();
// [{ id: 10, name: 'Cabinet Finish', type: 'finish_change', options: [101, 102], sequence: 1 }, …]
// the id you need, by name — then its options
const finish = catalog.listOptionSets().find((s) => s.name === 'Cabinet Finish');
catalog.listOptions(finish.id).map((o) => o.name); // ['Oak', 'Walnut', …]
```
Response — real sample from a live scene · `catalog.listOptionSets()` · 15 sets in this system
```
[
{
"id": 1,
"name": "Cabinet Finish",
"type": "finish_change",
"contentKind": "options",
"childOptionSetIds": [],
"sequence": 1,
"defaultOption": 65,
"options": [
69,
// … 8 more items like the one above
],
"defaultHiddenOptions": [],
"materialTargets": [
"cabinet"
],
"priceMode": "per_placement",
"default_option_id": 65,
"materials": [
"cabinet"
]
},
// … 14 more items like the one above
]
```
##### `catalog.listSceneOptionSets`
The **scene-level** option sets — the active scene configuration's list, in backend order: layout, a scene-wide finish, “add a product”. These apply to the whole design and are the ones a host lays out in its own markup. The same partition the built-in sidebar draws (and `useOptionSets().sceneOptionSets` returns as a hook).
```
catalog.listSceneOptionSets();
// [{ id: 30, name: 'Layout', type: 'layout_change', … }, { id: 10, name: 'Cabinet Finish', … }, …]
// a scene-level picker, outside React
for (const set of catalog.listSceneOptionSets()) {
const picked = options.effective()[set.id]; // the scene-wide selection for that set
render(set.name, catalog.listOptions(set.id), picked, (optionId) => options.select(set.id, optionId));
}
```
Response — real sample from a live scene · `catalog.listSceneOptionSets()` · 11 of the 15 sets are scene-level
```
[
{
"id": 12,
"name": "Layouts",
"type": "load_configuration",
"contentKind": "options",
"childOptionSetIds": [],
"sequence": 20,
"defaultOption": 1,
"options": [
1,
// … 3 more items like the one above
],
"defaultHiddenOptions": [],
"materialTargets": [],
"priceMode": "per_placement",
"default_option_id": 1,
"materials": []
},
// … 10 more items like the one above
]
```
##### `catalog.listProductOptionSets`
The **product-level** option sets bound to one placement, in binding order — the 3D triggers the engine attaches to that piece (width, arm style, leg style, …). Omit the id to follow the current selection; `[]` when nothing is selected or the id is unknown. A set can appear in both lists: a scene-wide finish a piece also binds is real semantics, not a duplicate.
```
catalog.listProductOptionSets('p_1'); // [{ id: 5, name: 'Width', … }, { id: 13, name: 'Arm Style', … }]
catalog.listProductOptionSets(); // the selected piece's — [] with nothing selected
// appear when a piece is selected, go when it is not
on('selection.changed', ({ placementId }) => {
const sets = placementId ? catalog.listProductOptionSets(placementId) : [];
panel.replaceChildren(...sets.map((s) => picker(s, catalog.listOptions(s.id, { placementId }))));
});
```
Response — real sample from a live scene · `catalog.listProductOptionSets("p1")` · 8 sets bound to "Single Door 9\""; listOptions(2, { placementId }) then returns 8 of that set's 10 options
```
[
{
"id": 2,
"name": "Base Cabinet Type",
"type": "load_new_product",
"contentKind": "options",
"childOptionSetIds": [],
"sequence": 3,
"defaultOption": 12,
"options": [
12,
// … 9 more items like the one above
],
"defaultHiddenOptions": [],
"materialTargets": [],
"priceMode": "per_placement",
"default_option_id": 12,
"materials": []
},
// … 7 more items like the one above
]
```
##### `catalog.listOptions`
The options one set offers, in sequence order, as resolved records (`id`, `name`, `value`, `thumbnail`, …) — `getOptionSet(id).options` are ids; this is those ids looked up. Pass `{ placementId }` to narrow to what the engine currently allows on that piece; without it you get the scene-scope list. A hidden or greyed option is still listed — `useOptionSets().optionDisabledPropsFor` says which and why. `[]` for an unknown set.
```
catalog.listOptions(10); // [{ id: 101, name: 'Oak', value: 'oak', … }, { id: 102, name: 'Walnut', … }]
catalog.listOptions(5, { placementId: 'p_1' }); // only the widths the engine allows on THAT piece
```
Response — real sample from a live scene · `catalog.listOptions(12)` · the "Layouts" set
```
[
{
"id": 1,
"name": "L-Shaped",
"value": 1,
"thumbnail": "https://api-configurator.imagine.io/assets/thumbnails/layouts/l_shaped.svg",
"priceDelta": 0
},
// … 3 more items like the one above
]
```
##### `catalog.listMaterials` · `catalog.getMaterial`
Every material in this system's catalog, and one by id (`null` when unknown). Materials are what finish options point at through their `value` / material targets — useful for a swatch legend, a spec sheet, or matching a finish to your own product data.
```
catalog.listMaterials(); // [{ id: 41, name: 'Oak Veneer', type: 'wood', color: '#b08a5a', … }, …]
catalog.getMaterial(41)?.name; // 'Oak Veneer'
```
Response — real sample from a live scene · `catalog.listMaterials()` · 15 materials; getMaterial(5) is the first entry alone
```
[
{
"id": 5,
"name": "Charcoal",
"thumbnail": "https://api-configurator.imagine.io/assets/thumbnails/finishes/acrylic_color.svg",
"materialJson": { "type": "MeshPhysicalMaterial", "color": 1513239, "roughness": 0.12, "metalness": 0.1, /* … the full material record (Material.toJSON()) */ }
},
// … 14 more items like the one above
]
```
#### Evaluation
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-evaluation
##### `evaluation.last`
The last evaluation the engine answered, or `null` before the first. A frozen record: `{ at, kind, durationMs, mutation, applied, rejected, code, errors, resolvedState, pricing, warnings, optionVisibility, optionAvailability, defaultOptionOverrides, messages, events, customEffects, customDiagnostics, addedPlacements, removedPlacements, catalogVersion, refetchCatalog }`. The same payload the `evaluate.*` events carry, kept for reading after the fact.
```
evaluation.last()?.kind; // 'completed' | 'rejected' | undefined
evaluation.last()?.pricing?.grandTotal; // the engine's number
```
##### `evaluation.history`
The last 20 records, newest first — enough to see what a shopper did and how the engine answered each step.
```
evaluation.history().filter((r) => r.rejected).map((r) => r.code);
```
##### `evaluation.pending`
`true` while at least one `/evaluate/` round-trip is in flight. The imperative form of a busy indicator; `useEvaluation().pending` is the React form.
```
if (evaluation.pending()) return; // do not stack a second change on an unanswered one
```
##### `evaluation.subscribe`
Called with the new record on every completed or rejected evaluation (and with the current one when pending changes). Returns unsubscribe. For code outside React; inside React use `useEvaluation()`.
```
const off = evaluation.subscribe((r) => { if (r?.rejected) toast(r.errors[0]?.message); });
off();
```
##### `evaluation.explainOption`
Why an option is, or is not, offered right now — read from the engine's current answer, never re-derived. Returns `{ optionSetId, optionId, placementId, visible, available, selectable, reason }` where `reason` is `'hidden_by_rule'`, `'disabled_by_rule'`, `'not_available_on_placement'` (only with `placementId`), or `null` when it is offered.
```
evaluation.explainOption(10, 102); // { selectable: false, reason: 'hidden_by_rule', … }
evaluation.explainOption(5, 151, { placementId: 'p1' }); // the piece's own bindings decide
```
##### `useEvaluation`
React hook — `{ last, history, pending }`, re-rendering on every evaluation. The component form of `evaluation.last()` and `evaluation.pending()`.
```
const { last, pending } = useEvaluation();
if (pending) return ;
return ;
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"pending": false, // true while at least one /evaluate/ is in flight
"last": { // the newest record, or null before the first evaluation
"at": "2026-09-02T10:14:03.512Z",
"kind": "completed", // 'completed' | "rejected"
"durationMs": 412,
"mutation": { "addPlacement": { "…": "…" } }, // what was sent
"applied": true,
"rejected": false,
"resolvedState": { "…": "…" }, // full envelope — see products.add
"pricing": { "currency": "USD", "grandTotal": 22661, "placements": { "…": "…" } },
"warnings": [], "messages": [], "events": [],
"customEffects": [], "customDiagnostics": [],
"optionVisibility": null, "optionAvailability": null, "defaultOptionOverrides": null,
"addedPlacements": null, "removedPlacements": null,
"catalogVersion": null, "refetchCatalog": false,
"code": null, "errors": null // populated on a rejection
},
"history": [ "…" ] // the last 20 records, NEWEST FIRST (history[0] === last)
}
// Each record is Object.freeze'd — read it, never patch it.
```
#### Config
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-config
##### `config.setApiKey`
Set the org API key (sent as `X-Api-Key` on every request); `null` clears it. **Prefer the env file** — put `VITE_API_KEY=…` in `.env.local` and the SDK picks it up with no call at all. Reach for this function only when the key is not known at build time: a multi-tenant host resolving it per request, or a page that swaps orgs without a rebuild. Call it **before** `mount()`.
Resolution order, first hit wins: `config.setApiKey()` → `window.__configApiKey` (injected by the page before boot) → `import.meta.env.VITE_API_KEY` (your build). The env route is Vite's: the variable must start with `VITE_` to be exposed, and a bundler without `import.meta.env` — Next.js, webpack, a plain script tag — has nothing to read, so those hosts set the key with this function (or on `window.__configApiKey` before boot).
**A browser key is not a secret.** An env var is inlined into the bundle you ship, so whichever route you use, anyone who opens devtools can read it — the env file keeps it out of source control, nothing more. Use a key issued for browser use, scope it to the systems this page needs, and rotate it if it leaks. For a public storefront where you would rather ship no org key at all, use one of the two keyless routes: **session tokens** — pass `getToken` to `mount()` and let your server mint short-lived tokens (Quickstart, “Production: a session token”) — or an **embed link**: `/embed/ ` authenticates with the link itself and is scoped to one system.
```
# .env.local — the recommended route (no code needed)
VITE_API_KEY=YOUR_ORG_API_KEY
```
```
// …or read the variable yourself and hand it over. Do this when you want your OWN
// variable name, or when your bundler is not Vite. Any of these, before mount():
config.setApiKey(import.meta.env.VITE_ACME_CONFIGURATOR_KEY); // your name, Vite
config.setApiKey(process.env.NEXT_PUBLIC_CONFIGURATOR_KEY); // Next.js
config.setApiKey(await fetchKeyForTenant(tenantId)); // resolved at runtime
```
##### `config.setChannelId`
Set the sales-channel id (prices, hidden options, per-channel theme).
```
config.setChannelId('dealer-42'); // set the sales-channel id (prices, hidden options, per-channel theme)
```
##### `config.getChannelId`
The active channel id.
```
const channel = config.getChannelId(); // 'dealer-42' — or null when no channel is active
```
Response — real sample from a live scene · `config.getChannelId()`
```
"dealer-42"
```
#### React hooks
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-hooks
The eighteen below are the documented surface. The package exports ten more, for hosts that need the layer underneath — stable, but read their JSDoc before relying on them: `useUIState` (`{ isMobile, selectedFeatureId, selectedElementType, isLayoutLoading }`), `useUIRegions` / `useUIRegion(name)` (which UI regions are visible), `useOptionGating` (`{ disabled, hidden, managedOptionSets, featureToOptions }`), `useCatalogMaps` (`{ options, materials, features }`), `useHostedProductState` (pending / placed hosted products), `useProductOrder`, `useProductOverrides`, `usePlacementInteraction` and `useAppVersion`. Nothing else starting with `use` is exported — a grep of the source will show more names, but they are module paths and comments, not exports.
##### `useBootStatus`
Boot progress, for rendering your own loading screen instead of ours (pair it with `ui.hide()`). `ready` flips true when the configurator is usable; `progress` is 0–100 and `detail` is the current step's wording. `themeReady` tells you the backend theme has applied, so your own splash can be branded rather than flashing default colours.
```
const { ready, loading, progress, detail, themeReady } = useBootStatus();
if (!ready) return ;
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"loading": false, // the SDK is still booting
"detail": null, // human-readable step while it is — e.g. "Loading products…"
"progress": null, // 0..1 when the step knows its own progress, else null
"themeReady": true, // the theme has been applied — paint without a flash
"catalogLoading": false, // catalog fetch in flight
"configLoading": false, // configuration fetch in flight
"ready": true // !catalogLoading && !configLoading — safe to mount
}
// `ready` ignores `loading`: it answers "is the data there", not "is the overlay up".
```
##### `useCopilotAvailable`
Whether the AI assistant's backend answered its probe — `true` / `false`. Gate your own chat entry point on it so you never render a button that opens a dead panel.
```
const chatReady = useCopilotAvailable();
return chatReady ? : null;
```
Returns — the hook's return — a bare boolean, not an object
```
false
// true only inside the SDK's Copilot provider AND with the chat runtime reachable
// (mountConfigurator probes it at boot). Outside the provider the context default
// applies, so a host component rendered above our root always reads false.
```
##### `useFormatters`
Locale-aware formatters that re-render when `ui.setLocale` / `ui.setCurrency` change — so your own price display never disagrees with ours.
```
const { locale, rtl, formatMoney, formatNumber } = useFormatters();
formatMoney(1299); // '€1,299.00' — the active currency
formatNumber(2400.5); // '2.400,5' in de-DE
rtl; // true for ar/he/… — mirror your own chrome
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"locale": "en-US", // the SDK locale (ui.setLocale), else the browser's
"rtl": false, // derived from the locale — for your own dir handling
"formatMoney": "ƒ (amount, currency?) → \"$22,661.00\"",
"formatNumber": "ƒ (value, Intl.NumberFormat options?) → \"1,250\""
}
// Both functions close over the current locale, so they re-render with it. The
// currency argument falls back to the channel's configured currency.
```
##### `useGenerateAssets`
What a custom Generate button needs: the trigger, and whether a run is in flight (so you can disable it and show a spinner). The results themselves arrive via `quote.images()` / `quote.generationStatus()`.
```
const { handleGenerateAssets, isGenerating } = useGenerateAssets();
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"isGenerating": false, // one run at a time — gate your button on this
"handleGenerateAssets": "ƒ ({ families? }) → Promise"
}
// handleGenerateAssets dispatches the ASSETS_GENERATE intent (so host middleware can
// see or refuse a run) and resolves when the pipeline finishes. Results land in the
// generated-assets store, not in the return value.
```
##### `useIcon`
Render one of our glyphs while honouring a host's `ui.registerIcon` override — so a component you write shows the customer's icon set, not ours. Pass the key and the built-in to fall back to; it re-renders if the override changes.
```
const Icon = useIcon('delete', DefaultTrashIcon); // your registerIcon('delete', …) override, else the built-in you pass
return ;
```
Returns — the hook's return — a component, not data
```
ƒ MyChevron // the registered override for that name
// …or exactly the `Builtin` you passed, when nothing is registered under the name.
// Render it; do not call it. The hook also subscribes the caller, so an icon
// registered after mount appears without another render being forced elsewhere.
```
##### `useLabel`
React hook — one UI string by key, re-rendering when labels change (e.g. after `ui.setLabels`).
```
const label = useLabel('panel.delete', 'Delete'); // (key, fallback) — re-renders when ui.setLabels changes it
```
Returns — the hook's return — a string
```
"Remove piece"
// The override for that key if one is set (ui.setLabels or the theme's `labels`),
// else the `fallback` you passed. An override set to "" returns "" — that is the
// documented way to hide a string, so test for `=== ''`, not for falsiness.
```
##### `useLabels`
Reactive t(key, fallback) for wording.
```
const t = useLabels();
const title = t('myPanel.title', 'Design your piece');
return title ?
{title}
: null; // '' from a theme/admin = hide it — render nothing
// reactive t(key, fallback): works for the built-in keys AND your own — a host can
// invent a key like 'myPanel.title' and let a theme/admin translate it via setLabels
```
Returns — the hook's return — one function, not a map
```
ƒ t(key, fallback?) → string
// One subscription, then t() per string — the point of this hook over useLabel.
t('panel.delete', 'Delete') // → "Remove piece" (overridden)
t('panel.add', 'Add') // → "Add" (no override — your fallback)
```
##### `useOptionSets`
**The hook you build a custom option panel from** — our own sidebar renders entirely from it, so nothing it needs is missing. It hands you the option sets plus the four things that are easy to get wrong on your own: which options are _available_ right now, which are hidden, whether the pick applies to a selected product or the whole scene (`scope`), and a `select` that routes through the same dispatch our sidebar uses — so there is no second path into the engine.
```
const { optionSetList, getOptionsForSet, visibleOptions, optionDisabledPropsFor,
getEffectiveSelection, select, scope, materials } = useOptionSets();
optionSetList.map((set) => { // an ARRAY; `optionSets` is the same keyed by id
const opts = visibleOptions(set.id, getOptionsForSet(set)); // drop hidden BEFORE render
const selected = getEffectiveSelection(set.id); // after defaults + rules
return opts.map((o) => {
const { disabled, disabledReason } = optionDisabledPropsFor(set.id, o);
const swatch = materials[o.value]; // keyed by option VALUE, not id
return ;
});
});
scope.placementId; // whose options these are — null = the whole scene
```
Shapes
`optionSets` is a **record keyed by id** — the store's own shape — and `optionSetList` is the same sets as an array. Use whichever your rendering wants; a defensive `Array.isArray(optionSets) ? …: []` renders an empty panel with no error, which is how this was found. `materials` is keyed by an option's **`value`**, not its `id`: a finish option's value is the material it applies, and that is the key.
Two scopes
With nothing selected, a set is **scene-wide**. Select a product and the _same_ hook returns that product's sets — narrowed to its backend bindings, reading from its own selections — and `scope.placementId` tells you which. To render a scene-level panel that ignores the selection, call `useOptionSets({ placementId: null })`; to render a picker for one specific piece, pass its id. One flat `useOptionSets()` rendered regardless of scope collapses the two levels — Width and Frame Size appear scene-wide next to Cabinet Finish.
**Which sets are scene-level?** `useSystemConfig().scene[activeSceneConfigId].optionSets` is the ordered list of their ids, with `activeSceneConfigId` from `useSceneState()`. A product's own sets come from `useProduct(placementId).product.options`.
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"optionSets": { // RECORD keyed by option-set id
"1": { "id": 1, "name": "Cabinet Finish", "type": "finish_change",
"sequence": 1, "options": [69, "…"], "materialTargets": ["cabinet"] },
"2": { "…": "…" }
},
"optionSetList": [ "…" ], // the same sets as an ARRAY
"sceneOptionSets": [ "…" ], // scene-level sets: render these always
"productOptionSets": [ "…" ], // the focused piece's bound sets — [] with nothing selected
"features": "…", // legacy alias of optionSets (same object)
"options": { "65": { "id": 65, "name": "Walnut", "…": "…" } }, // catalog options by id
"materials": { "…": "…" }, // catalog materials by id
"hiddenOptions": "Set(0) {}", // a JS Set — hiddenOptions.has(id), NOT an array
"scope": { "placementId": "p1", "isPlacementScoped": true },
"getOptionsForSet": "ƒ (optionSet) → option[]", // sequence-ordered, binding-narrowed
"getOptionsForFeature": "ƒ (optionSet) → option[]", // legacy alias
"select": "ƒ (optionSetId, optionId, optionSet?) → void",
"getSelection": "ƒ (optionSetId) → optionId | undefined", // this scope's own pick
"getEffectiveSelection": "ƒ (optionSetId) → optionId | undefined", // own pick, else scene-wide
"optionDisabledPropsFor": "ƒ (optionSetId, option) → { hidden, disabled, disabledReason }",
"visibleOptions": "ƒ (optionSetId, options[]) → option[]"
}
// `hiddenOptions` being a Set is the one shape that bites: JSON.stringify prints {}
// and `.includes` throws. `scope.placementId` is null (and productOptionSets empty)
// whenever nothing is selected — that is scene scope, not an error.
```
##### `usePrice`
React hook — the live scene price: `{ grandTotal, currency, placements }`, re-rendering whenever the engine re-prices.
```
const price = usePrice(); // live total
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"grandTotal": 22661, // engine-resolved; null before the first evaluation
"currency": "USD",
"placements": { // per-placement, exactly as the engine sent it
"p1": { "unitPrice": 824, "adjustments": [ { "optionSetId": 12, "label": "L-Shaped", "amount": 0 } ] },
"p2": { "…": "…" }
},
"aggregateAdjustments": [] // scene-level cost lines: [{ optionSetId, optionId, label, unitAmount, count, amount }]
}
// Never computed locally. Σ placement unitPrices + Σ aggregateAdjustments = grandTotal,
// so a host summing only `placements` is short by the aggregate lines. Frozen.
```
##### `useProduct`
One product, reactively. Pass a **placement id** (`'p1'`) to get that placed product — the same row `useProducts()` lists, plus `.product`, its catalog record — re-rendering whenever it moves, re-sequences or changes variant. Pass a catalog product/variant id instead to get just the catalog record. `null` when neither matches.
```
const piece = useProduct('p1'); // a PLACED product by placement id — { placementId, productId, variantId, sequence, position, …, product }
piece?.product?.name; // `.product` is its catalog record, so the name/width/options are one hop away
const record = useProduct(12); // given a catalog product/variant id instead → that catalog record
```
Returns — the hook's return — two shapes, decided by the id you pass
```
// A PLACEMENT id (a string the engine minted) → the placed piece, with its catalog record:
{
"placementId": "p1",
"variantId": 9,
"productId": 9,
"sequence": 0,
"placementGroup": "floor",
"position": [0, 0, 0],
"rotation": [0, 0, 0],
"product": { "id": 9, "name": "Single Door 9\"", "…": "…" } // null if unresolved
}
// A CATALOG id (an integer) → that catalog record alone, with no placement keys:
{ "id": 9, "name": "Single Door 9\"", "productGraph": 3, "…": "…" }
// null when the id matches neither. The scene is checked first, so a placement id
// never falls through to the catalog. Frozen either way.
```
##### `useProducts`
React hook — every placed product as frozen `{ placementId, productId, variantId, sequence, placementGroup, position, rotation }` rows, re-rendering as the scene changes.
```
const products = useProducts(); // all placed products
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
[
{
"placementId": "p1", // added by the hook; the rest is the engine's row
"variantId": 9,
"productId": 9,
"sequence": 0,
"placementGroup": "floor",
"position": [0, 0, 0],
"rotation": [0, 0, 0],
"locked": false // …plus whatever else the engine attached to the piece
},
"…"
]
// Sorted by the backend `sequence` (insertion order only as a fallback), frozen, and
// [] before the first scene loads — never null.
```
##### `useRenderImage`
A view's rendered image for the shopper's current configuration, kept up to date: `{ url, loading, error }`. When the shopper changes an option or the layout, it fetches the new image; the previous `url` stays until the next one arrives, so the picture never goes blank in between. `useRenderImage(viewId, { tier?, frame?, format? })` — `tier` defaults to `'preview'` (page-sized); pass `'full'` for full resolution. See Renders for the one-off calls.
```
function ViewImage({ viewId }) {
const { url, loading } = useRenderImage(viewId);
if (!url) return null;
return ;
}
```
##### `useSceneState`
“What is the scene right now?” in one subscription. Three of its fields have no other reader: `activeSceneConfigId` (which layout preset is applied — for marking the active one in your own picker), `placementSelections` (every placed product's option picks at once, where `useOptionSets` only gives you the current scope's), and `locked` (a backend rule locked the selected piece — a custom option panel must not offer changes on it). Also carries `instances`, `selectedId` and the scene-wide `sceneSelections`.
```
const { instances, selectedId, locked, placementSelections,
activeSceneConfigId, sceneSelections } = useSceneState();
// mark the active layout in your own picker
presets.map((p) => ({ ...p, current: p.id === activeSceneConfigId }));
// never offer option changes on a locked piece
{!locked && }
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"instances": { "p1": { "…": "…" } }, // placed products, keyed by placement id
"selectedId": null, // the selected placement, or null
"locked": false, // is that selection locked by a rule?
"placementSelections": { "p1": { "41": 119 } }, // placementId → { optionSetId: optionId }
"activeSceneConfigId": 1, // the layout preset in effect
"sceneSelections": { "10": 101 } // scene-wide picks
}
```
##### `useSelection`
What the shopper has selected — `{ placementId, isSelected, piece }`, where `piece` is the placed product's full row (or `null`). Re-renders on every selection change, so it is how a custom panel or inspector follows the scene.
```
const { placementId, isSelected, piece } = useSelection();
if (!isSelected) return
Select a piece to configure it
;
return ;
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"placementId": "p1", // null with nothing selected
"isSelected": true, // === (placementId != null)
"piece": { // the placed product's full row, or null
"variantId": 9, "sequence": 0, "placementGroup": "floor",
"position": [0, 0, 0], "locked": false, "…": "…"
}
}
// `piece` carries no placementId of its own — that is the sibling key. Frozen.
```
##### `useSelectionActions`
Actions for the selected piece (move/duplicate/delete + price).
```
const { selectedInst, panelActions, priceInfo } = useSelectionActions();
// selectedInst — the selected placement record, or null
// panelActions — { onMoveLeft, onMoveRight, onDuplicate?, onDelete, disabledActions } or null when nothing is selected
// priceInfo — { unitPrice, adjustments, currency } or null
if (panelActions?.onDuplicate) panelActions.onDuplicate();
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"selectedInst": { "id": "p1", "variantId": 9, "…": "…" }, // the live instance, or null
"swapOrder": "ƒ (idA, idB) → void",
"panelActions": { // null when nothing is selected — guard before spreading
"targetId": "p1",
"placementId": "p1", // same id, under the name every other surface uses
"onMoveLeft": "ƒ () → void",
"onMoveRight": "ƒ () → void",
"onDuplicate": "ƒ () → void", // undefined when the piece may not be duplicated
"onDelete": "ƒ () → void",
"disabledActions": {
"moveLeft": { "disabled": true, "reason": "Already at the start" },
"moveRight": undefined, // undefined = allowed
"duplicate": undefined
}
},
"priceInfo": { "unitPrice": 824, "adjustments": [ "…" ], "currency": "USD" }
}
// Every verb dispatches an intent, so host middleware can wrap or cancel our buttons.
// Neighbour moves are scoped to the piece's own placementGroup: "left" never crosses
// rows. Delete is confirm-then-commit — the piece stays put if the engine refuses.
```
##### `useSystem`
Which configurator is loaded — `{ id, name, configuratorKey }`. For showing the product line's name in your own chrome, or branching when one page mounts several systems.
```
const { id, name } = useSystem();
return
{name}
; // e.g. 'Nordic Living Room'
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"id": 1, // null until the system is loaded
"name": "Acme Kitchens",
"configuratorKey": null // the backend's `configurator` field — null when it ships none
}
```
##### `useSystemConfig`
The loaded system's configuration maps — `{ scene, product, features, rulesReady, rulesTriggerIndex }`. `scene[id].optionSets` is the ordered list of **scene-level** option-set ids (see `useOptionSets` for why that split matters); `product[id]` the per-product configurations; `features` every option set by id. `rulesReady` flips true once the engine's rules have loaded — gate a custom panel on it so it doesn't paint pre-rule defaults.
```
const { scene, rulesReady } = useSystemConfig();
const { activeSceneConfigId } = useSceneState();
const sceneLevelIds = scene[activeSceneConfigId]?.optionSets ?? []; // ordered, scene-wide
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
"scene": { "1": { "id": 1, "sequence": 0, "scene_option_id": 12, "…": "…" } }, // scene configurations, by id
"product": { "3": { "…": "…" } }, // product configurations, by product-graph id
"features": { "1": { "…": "…" } }, // option-set configuration, by set id
"rulesReady": true, // rules have loaded — gate rule-dependent UI on it
"rulesTriggerIndex": { // Maps, not objects: .get(id), and {} under JSON
"option_selected": "Map(14)",
"option_deselected": "Map(0)",
"component_loaded": "Map(2)",
"component_removed": "Map(0)"
}
}
// All three maps are replaced together when a system loads, which is why they are one
// hook. Every value is {} before boot finishes — never null.
```
##### `useComponentRegistry`
Subscribe a custom shell to the component-override registry. Call it once near the top; then `ui.resolveComponent(name, Default)` anywhere below — inside loops too — and the shell repaints when something registers later (a lazily-loaded extension). Without it you either resolve in the render body and hand React a new component identity every pass, or memoise and miss late registrations. Every built-in shell uses exactly this pair.
```
useComponentRegistry(); // once, near the top
const Tile = ui.resolveComponent('OptionThumbnail', DefaultTile); // anywhere below
```
Returns — the hook's return — an opaque version, not the registry
```
3
// A change counter from the registry's external store. The VALUE is not the contract:
// call the hook for the subscription, then use resolveComponent() freely below —
// including in loops, where a hook per lookup is impossible. Without the subscription,
// an override registered after mount stays invisible until something else re-renders.
```
##### `useToolbar`
Everything a custom toolbar needs, from one subscription: the current view state (`is3D`, `showWalls`, `showDimensions`, `showFloor`, `showCeiling`, `isFullscreen`, `isLayoutLoading`, `canUndo`, `canRedo`, `isMobile`), the matching actions, and `isOn(key)` — which tells you whether the backend/channel has that button enabled at all, so your toolbar hides what the admin turned off. Actions dispatch intents, so host middleware sees your buttons exactly like ours.
```
const { is3D, showWalls, canUndo, isOn,
toggleView, toggleWalls, undo, resetCamera } = useToolbar();
{isOn('toggle2d3d') && }
{isOn('walls') && }
{isOn('undo') && }
```
Returns — the hook's return · keys verbatim from the source, values from the live scene sampled above
```
{
// chrome
"guiVisible": true,
"isMobile": false,
"isOn": "ƒ (toggleKey) → boolean", // uiToggles gate: absent key = on
"uiToggles": { "fullscreen": false },
// view state
"is3D": true,
"showDimensions": false,
"showWalls": true,
"showFloor": true,
"showCeiling": false,
"showWallGuide": false, // auto-clears itself after 5s
"isLayoutLoading": false,
"isFullscreen": false,
"isLandscapeMode": false,
"canUndo": true,
"canRedo": false,
"sceneCapabilities": { "walls": true, "…": "…" }, // hide what this configurator has not got
// actions — BOTH spellings ship; the unprefixed ones are the public shape
"toggleView": "ƒ () → void", "handleToggleView": "ƒ () → void",
"toggleDimensions": "ƒ () → void",
"toggleWalls": "ƒ () → void", "handleWallsToggle": "ƒ () → void",
"toggleFloor": "ƒ () → void",
"toggleCeiling": "ƒ () → void",
"toggleFullscreen": "ƒ () → void", "handleFullscreen": "ƒ () → void",
"toggleLandscape": "ƒ () → void", "handleLandscapeToggle": "ƒ () → void",
"resetCamera": "ƒ () → void", "resetCameraToDefault": "ƒ () → void",
"undo": "ƒ () → void", "handleUndo": "ƒ () → void",
"redo": "ƒ () → void", "handleRedo": "ƒ () → void"
}
// An undefined action is silent — `onClick={t.toggleVieW}` neither fires nor throws —
// which is why both spellings exist. Check `isOn(key)` before rendering a button the
// backend's uiToggles may have switched off.
```
#### Lifecycle & events
Permalink: https://configurator-platform.imagine.io/sdk/index.html#fn-lifecycle
##### `addMiddleware`
Run your code around **every action the SDK performs**. Each one is first described as an _intent_ — `{ type, …payload }`, e.g. `'option.select'`, `'product.add'`, `'product.remove'`, `'product.move'`, `'quote.open'` — and passed to your function as `(intent, next)`. Where you call `next` decides what happens: before it, after it, instead of it, or not at all (which cancels). It may be async, so you can await your own API before the default runs. Returns an unregister function.
```
const off = addMiddleware(async (intent, next) => {
// BEFORE + CANCEL: check your stock API before the engine hears about it
if (intent.type === 'option.select') {
const inStock = await myApi.check(intent.optionId);
if (!inStock) { ui.notify({ type: 'error', message: 'Out of stock' }); return { cancelled: true }; }
}
const result = await next(); // the SDK's own behaviour runs here
// AFTER: everything the shopper does, in one place
analytics.track(intent.type, intent);
return result;
});
off(); // stop intercepting
```
**Seeing what the configurator does** — the quickest way to learn the intents: log each one with its payload and what the engine did about it. Paste this into your app (or the browser console) and click around.
```
addMiddleware(async (intent, next) => {
console.groupCollapsed('[intent]', intent.type);
console.log('payload', intent); // e.g. { type: 'option.select', optionSetId: 75, optionId: 752 }
const result = await next();
console.log('result', result); // the engine's answer — applied / rejected
console.groupEnd();
return result;
});
```
Every intent the SDK dispatches, with the payload your middleware receives alongside `type`. The first six round-trip to the engine; the rest are local UI actions that never call the backend but are still buttons you may want to wrap.
| intent.type | Fires when | Payload |
| --- | --- | --- |
| **Engine round-trips** |
| `option.select` | an option is picked (any scope) | `optionSetId`, `optionId`, `optionSetType` |
| `product.add` | a product is placed — palette, insert tile or duplicate | `productGraphId`, `variantId`, `placementGroup`, `sequence` |
| `product.remove` | the selection panel's delete | `placementId` |
| `product.move` | move-left / move-right | `placementId`, `direction` (`'left'` · `'right'`) |
| `product.duplicate` | the selection panel's duplicate | `placementId` |
| `layout.change` | a layout preset is chosen | `optionSetId`, `optionId` |
| **Local UI** — no backend call |
| `view.mode` | the 2D/3D toggle | `mode` (`'2d'` · `'3d'`) — the mode being switched TO |
| `view.walls` | the walls toggle | `next` (boolean) |
| `view.dimensions` | the dimensions toggle | `next` (boolean) |
| `view.fullscreen` | the fullscreen button | `next` (boolean) |
| `history.undo` · `history.redo` | undo / redo | — (type only) |
| `scene.reset` | `scene.reset()` — the scene is emptied | — (type only) |
| `quote.open` | the quote opens — its own verb, so “gate the quote behind a login” is one match | — (type only) |
| `assets.generate` | Generate Assets is triggered | `families` (which artefacts, or `null` for all) |
| `ui.modal.open` | any modal opens | `key`, `data` |
Good to know
Middleware runs in registration order and ends in the SDK's handler. One that **throws is skipped** — the action still happens and an `extension.failed` event fires — so a broken extension can never brick a button. And middleware shapes the **request only**: it can gate or annotate what is sent, but the resulting scene and prices always come from the engine.
**Just want to see what fires?** Add `?debug=intents` to the URL and every action is logged as `[sdk.intent] {payload}` — no code, no middleware to unregister.
##### `boot`
Boot the engine/catalog/scene without mounting UI. Takes the same options as `mount()` — `systemId`, the routing hooks, and `getToken` for session-token auth. Returns { cancel() }.
```
const b = boot({ systemId: 1 });
// public page: boot({ systemId: 1, getToken: async () => (await fetch('/configurator-token')).json() });
// later: b.cancel();
```
##### `configure`
Register many extensions at once; returns one teardown.
```
const teardown = configure({
theme: brandTheme,
labels: { 'panel.delete': 'Remove piece' },
events: { 'evaluate.completed': syncCart },
});
// teardown() reverses all of it
```
##### `load`
Load a backend system’s catalog + configuration.
```
await load(3); // load a backend system's catalog + configuration
```
##### `mount`
Render the full configurator into a DOM element (selector or node) and boot it. Options: `systemId` — which backend system (configurator) to load; advanced routing hooks `resolveInitialSystemId`, `resolveConfigurator`, `resolveConfiguratorKey`, `resolveInitialChannelId` for multi-configurator hosts; `getToken` — an async callback that returns a short-lived session token from your server, used _instead of_ the org API key on a public page (Quickstart, “Production: a session token instead of the key”). Returns `{ unmount }`.
```
const app = mount('#root', { systemId: 1 });
// options: systemId, getToken?, resolveInitialSystemId?, resolveConfigurator?,
// resolveConfiguratorKey?, resolveInitialChannelId?
// public page — no org key in the bundle:
// mount('#root', { systemId: 1, getToken: async () => (await fetch('/configurator-token')).json() });
app.unmount(); // tear it down
```
##### `off`
Unsubscribe from an event.
```
const handler = (pricing) => cart.update(pricing);
on('price.changed', handler);
off('price.changed', handler); // detach exactly that handler
```
##### `on`
Subscribe to an SDK lifecycle event; returns an unsubscribe function. `ready` and `scene.ready` replay to late subscribers; everything else fires live only.
```
const off = on('price.changed', (pricing) => updateCart(pricing));
on('*', (name, payload) => analytics(name, payload)); // firehose — '*' gets (name, payload)
```
Possible values — event name
`ready` the SDK booted: catalog loaded, initial scene applied
`scene.ready` the 3D scene is mounted and rendering
`option.selected` an option was picked — `{ optionSetId, optionId, optionSetName, optionName }`
`product.added` a product was placed — `{ variantId, productGraphId, placementIds }`
`product.removed` a placement was removed — `{ placementId }`
`product.moved` a placement was reordered — `{ placementId, sequence }`
`layout.changed` a layout preset was applied — `{ presetId }`
`selection.changed` the selected product changed — `{ placementId, componentId }`, both null on deselect
`price.changed` pricing recalculated — payload is the engine’s pricing envelope
`evaluate.started` an engine round-trip began — `{ mutation }`
`evaluate.completed` the engine applied a change — `{ mutation, applied, resolvedState, pricing }`
`evaluate.rejected` the engine refused a change — roll external state (a cart) back on this
`error` an engine call failed — `{ op }`
`extension.failed` a host extension (middleware) threw — `{ where, intent, message }`
`*` every event — handler receives `(name, payload)`, name first
##### `onBackendEvent`
Subscribe to events your backend rules emit (emit_event).
```
onBackendEvent('premium_fabric_chosen', ({ payload }) =>
ui.notify({ message: payload.note }));
```
##### `registerEffectHandler`
Give meaning to an effect type your admin rules use that the SDK does not ship. A rule's `customEffects[]` arrive on the evaluation that fired it; each one is routed to the handler registered for its `type`. One handler per type — registering again replaces it; returns an unregister. A type with no handler is dropped silently, and a handler that throws is logged and skipped, never breaking the render. Payload: `{ ruleId, type, params, placementId? }`.
```
registerEffectHandler('show_popup', (eff) => ui.openModal('promo', eff.params)); // eff.params from the admin rule
```
##### `once`
Subscribe to the next occurrence of an event.
```
once('scene.ready', () => console.log('scene ready')); // subscribe to the next occurrence of an event
```
##### `history.undo`
Step the scene back to the state before the last change — placements, options and moves all revert together.
```
history.undo(); // undo the last action
```
##### `history.redo`
Re-apply the change that undo just reverted (available until a new change forks history).
```
history.redo(); // redo
```
##### `history.canUndo`
True if undo is available.
```
if (history.canUndo()) { /* enable the button */ } // true if undo is available
```
Response — real sample from a live scene · `history.canUndo()`
```
true
```
##### `history.canRedo`
True if redo is available.
```
const can = history.canRedo(); // e.g. disable your own redo button when false
```
Response — real sample from a live scene · `history.canRedo()`
```
false
```
When it doesn't work
### Troubleshooting
Permalink: https://configurator-platform.imagine.io/sdk/index.html#troubleshooting
| Symptom | Cause & fix |
| --- | --- |
| `npm install` fails with `ERESOLVE` | Two causes. **React 18**: the package was installed on its own, so npm picked the React 19 versions — name the React 18 ones in the same command: `npm install @imagineio/configurator-sdk react@^18.2 react-dom@^18.2 three@~0.159.0 @react-three/fiber@^8.15 @react-three/drei@^9.88 @react-three/postprocessing@^2.16 postprocessing@~6.36.0`. **React 19**: the app already has three.js 0.187 or newer, which the SDK does not accept yet — run `npm install @imagineio/configurator-sdk three@~0.186.0`. `--legacy-peer-deps` only hides the conflict: the mismatched versions are still installed. |
| `ERESOLVE` after moving an app from React 18 to React 19 | `package-lock.json` still holds the React 18 3D packages (`@react-three/fiber@8`), which do not accept React 19. Remove them and reinstall from scratch: `npm uninstall three @react-three/fiber @react-three/drei @react-three/postprocessing postprocessing`, delete `node_modules` and `package-lock.json`, then run `npm install react@^19.3.1 react-dom@^19.3.1` and `npm install -D @types/react@^19.3.0 @types/react-dom@^19.3.0`. npm then adds the React 19 versions for the SDK. |
| A blank page for a second or two _before_ our loading screen | What is left is your own bundle: nothing can paint until the SDK’s JS has downloaded and parsed, and `ui.setLoading()` cannot help because there is no tree to render it yet. Paint your own placeholder in `index.html` and drop it when the scene exists — it must be a **sibling** of the mount element, since React clears that element’s children on its first commit: ` Loading… ` `scene.onReady(() => document.getElementById('boot-splash')?.remove());` The SDK’s own share of that wait is gone as of 2026-09-09: the boot no longer queues behind the chat-availability probe, so our loader appears as soon as the theme resolves rather than after `/warmup` answers. |
| Console shows `401 Unauthorized` | With `getToken`: your token route returned an expired or invalid token, or the key behind it was revoked — the SDK re-asks once and replays, so a persistent 401 means the route itself is answering wrongly (check it in the browser). Without it: missing or wrong API key. Set `VITE_API_KEY` in `.env.local` and restart the dev server (Vite reads env files at startup, so an edit mid-session does nothing), or call `config.setApiKey('…')` **before** `mount()`. The console line names the reason: missing, invalid, or revoked. |
| Session token refused (`401` / `403` with a `detail`) | The SDK re-asks your `getToken` route once and retries, so a refusal that persists is your route or the token it returns. The `detail` says which: - _Send X-Api-Key (an SDK session token cannot mint another one)._ — the token endpoint was called with a session token. Only your server, with the key, can request tokens. - _Session token has expired._ — older than 30 minutes; your route is returning a stale token instead of asking imagine.io again. - _Session token has been revoked / invalidated._ — the key behind it was revoked, or your org reset all tokens. Request with a valid key. - _Organization is not active._ — subscription paused or cancelled; see billing in the admin panel. - `403` _This API key is read-only; it can only mint 'catalog'-scoped tokens._ — a read-only key asked for `session`. Use a read & write key or request `catalog`. - `403` origin mismatch — the token is bound to a different `origin`. Request it with the page's origin, or omit the field. - `404` _System 12 not found in your organization._ — wrong `system_id`; check the id in the admin panel. Also accepted by the API, if your environment cannot set the Authorization header: `X-Sdk-Token: ` or `?sdk_token=`. |
| Models never appear; network shows 404 on `/assets/draco/…` | The static assets aren't reachable. Add the Vite plugin — `imagineConfigurator()` from `@imagineio/configurator-sdk/vite` (Quickstart, “Adding to an existing app”) — or copy them manually: `cp -r node_modules/@imagineio/configurator-sdk/static/* public/`. |
| Chat shows “Not connected” | The AI runtime isn't reachable from the browser. On load the SDK logs `[sdk] copilot probe: → …` — check that request in the Network tab (firewall/VPN are the usual causes) and share the console line with your imagine.io contact if it persists. |
| Blank page + “Multiple instances of Three.js” warning | Another dependency bundles its own `three`. The Vite plugin (Quickstart, “Add the Vite plugin”) dedupes automatically; without it, add `resolve: { dedupe: ['three', 'react', 'react-dom', '@react-three/fiber'] }` to `vite.config.js`. |
| A changed SDK file has no effect (you edited or copied files into `node_modules`) | Vite serves a _pre-bundled_ copy of the package from `node_modules/.vite/deps`, and that cache is keyed on your lockfile and config, not on file contents — so a hand-copied file is never seen. Delete `node_modules/.vite` and restart the dev server, or start it once with `npx vite --force`. A normal `npm install` of a new version changes the lockfile and invalidates the cache by itself. |
| Chat sends but never answers (the user message appears, no reply; the console shows a `405` on the chat runtime's `/info` route) | Your install resolved a newer chat client library than the runtime speaks (`npm ls @copilotkit/react-core`). The SDK pins the tested pair (`1.59.5`); reinstall so the pin applies, and do not add your own chat-client dependency with a wider range. |
| An override/registration “does nothing” | Check it landed: `ui.listComponentOverrides()` / `ui.listLayouts()` / `placement.listStrategies()`. For layouts, read `ui.activeLayout()` first — the backend may have selected a different shell than the one you replaced. |
| Theme looks half-applied (cards stay white) | You set `colors.background` without `colors.surface` — `surface` is what cards, dialogs and panels read. |
| Placement tiles never appear | Two requirements: a product must be **armed** (`products.anchor(…)` or a palette click), and a tile renderer must be registered (`placement.registerTargetRenderer`) — the SDK ships no tile of its own. |
| Pieces overlap or fly apart in a custom strategy | Footprint units — `ctx.getDims()` is metres, catalog `width` is inches; and `computeLayout` rotation is radians while `computeTargets` is degrees. |
Still stuck? Send your imagine.io contact the console output including any `[sdk]` lines — they name the exact URL or registration that failed.
---
# Admin guide — setting up a catalog, rules, systems, links, channels and billing in the dashboard
Source: https://configurator-platform.imagine.io/admin-guide/index.html
Admin guide
## Everything you can do in the dashboard.
A configurator shows exactly what your organization's catalog says: the parts, what they are
made of, which choices a shopper gets, and the rules that decide what is allowed. This guide
walks the dashboard screen by screen — first the setup chain in the order it has to happen,
then every other page, then the handful of things that catch people out.
Getting in
### Your organization, your team, and where to find help.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#getting-in
Signing up creates an organization. Everything you build belongs to it, and everyone you add sees the same catalog.
#### Sign up and sign in
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#sign-up
[admin-configurator.imagine.io](https://admin-configurator.imagine.io/)
Sign up with an organization name, an email and a password, or with Google or GitHub. You must accept the Terms of Use and Privacy Policy to create an account — the box sits just above the Sign up button and applies to the social buttons too. The first user becomes the organization's **owner**. Forgotten your password? **Forgot password?** under the sign-in form emails you a reset link.
#### Switching workspaces
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#workspaces
Top-left — your organization's name
If you belong to more than one organization, the name at the top left is a switcher. Pick another and every page reloads under that organization: its catalog, its systems, its billing. The header shows which one you are in, with its **ID** and a copy button — support will ask for that ID, so it is one click away.
[Image: The workspace switcher open at the top left, listing the organizations this user belongs to]
**Top-left switcher.** Every organization you can act in. Switching changes what every page shows; nothing is shared between them.
#### Roles
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#roles
[Settings › Users](https://admin-configurator.imagine.io/users)
Three roles, set per person. Owners and admins see everything under Settings; members see the catalog and scenes but cannot change them.
- **Owner** — everything, including transferring ownership to someone else.
- **Admin** — everything the owner can do, except transfer ownership. Users, branding, API keys and billing are all included.
- **Member** — read-only across the catalog, scenes and logic.
**Only one owner.** To hand the organization to a colleague, open them under Users and use **Transfer ownership**. You become a member.
#### Help
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#help
Top right — Help
The **Help** button opens a drawer with this guide, the SDK guide for developers, the SDK starter repository on GitHub, a **Contact support** form, and the support address. The form opens in place — you keep the screen you were on — and it already knows your organization and the page you came from, so you only describe what happened. It takes attachments, so a screenshot goes straight in.
[Image: The Help drawer open on the right, listing the admin guide, SDK guide, SDK starter repo, npm package, Contact support and the support e-mail]
**Help.** Top right on every page. The guides, the starter repo, and a support form that opens without leaving the screen you are on.
The **assistant** in the bottom-right corner is covered in its own section below — it does considerably more than answer questions.
Dashboard
### A count of everything in the catalog.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#dashboard
The first page after signing in. Each card is a total and a shortcut: click one to open that list.
[Image: The dashboard grid of counts: product graphs, product variants, materials, components, option sets, options, configurable systems, presets, rules, constraints, sales channels and projects]
**Dashboard.** Counts for product graphs, variants, materials, components, option sets, options, systems, presets, rules, constraints, sales channels and saved projects. An empty organization shows zeros here — that is what a developer sees as an empty scene.
On the Free plan a banner above the cards says the organization is **non-commercial** and its configurators carry the imagine.io watermark, with an **Upgrade** button. Pages your plan does not include show an Upgrade pill in the sidebar and open to an explanation rather than disappearing — see Plan and billing.
The assistant
### Ask it where things are. Or ask it to do them.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#assistant
The sparkle button in the bottom-right corner of every page opens the **Admin Assistant**. It knows this dashboard, it knows your catalog, and it can change your catalog for you. Included on every plan.
[Image: The Admin Assistant panel open on the right of the dashboard, with a question answered as steps and links]
**Admin Assistant.** Opens as a side panel; the page you were on stays put. Answers name the exact page and link to it.
#### Ask it things
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#assistant-ask
It answers in terms of the dashboard you are looking at, not in developer terms: which page something lives on, what a field means, how to get from here to there. Where a page is the answer, it gives you a link straight to it. When a question is outside what it can do — a bug, an invoice, a person — it points you at the guides or the support form rather than guessing.
#### Ask it to do things
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#assistant-do
Describe what you want and it works in the catalog directly, then tells you what it did with links to each thing it touched:
- Create, edit or remove materials, components, products, variants, options, option sets, rules, constraints and more.
- Add options to an option set, or take them out.
- Wire a finish or part option to the component it swaps in, by name.
- Attach components and option sets to a product or a variant; add variants to a preset.
- Open a system's draft and add option sets to it.
**Review before you publish.** Everything it creates lands in your drafts, exactly as if you had typed it. Check its summary, open anything you are unsure of, then publish yourself.
#### Give it files
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#assistant-files
Use the **+** button, or drop files or a whole folder anywhere on the panel. It reads spreadsheets, PDFs, Word documents and text; it looks at images; it inspects 3D models for their structure. Two things this makes possible:
- **Build a catalog from a folder.** Drop a folder holding a README or spreadsheet that describes the products, alongside the `models/` and `textures/` it refers to. It reads the description, uploads the assets, and creates everything in dependency order — materials before components before products.
- **Fix an import.** When **Import Catalog** reports problems in its review step, **Ask AI about these issues** opens the assistant with those problems already in front of it.
#### Two things it will not do
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#assistant-limits
- **Publish.** Publishing is what puts a change in front of shoppers, so it is always yours. When its work is ready it stops and hands you a link to the system: **Layouts › Publish**.
- **Place products in a scene.** Where each variant sits is set in the configuration preset editor, by hand. It will get a system and its option sets ready, then point you there.
**If the button is missing**, the assistant is not part of the organization's plan, or is not enabled for this installation. It never shows a locked state — it is either there or it is not.
Do these in order
### Set up a configurator: each step uses the one before it.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#setup
The catalog is a chain: materials and components exist first, variants group them, option sets present the choices, and a configurable system ties it together. Working out of order means going back.
#### Create your organization and add the team
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-01
[Settings › Users](https://admin-configurator.imagine.io/users)
Signing up creates your organization and makes you its owner. Add whoever else needs access with **Add User**: their name, email, role, and a password you choose and pass on to them. To change a role, or to set someone a new password, edit the person. Team size is unlimited on every plan.
- **Owner** — everything, including ownership transfer.
- **Admin** — everything except ownership transfer.
- **Member** — read-only.
[Image: The Users page listing team members, each with an Owner, Admin or Member role]
**Settings › Users.** Everyone with access to your organization, and the role each person holds. **Add User** is top right.
#### Add materials
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-02
[Catalog › Materials](https://admin-configurator.imagine.io/materials)
Every finish a shopper can pick: an oak, a fabric, a worktop stone. A material has a **type**, a **colour**, and the surface properties the 3D scene uses — **metalness**, **roughness**, **tiling** — plus its **texture maps**. Upload a thumbnail; the shopper sees it as the swatch. Materials come first because components and options both point at them.
[Image: The Materials list with a thumbnail, name and type for each material]
**Catalog › Materials.** Each row is one finish with its swatch. Open a material to set its properties and upload texture maps.
**Name them the way you sell them.** The shopper sees these names, and so does anyone writing a rule later. If you already have material definitions as JSON, **Import material JSON** on the form fills the fields for you.
#### Upload components
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-03
[Catalog › Components](https://admin-configurator.imagine.io/components) · [Component Groups](https://admin-configurator.imagine.io/component-groups)
The physical parts, each with its 3D model as a **GLB** file: a cabinet door, a sofa arm, a worktop run. Name the **material slots** on the model so a finish option knows which surface it changes. On the component's own page, add **anchor points** — the spots where other parts attach. Parts that can stand in for each other go in a **component group**, so a rule or an option can swap between them.
[Image: A component open in the dashboard, showing its 3D model and the anchor points where other parts attach]
**Catalog › Components.** One part with its model uploaded; anchor points are added on this page. Interchangeable parts are grouped under **Catalog › Component Groups**.
**A component can contain components.** A composite — a drawer unit made of a carcass, a front and a handle — is built from child components on the parent's page, so the parts move and swap together.
#### Build products and their variants
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-04
[Catalog › Product Graphs](https://admin-configurator.imagine.io/product-graphs) · [Product Variants](https://admin-configurator.imagine.io/product-variants) · [Product Categories](https://admin-configurator.imagine.io/product-categories) · [Tags](https://admin-configurator.imagine.io/tags)
A **product graph** is the catalog item and its structure — a base cabinet, say, with the components it is built from and the option sets that apply to it. A **product variant** is one fully specified version of it: the single door at a particular width, in a particular finish. Variants are what actually get placed in a scene; the base price sits on the product they belong to.
- **Categories** group products for browsing.
- **Tags** are a shared vocabulary you can put on products, components, materials and systems — useful for filtering, and for rules that need to say "any tall unit".
[Image: The Product Variants list, each variant shown under its parent product with its components]
**Catalog › Product Variants.** Variants grouped under their product. This is the level that is placed in a scene.
**Duplicate, then edit.** A product graph can be duplicated with its components and option sets, which is faster than rebuilding a near-identical product.
#### Create option sets and options
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-05
[Catalog › Option Sets](https://admin-configurator.imagine.io/option-sets) · [Options](https://admin-configurator.imagine.io/options)
This is the shopper's interface. An **option set** is a choice group — Fabric, Worktop, Handle; an **option** is one choice within it. What picking an option does depends on the set's **type**:
- **Finish change** — swaps a material on named slots.
- **Load new component** — swaps one part for another.
- **Load new product** — adds a product variant to the scene, an appliance for instance.
- **Product change** — replaces the placed variant with another of the same product.
- **Load configuration** — applies a saved preset.
[Image: An option set open in the dashboard, showing its type and the options inside it]
**Catalog › Option Sets.** One set with its **Type** shown at the top and its options below. The type decides what each option does when picked.
**Prices live in the catalog, not in a price list.** A product carries a **base price**; an option carries a **price delta** — what picking it adds to, or takes off, the total. The quote is the sum of what the shopper chose, so there is no separate list to maintain. Sales channels can override prices per channel — see Sales channels.
#### Add rules and constraints
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-06
[Logic › Rules](https://admin-configurator.imagine.io/rules) · [Constraints](https://admin-configurator.imagine.io/constraints)
Rules react: when this option is chosen, do that. Constraints are limits that always hold, like a maximum run length or a part that cannot sit above a hob. Both are evaluated on the server on every shopper action, so a shared link, an embed and an SDK integration all behave exactly the same.
[Image: The rule editor with a trigger dropdown and an effect dropdown]
**Logic › Rules.** A rule is a trigger and an effect, each chosen from a dropdown. **Custom** on either side takes JSON — see the section below.
**What can a rule or constraint do?** Step 06 in detail lists every trigger, effect and constraint type, the Custom JSON vocabulary, and 17 worked examples with the exact JSON to paste.
#### Assemble a configurable system
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-07
[Scenes › Configurable Systems](https://admin-configurator.imagine.io/configurable-systems) · [Configuration Presets](https://admin-configurator.imagine.io/configuration-presets) · [System Groups](https://admin-configurator.imagine.io/configurable-system-groups)
A system is one configurable product line — a kitchen, a sofa range — tying together the products, option sets and rules a shopper can reach. A system's page has tabs:
- **Details** — name, description and placement type (countertop, built-in, freestanding, wall-mounted or undermount). The **interface toggles** live here too: switch off the **scene toolbar**, the **selection action panel**, or the **panels and assistant** for this system, or leave each on _Inherit_.
- **Layouts** — the **draft** you are editing, the published version live sites load, and the history. This is where **Publish** lives.
- **Option Sets** — which choice groups this system offers, in what order, with what default.
- **Environment** — lighting, HDR backdrop and post-processing for the 3D scene.
- **Catalog** — everything assigned to this system: products, components, materials, rules and constraints, grouped.
- **Sharing Links** — the public links, covered in the next step.
**Shadows and HDR lighting.** Use the **PCF** shadow type for soft shadows. three.js no longer has a separate soft variant, so **PCF Soft** and **PCF Hard** both render as PCF; a higher shadow radius gives softer edges. The same HDR can also look slightly different from one website to another, depending on the three.js version the site was built with. That comes from three.js, not from your settings.
**Presets: the scene a shopper starts from.** A configuration preset is a saved arrangement — which product variants are placed, and where. A system points at one as its default, so every session opens on something finished rather than an empty scene. Three steps:
- **Create it** — [Scenes › Configuration Presets](https://admin-configurator.imagine.io/configuration-presets) › **New**. A name and a description.
- **Place products** — open the preset and, under **Placements**, add each product variant and set where it sits. Add as many as the scene needs.
- **Point the system at it** — open the system › **Layouts** › **Change preset**, pick it, then **Publish**. That publish records a new layout version.
[Image: A configuration preset open on its Placements list, with product variants and their positions]
**Scenes › Configuration Presets.** One preset with its placements. **References** on the same page lists every system version that uses it.
**The preset is not versioned — the system is.** Each time you publish, the new layout version keeps a copy of the placements as they were at that moment, which is what History and Revert restore. Edit a preset afterwards and the change shows in the system's draft; shoppers see it once you publish again.
**System groups** bundle systems so one system's settings can be applied to all of them at once.
[Image: A configurable system open on its Layouts tab, showing the draft and the Publish button]
**Scenes › Configurable Systems › Layouts.** The draft you are editing, and **Publish** to make it live. Shoppers only ever see a published version.
**Systems are versioned, and nothing is live until you publish.** Edit the draft freely; publish when it is right. The button reads **Publish as v1** the first time. A system that has never been published gives the SDK nothing to load — the scene is simply empty, with no error.
#### Publish a public link — no developer needed
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-08
[Scenes › Configurable Systems › Sharing Links](https://admin-configurator.imagine.io/configurable-systems)
Every system can have one or more links. Each is a ready-to-use URL that opens the full configurator on its own page. Share it directly, put it behind a button on your site, or embed it in a page with an iframe. Nothing has to be built for this to work. Each link has:
- **Name** — where this link is used, such as "Storefront" or "Dealer portal". Make one link per place so each can be switched off on its own.
- **Theme** — the look this link opens with. Leave it empty to use the default theme.
- **Allowed domains** — the websites permitted to embed this link in an iframe. Add your site's domain before you embed. Leave it empty while testing.
Links made here open the configurator with no sales channel. For a link that carries a channel's prices and option defaults, create it from the channel instead: **Commerce › Sales Channels › System Config › Sharing Links**.
[Image: The Sharing Links tab of a system, with one link showing its name, theme and allowed domains]
**Scenes › Configurable Systems › Sharing Links.** One link per place you use it. Copy the URL or the embed code from the row; **Regenerate URL** invalidates the old one. Shown to owners and admins.
To embed, paste this where the configurator should appear, with the link's URL in place of `YOUR_LINK` — or use **Copy embed code** on the link, which gives you the same thing filled in. It works on any site builder or CMS that lets you add HTML.
```
```
Step by step for your platform, with the cart hand-off: [Shopify](https://configurator-platform.imagine.io/docs/guides/shopify/index.html), [WordPress](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html), [WooCommerce](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html), [Webflow](https://configurator-platform.imagine.io/docs/guides/webflow/index.html). Any other builder that accepts HTML works the same way.
**Stop here if this is all you need.** The next step is only for a team that wants the configurator inside their own page and code. Turning a link off takes effect immediately and keeps everything else intact.
#### Create an API key and note the system id
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#step-09
[Settings › API Keys](https://admin-configurator.imagine.io/settings/api-keys) · [Scenes › Configurable Systems](https://admin-configurator.imagine.io/configurable-systems)
The key and the system id are the two values a developer needs. Name the key after the site or tool that will use it, choose its permission, and list the websites that may use it:
- **Read & write** — the configurator can save and share projects and upload renders.
- **Read only** — browse, configure and price, never write. The safer choice for a page that never saves.
- **Websites** — at least one is required. Enter `shop.example.com` for a site, `*.example.com` for all its subdomains, and for a developer's machine `localhost` **with its port** — `localhost:5173`, not `localhost`. A key with an empty list works nowhere.
The system id is in the address bar when a system is open — `…/configurable-systems/2` means `2`.
[Image: The API Keys page with a key listed, its value masked except for the last four characters]
**Settings › API Keys.** A key is shown in full once, when created, then masked. Its permission and its website list can be changed at any time; **Revoke** stops it for good.
**Copy the key when it is shown.** It is never shown again. You can change its permission or revoke it here at any time, and every session token made from it stops working within about thirty seconds.
Step 06 in detail · Rules and constraints
### Everything you can pick, and what to write when the dropdowns run out.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#custom-logic
A rule is **when this happens, do that**; a constraint is a limit that always holds. Both are built from dropdowns in the dashboard, and both have a **Custom** choice that takes a few lines of JSON. This section lists every dropdown value first, then the JSON vocabulary, then 17 worked examples you can paste. Every example was run against the Kitchen system and does what its result says. The one-page version, with what the engine returns for each: [how a rule differs from a constraint](https://configurator-platform.imagine.io/docs/concepts/rules-vs-constraints/index.html).
#### 1 Rule triggers THE WHEN DROPDOWN
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#triggers
| Trigger | Plain meaning | You pick | Use it when |
| --- | --- | --- | --- |
| **Product Variant Placed (presence)** | A specific variant is in the scene. Fires when it is added, stays on while it is there, and fires on scene load with it. | One or more variants | Anything that should hold while a product is present: hide options, narrow widths, swap parts, show a message. |
| **Product Variant Selected (focus)** | The shopper clicked that variant in the 3D scene. | One or more variants | Extra options or a message only while the shopper looks at that product. |
| **Component Loaded (presence)** | A component (door, handle, panel…) is on some placement. | One or more components | Reacting to a part rather than a whole product. |
| **Component Selected (focus)** | The shopper clicked a component in 3D. | One or more components | Same as the variant focus trigger, for a part. |
| **Option Selected** | A given option is the current choice of its set, picked or default. | One or more options | Reacting to picker choices: No handle → hide handles. |
| **Scene Loaded** | The configurator has just loaded a scene (start or layout change). | Nothing | One-time setup: a welcome message, exclude hardware from spacing, apply a default. |
| **Custom (JSONLogic)** | Fires when an expression you write is true. | Trigger Params JSON | Anything the others cannot say: more than two tall cabinets, a gold customer. |
**Presence triggers are the workhorse.** Product Variant Placed and Component Loaded hold while the item is in the scene and switch off by themselves when it leaves, so there is no separate "removed" trigger to write.
#### 2 Rule effects THE THEN DROPDOWN
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#effects
| Effect | What the shopper sees | Fill in |
| --- | --- | --- |
| **Hide Option** | The option disappears from its picker. | Option(s) |
| **Disable Option** | The option stays visible but greyed out and not clickable. | Option(s) |
| **Show Option** | Only the listed options remain in their option set while the rule holds; everything else in that set is removed. | Option(s) |
| **Swap Component** | A part on the product is replaced by another part. | The part currently there and the part to install |
| **Swap Via ComponentGroup** | Every part in a group (all handles) is replaced by one chosen part. | Component group and the part to install |
| **Hide Component / Show Component** | A part is hidden on the product, or shown again. | Component(s) |
| **Transform Component** | A part is moved or rotated on the product. | Component, position and rotation |
| **Hide Component Group** | Every part of a group is hidden, the push-to-open, no-handles effect. | Component group(s) |
| **Exclude Components From Bounds** | Nothing visible. The auto-placer ignores these parts when measuring width, so cabinets sit flush. | Components or groups |
| **Load Product** | A new product appears next to the triggering product (a hood above a stove). | Variant to add |
| **Unload Product** | Products of that variant leave the scene, with anything sitting in them. | Variant, or product for all its variants |
| **Load Material** | A surface changes material (a door turns walnut). | Material and slot name(s) |
| **Show Option Sets** | Only the listed option sets are shown at the chosen scope: the piece's panel, or the scene sidebar when scene-wide. | Option set(s) |
| **Show Message** | A toast, banner or popup with your text. | Text, severity, display |
| **Emit Event** | Nothing in the picker; the 3D app receives a named event it can react to. | Event name and optional payload |
| **Custom (JSONLogic)** | Runs a list of actions you write. | Effect Params JSON |
**Under Option Selected** the effect dropdown offers nine of these: Swap Component, Swap Via ComponentGroup, Hide Component Group, Exclude Components From Bounds, Load Material, Show Option Sets, Show Message, Emit Event and Custom. To hide, disable or narrow options, or to load, unload, hide, show or move parts in response to a choice, put the same condition in a Custom trigger instead. Every other trigger offers all seventeen.
**Effect scope** says where: **Placement** (default) is the product that triggered the rule; **Scene-wide** is every product in the scene for the 3D effects, and the scene sidebar for Show Option, Hide Option, Disable Option and Show Option Sets. **Priority** only matters when two rules change the same thing; higher wins. A rule can be limited to one **sales channel**.
#### 3 Constraint types ALWAYS ENFORCED
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#constraint-types
| Type | Plain meaning | Target | Value fields | What the shopper experiences |
| --- | --- | --- | --- | --- |
| **Max Count** | No more than N of this product. | product or variant | `max; optional on_add_action: replace` | Adding one too many is refused, or with replace the oldest is swapped out. |
| **Mutually Exclusive** | These products cannot be in the scene together. | product or variant | `with_products / with_variants; on_add_action: block or replace` | Adding the second is refused, or the first is removed automatically. |
| **Positioned Above** | This product must sit above one of the listed products (hood above stove). | product or variant | `above_products / above_variants; auto_load_default or on_missing_anchor: remove` | Snaps above its anchor; with no anchor the default is added or the product removed. |
| **Requires Together** | If this product is present, its partner must be too. | product or variant | `with_product or with_variant` | The partner is added automatically. |
| **Fixed Position** | Always sits at a fixed height, position or rotation. | product or variant | `position / rotation per axis; enforcement: strict or on_add` | Cannot be dragged off that position (strict), or only starts there (on_add). |
| **Adjacency Required** | Product A must be right next to product B. | product | `a, b` | Moving one makes the other follow. |
| **Min Separation** | At least N products between A and B. | product | `a, b_any_of, min_cabinets_between; optional auto_fill_variant` | Adding A next to B shifts it away, optionally filling the gap. |
| **Custom (JSONLogic)** | Any check you can write as an expression, with a message. | any or none | `when, then` | Refused with your message. |
Constraints are attached to one or more systems and can be limited to a sales channel.
#### 4 Custom JSON: where it goes and how it is shaped WHEN THE DROPDOWNS RUN OUT
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#custom-json
Pick **Custom** as the trigger, the effect or the constraint type and a JSON box appears. Everything in the next four tables can go in that box. The ids in the examples are Kitchen ids; yours are shown next to each product, variant, option set and option in the dashboard lists.
#### Where the JSON goes
**Rule with a custom trigger** → Trigger Type: Custom → `Trigger Params`
```
{"mode": "triggered", "when": [ …conditions… ]}
```
**Rule with a custom effect** → Effect Type: Custom → `Effect Params`
```
{"actions": [ …actions… ]}
```
**Custom constraint** → Constraint Type: Custom → `Value`
```
{"when": [ …conditions… ], "then": [ …actions… ]}
```
You can mix: a Custom trigger with a normal effect, or a normal trigger with a Custom effect. `"mode": "derived"` re-runs the rule for every product on every change.
#### Writing a condition
Compare a path with a value. A list means all must hold; use `or` / `not` for the rest.
```
{"$me.category": "Base Cabinet"} // equals
{"$me.width": {">": 24}} // > < >= <= != in !in
{"$me.selections.8": {"in": [8, 9]}} // option chosen in set 8
{"$me.corner": true}, {"$me.is_middle_of_group": true}
{"or": [{"$me.category": "Appliance"}, {"$me.corner": true}]}
{"not": {"has_placement": {"graph_id": 5}}}
{"count_of": {"graph_id": 4}, ">": 2}
{"sum_of": {"field": "width", "filter": {"placement_group": "floor"}}, ">": 120}
{"$me.left_neighbor.graph_id": 6}
{"$user.tier": "gold"}
```
`$me` is the product being looked at, `$scene` the whole scene, `$context.focus` what the shopper has clicked. `$user` is reserved for shopper facts your website's developer sends; the configurator sends none by itself today. Numbers stay unquoted.
#### Writing an action
```
{"reject": {"message": "…"}} // block with a message
{"warn": {"message": "…"}}
{"emit_info": {"code": "X", "message": "…"}}
{"hide_component": {"on": "$me", "slot": "handle"}}
{"show_component": {"on": "$me", "slot": "handle"}}
{"set_material": {"on": "$me", "slot": "cabinet", "material_id": 18}}
{"set_transform": {"on": "$me", "slot": "leg_right", "position_delta": [0.1, 0, 0]}}
{"set_selection": {"option_set_id": 6, "option_id": 27, "scope": "system"}}
{"emit_event": {"name": "island_added", "payload": {"pid": "$me.id"}}}
{"swap_variant": {"on": "$me", "mapping": {"41": 40}}}
{"load_product": {"variant_id": 8, "placement_group": "wall"}}
{"mark_locked": {}}
```
Constraints may only `reject`, `warn` and `emit_info`. `emit_event` works from triggered rules only. `"on"` names the piece: `"$me"`, a neighbour such as `"$me.right_neighbor"`, or `{"id": "p3"}`.
#### 5 Custom JSON: what you can look at PATHS
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#paths
| Path | Example condition | Means |
| --- | --- | --- |
| `$me.variant_id` | `{"$me.variant_id": 29}` | this piece is variant 29. Variant ids are shown in Catalog > Product Variants. |
| `$me.graph_id` | `{"$me.graph_id": 1}` | this piece belongs to product 1 (any of its variants). Product ids are in Catalog > Product Graphs. |
| `$me.category` | `{"$me.category": "Appliance"}` | its product category, exactly as written on the product. |
| `$me.width` `$me.depth` `$me.height` `$me.weight` | `{"$me.width": {">": 24}}` | the size and weight fields typed on the variant, so this reads "wider than 24". Any variant field works, name included. |
| `$me.corner` `$me.edge` | `{"$me.corner": true}` | the variant's corner flag, and its edge side ("left" or "right") for end pieces. |
| `$me.sequence` | `{"$me.sequence": 0}` | its position in its row counted from the left, so 0 is the leftmost piece. |
| `$me.placement_group` | `{"$me.placement_group": "wall"}` | the row it sits in: "floor", "wall", or whatever your system names its rows. |
| `$me.is_first_in_group` `$me.is_last_in_group` `$me.is_middle_of_group` | `{"$me.is_last_in_group": true}` | true or false: is it at the start, the end, or somewhere inside its row. |
| `$me.left_neighbor.…` `$me.right_neighbor.…` | `{"$me.right_neighbor.category": "Appliance"}` | any of the fields above, read on the piece directly to the left or right. Empty when there is no neighbour, so the condition is simply false. |
| `$me.selections. ` | `{"$me.selections.8": {"in": [8, 9]}}` | the option currently chosen for that option set on this piece. Here: in option set 8 the shopper picked option 8 or 9. Ids are in Catalog > Option Sets. |
| `$me.overrides.visibility. ` `$me.overrides.materials. ` `$me.overrides.transforms. ` | `{"$me.overrides.visibility.handle": false}` | what another rule has already done to this piece: a part hidden (visibility false), a material set, a part moved. Here: "the handle was already hidden". Slot names are the component slot names on the product. |
| `$me.id` | `{"pid": "$me.id"}` | the id of this placement. Only useful inside an emit_event payload so the 3D app knows which piece. |
| `$scene.placements` `$scene.selections` | `{"count": {"list": "$scene.placements", "where": {"$item.category": "Appliance"}}, ">": 2}` | the list of everything placed, and the scene-wide option choices. Used with the list helpers in the next table; $item is the current list entry. |
| `$context.focus.placementId` `$context.focus.variantId` `$context.focus.componentId` | `{"$context.focus.variantId": 29}` | what the shopper has clicked in 3D: the id of the selected placement, its variant id and, when a specific part was clicked, that component id (otherwise empty). The configurator sends this by itself on every action, and nothing when nothing is selected. These three are the only context keys it sends today. |
| `$user. ` | `{"$user.tier": "gold"}` | reserved for facts about the shopper such as tier, region or dealer. The configurator sends none of these today; they exist only when your website's developer passes them in mutation.context.user, and there is no dashboard setting for it. Ask them which keys they send before writing a rule on one. A missing key makes the condition false, so such a rule stays silent. |
#### Operators
| Operator | Means |
| --- | --- |
| `==` | equals; implicit when you write {"path": value} |
| `!=` | not equal |
| `> =
#### Filter keys INSIDE count_of / has_placement / sum_of
| Key | Matches |
| --- | --- |
| `graph_id` | product id |
| `variant_id` | variant id |
| `category` | product category |
| `placement_group` | row |
| `corner` | true / false |
| `edge` | left / right |
| `and / or / not` | combine filters |
#### 6 Custom JSON: counting and testing the scene HELPERS
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#helpers
| Helper | Returns | Means |
| --- | --- | --- |
| `count_of` | int | how many placements match a filter |
| `has_placement` | bool | at least one placement matches a filter |
| `sum_of` | number | total of a product field (width…) over placements matching a filter |
| `has_host_variant_in_graph` | bool | this appliance sits inside a cabinet of the given product |
| `count / any / all / find / filter / map / sum` | various | generic list helpers over a list such as $scene.placements, with a where clause on $item |
#### 7 Custom JSON: what you can do ACTIONS
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#actions
| Action | Allowed in | Does |
| --- | --- | --- |
| `reject` | rules and constraints | blocks the change with your message |
| `warn` | rules and constraints | a non-blocking warning |
| `emit_info` | rules and constraints | an informational note in the response |
| `hide_component / show_component` | rules | hide or show a part by slot name |
| `set_material` | rules | change a surface material by slot name |
| `set_transform` | rules | move (position_delta), rotate (degrees) or scale a part |
| `set_selection` | rules | force an option choice, scene-wide or on the piece |
| `swap_variant` | rules | replace the piece named in on with another variant, via an id map |
| `load_product` | rules | add a product to a row; optional if_no_variant_in to skip when one is already there |
| `mark_locked` | rules | stop the shopper dragging the piece |
| `emit_event` | triggered rules only | send a named event with a payload to the 3D app |
Every action that touches a piece takes `"on"`: `"$me"` (default), a neighbour such as `"$me.right_neighbor"`, or an exact placement `{"id": "p3"}`. Any value starting with `$` is read live. See the worked examples below for each of these in use.
#### 8 Worked examples: custom rules 10 RECIPES, EACH RUN AGAINST THE KITCHEN SYSTEM
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#examples
rule · custom trigger
##### Warn when the kitchen has more than two tall cabinets
Logic › Rules · Trigger Type: Custom · Effect Type: Show Message
**Trigger Params**
```
{"mode": "triggered", "when": [{"count_of": {"graph_id": 4}, ">": 2}]}
```
**Effect** Show Message → "That is a lot of tall storage", severity info.
**Result.** The toast appears on the evaluate where the third tall cabinet lands.
rule · custom trigger
##### No island in the scene → grey out the island width options
Trigger Type: Custom · Effect Type: Disable Option
**Trigger Params**
```
{"mode": "triggered", "when": [{"not": {"has_placement": {"graph_id": 5}}}]}
```
**Effect** Disable Option → options 8 and 9 (6 ft / 8 ft).
**Result.** Both options are marked unavailable until an island is added.
rule · custom trigger
##### Gold customers see a message
Trigger Type: Custom · Effect Type: Show Message
**Trigger Params**
```
{"mode": "triggered", "when": [{"$user.tier": "gold"}]}
```
**Effect** Show Message → "Gold perks unlocked".
**Result.** Fires only when your website's developer sends mutation.context.user = {"tier": "gold"} with the shopper's actions. The configurator does not send any user keys by itself today, so without that developer step the rule stays silent.
rule · custom effect
##### Island placed → set its material, force the handle style, tell the 3D app
Trigger Type: Product Variant Placed → Island Standard 6ft · Effect Type: Custom
**Effect Params**
```
{"actions": [
{"set_material": {"on": "$me", "slot": "cabinet", "material_id": 18}},
{"set_selection": {"option_set_id": 6, "option_id": 27, "scope": "system"}},
{"emit_event": {"name": "island_added", "payload": {"pid": "$me.id"}}},
{"emit_info": {"code": "ISLAND", "message": "Island configured"}}
]}
```
**Result.** The island gets material 18 on its cabinet slot, the Door Handle set switches to option 27 scene-wide, events[] carries island_added, warnings[] carries the ISLAND note. Pick a slot the Cabinet Finish set does not own, or the shopper's finish choice wins on the next evaluate.
rule · derived
##### Hide the side panel of every base cabinet with an appliance to its right
Trigger Type: Custom · Effect Type: Custom
**Trigger Params**
```
{"mode": "derived", "when": [{"$me.graph_id": 1}, {"$me.right_neighbor.category": "Appliance"}]}
```
**Effect Params**
```
{"actions": [{"hide_component": {"on": "$me", "slot": "single_body"}}]}
```
**Result.** On the default preset the base cabinets at positions 2, 8 and 10 get the slot hidden, and it updates by itself whenever cabinets move. Derived rules re-run on every change, never block, and do not appear in fired[].
rule · derived
##### Hide the handle on the first cabinet of the run
Trigger Type: Custom · Effect Type: Custom
**Trigger Params**
```
{"mode": "derived", "when": [{"$me.graph_id": 1}, {"$me.is_first_in_group": true}]}
```
**Effect Params**
```
{"actions": [{"hide_component": {"on": "$me", "slot": "handle"}}]}
```
**Result.** The Single Door 9" at the start of the floor run loses its handle. Move another cabinet to the front and the handle follows the position. "handle" is the component slot name, read it from the variant's Components tab.
rule · custom trigger
##### No sink in the kitchen → grey out the Dishwasher option
Trigger Type: Custom · Effect Type: Disable Option → Dishwasher (option 76)
**Trigger Params**
```
{"mode": "triggered", "when": [{"not": {"has_placement": {"graph_id": 6}}}]}
```
**Result.** Remove the sink and the Dishwasher card in the Appliances picker greys out. Put a sink back and it is selectable again.
rule · custom effect
##### Refrigerator placed → lock it in place and tell the 3D app
Trigger Type: Product Variant Placed → Refrigerator (variant 5) · Effect Type: Custom
**Effect Params**
```
{"actions": [
{"mark_locked": {}},
{"emit_event": {"name": "fridge_placed", "payload": {"pid": "$me.id"}}}
]}
```
**Result.** The new refrigerator placement carries locked: true, so the shopper cannot drag it, and events[] carries fridge_placed with its placement id.
rule · derived
##### A 30" drawer unit next to the sink becomes the 24" one
Trigger Type: Custom · Effect Type: Custom
**Trigger Params**
```
{"mode": "derived", "when": [{"$me.variant_id": 41}, {"$me.right_neighbor.graph_id": 6}]}
```
**Effect Params**
```
{"actions": [{"swap_variant": {"on": "$me", "mapping": {"41": 40}}}]}
```
**Result.** On load, the Double 2 Drawer 30" left of the sink is replaced by the 24" version and stays stable afterwards. swap_variant only changes the piece named in "on"; it does not walk the whole scene.
rule · custom effect
##### A stove with no range hood → add one
Trigger Type: Custom · Effect Type: Custom
**Trigger Params**
```
{"mode": "triggered", "when": [
{"has_placement": {"graph_id": 12}},
{"not": {"has_placement": {"graph_id": 13}}}
]}
```
**Effect Params**
```
{"actions": [{"load_product": {"variant_id": 8, "placement_group": "wall"}}]}
```
**Result.** Delete the range hood while a stove is in the scene and a Range Hood is added back on the wall run in the same evaluate. placement_group is required and must be one of the system's groups.
#### 9 Worked examples: custom constraints 7 RECIPES
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#constraint-examples
constraint
##### Corner cabinets only at the ends of a run
Logic › Constraints · Type: Custom · target: none
**Value**
```
{"when": [{"$me.corner": true}, {"$me.is_middle_of_group": true}],
"then": [{"reject": {"message": "Corner cabinets belong at the end of a run."}}]}
```
**Result.** Dropping a corner base cabinet in the middle of the row is refused with that message (CONSTRAINT_VIOLATION_HARD). The scene stays as it was.
constraint
##### Warn once when the floor run is wider than 10 ft
Type: Custom · target: none
**Value**
```
{"when": [{"$me.placement_group": "floor"}, {"$me.is_first_in_group": true},
{"sum_of": {"field": "width", "filter": {"placement_group": "floor"}}, ">": 120}],
"then": [{"warn": {"message": "This run is wider than 10 ft."}}]}
```
**Result.** An untargeted custom constraint is checked once per product; anchoring on the first piece of the row makes the warning appear once instead of 22 times.
constraint · targeted
##### Dishwasher should sit next to the sink
Type: Custom · target: Dishwasher (product)
**Value**
```
{"when": [{"not": {"or": [{"$me.left_neighbor.graph_id": 6}, {"$me.right_neighbor.graph_id": 6}]}}],
"then": [{"warn": {"message": "The dishwasher should sit next to the sink."}}]}
```
**Result.** Targeting the product means $me is only ever a dishwasher, so no anchor trick is needed. Prefer the typed Adjacency Required constraint when one exists; it also moves the sink along when the dishwasher is dragged.
constraint
##### An island needs a run of at least 8 ft
Type: Custom · target: none
**Value**
```
{"when": [{"$me.graph_id": 5},
{"sum_of": {"field": "width", "filter": {"placement_group": "floor"}}, "<": 96}],
"then": [{"reject": {"message": "An island needs a run of at least 8 ft."}}]}
```
**Result.** With only a couple of base cabinets on the floor, dropping an island is refused; on the default preset (12.75 ft) it is accepted. Widths are in inches, like the product fields.
constraint · targeted
##### Two tall cabinets side by side → warn
Type: Custom · target: Tall Cabinet (product 4)
**Value**
```
{"when": [{"or": [{"$me.left_neighbor.graph_id": 4}, {"$me.right_neighbor.graph_id": 4}]}],
"then": [{"warn": {"message": "Two tall cabinets side by side make a wall."}}]}
```
**Result.** Place two tall cabinets next to each other and the warning appears, once per cabinet in the pair. Because the product is targeted, no other piece is checked.
constraint
##### A corner base cabinet wants a corner wall cabinet above it
Type: Custom · target: none
**Value**
```
{"when": [{"$me.graph_id": 1}, {"$me.corner": true},
{"not": {"has_placement": {"graph_id": 3, "corner": true}}}],
"then": [{"warn": {"message": "Add a corner wall cabinet above the corner base cabinet."}}]}
```
**Result.** The default preset has both corners, so nothing shows; delete the wall corner and the warning appears on the next evaluate. Filters accept corner: true alongside graph_id.
constraint
##### The floor run is longer than 12 ft → warn once
Type: Custom · target: none
**Value**
```
{"when": [{"$me.placement_group": "floor"}, {"$me.is_first_in_group": true},
{"sum_of": {"field": "width", "filter": {"placement_group": "floor"}}, ">": 144}],
"then": [{"warn": {"message": "This kitchen run is longer than 12 ft."}}]}
```
**Result.** Exactly one warning, anchored to the first piece of the run. Use sum_of for totals over product fields such as width; the generic sum primitive cannot read $item.width.
Commerce
### One configurator, sold through many storefronts.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#channels
A sales channel is a storefront, dealer or portal that sells the same catalog on its own terms. Each channel gets its own prices, option defaults, theme and links, without touching the catalog itself. How a link, an embed or the SDK picks the channel: [per-channel pricing](https://configurator-platform.imagine.io/docs/concepts/per-channel-pricing/index.html).
[Image: The Sales Channels list, each channel with its own prices and defaults]
**Commerce › Sales Channels.** One row per storefront or dealer. Upgrade in the sidebar means your plan does not include channels yet.
#### A channel's tabs
[Commerce › Sales Channels › a channel](https://admin-configurator.imagine.io/sales-channels)
- **Details** — name, and the products and option sets this channel sells; a channel only exposes what you attach to it. A dealer channel also gets an **Embed Token**: the key a dealer's own backend uses with the channel API to read this channel's products, option sets and saved projects. **Regenerate** it to cut off a dealer still using the old one.
- **Overrides** — the option defaults this channel opens with. Set channel-wide defaults, then override them for a single product where a dealer wants something different.
- **Product Prices** — a price per product that replaces its base price for this channel only. Clear it to fall back to the catalog price.
- **System Config** — per-system settings for this channel: a starting **preset** and a **theme** that override the system's own for this channel, its own **Sharing Links**, and the same interface toggles as on the system. A link made here carries the channel's prices and defaults; a link made on the system opens with the system's own defaults at catalog prices.
[Image: A sales channel open on its Overrides tab, showing channel-wide option defaults and a per-product override]
**Overrides.** Channel-wide defaults at the top; a product below with its own binding, which wins for that product only.
**Catalog prices are the fallback.** Anything a channel does not override comes from the catalog, so a new option is sold everywhere at its catalog price until a channel says otherwise.
What shoppers create
### Saved projects, quotes and generated images.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#shoppers
Shoppers can save a configuration and share it on every plan. Seeing those saves in the dashboard — with customer details, totals and a PDF — is a paid feature. How the price and the quote are produced: [live pricing and quotes](https://configurator-platform.imagine.io/configurator-with-live-pricing-and-quotes/index.html).
[Image: The Projects list of configurations shoppers have saved, with customer, system, status and total]
Projects
#### Projects and quotes
Every saved configuration, with its **customer**, the **system** it came from, its **status** and its **total**. Open one to see the items, the renders the shopper generated, and to download a quote as a PDF.
[Projects › Projects](https://admin-configurator.imagine.io/projects)
[Image: The AI Images grid with the allowance used this period shown above it]
AI images
#### AI images
Silo and lifestyle images shoppers generated from a configured scene. The card above the grid shows the **allowance used this period**; the plan sets the monthly number. Filter by date, and step through images with the arrow keys.
[Projects › AI Images](https://admin-configurator.imagine.io/ai-images)
**Locked on Free.** Both pages show an Upgrade pill in the sidebar until your plan includes them. Nothing is lost while locked — the projects are saved and the images are kept; upgrading shows them.
Look and feel
### Branding is your organization. A theme is the configurator.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#look
Two pages that are easy to confuse. Branding is set once and describes who you are; themes describe how a configurator looks, and you can have several.
[Image: The Branding page, Identity & Brand section, with company name, logos and favicon]
Branding
#### Branding
Company name and website; logos for light and dark backgrounds plus a square mark; favicon. Then the dashboard's own appearance — heading and body fonts, font size scale, button style, corner radius, content density — and your locale: timezone, date format and currency.
[Settings › Branding](https://admin-configurator.imagine.io/settings/branding)
[Image: A theme open in the dashboard, showing colour, typography and button settings]
Themes
#### Themes
A stock look for the configurator a shopper sees: **colours** (accent, borders, card surfaces), **typography** (body font, base size, weights), **buttons** (radius, control height), **corner radius**, **card width and padding**, and **layout density**. Themes themselves are read-only. Open one and **Customize** to change any of that for your organization: your changes are kept as an override on top of the theme, other organizations still see the original, and later improvements to the theme still reach you for everything you did not touch. Pick a theme on each sharing link, or for a whole channel, per system, under **Commerce › Sales Channels › System Config**.
[Scenes › Themes](https://admin-configurator.imagine.io/themes)
**One catalog, many looks.** A dealer link and your own storefront can point at the same system with different themes — the catalog, prices and rules do not change, only the skin.
**When a theme isn't enough.** Themes change how the configurator looks. Changing what it _is_ — replacing a panel with your own, adding a button, a different layout, your own 3D renderer for a part, a custom quote PDF — is done in code with the SDK, against the same catalog you build here. Nothing in this guide changes; a developer does that part. See the [SDK guide › Customise](../sdk/index.html#customize).
In bulk
### Import a catalog instead of entering it screen by screen.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#import
Bring an existing catalog in from a spreadsheet, with its models and textures alongside. Owners and admins only. To try it first, import one of the [sample catalogs](https://configurator-platform.imagine.io/docs/sample-catalogs/index.html), a sectional sofa or a kitchen.
[Image: The Import Catalog upload step, accepting a spreadsheet, a zip or a whole folder]
**Catalog › Import Catalog.** Drop a folder, a zip, or a spreadsheet. **Get template** gives you the columns to fill.
#### How it runs
- **Get the template.** A spreadsheet with one sheet per thing — materials, components, products, variants, option sets, options — and the columns each needs.
- **Upload.** A CSV or XLSX on its own, or a folder or zip that holds the spreadsheet next to its `models/`, `textures/` and `assets/` folders. If you give it a folder, the paths in the sheet resolve relative to it.
- **Review.** The importer first runs without writing anything and shows what would be **Created**, **Skipped** and in **Error** — a missing model file, a duplicate name, a malformed JSON column. Fix the sheet and upload again, or choose **Skip existing** or **Create anyway** for the rows it flags.
- **Import.** Rows are created in dependency order — materials before components before products — so a later row can reference an earlier one by name.
- **Publish.** The import stops at a draft, exactly as the dashboard does. Open the system it created, then **Layouts › Publish**.
**The sheet cannot express everything.** Behaviour that lives in the placement engine — how modules chain, which options are pre-selected on each placed module — has no column and is set in the dashboard after the import. Preset placements come in as a best guess and usually want nudging.
Plan and billing
### Free to build and evaluate. Upgrade to sell.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#billing
Every organization starts on Free: build, embed and share real configurators while you evaluate, for non-commercial use, with the imagine.io watermark on every configurator. A paid plan licenses commercial use, removes the watermark, and unlocks the pages marked Upgrade.
[Image: The Billing page showing the current plan card, what it includes, and the Change plan and Manage billing buttons]
**Settings › Billing.** Your plan, what it includes, and your renewal date. Owners and admins only.
#### What the page shows
- **Current plan** — the plan, its cadence and renewal date, and the list of what it includes. Usage figures for storage, API requests and bandwidth are listed per plan.
- **Upgrade** — on Free, opens secure checkout. Payment is handled by Stripe; the dashboard never sees your card.
- **Change plan** and **Manage billing** — on a paid plan, open the billing portal to switch cadence, update the card, or download invoices. A scheduled change shows on the card until it takes effect.
- **Payment needs attention** — if a renewal fails, a notice appears with a button to the portal to fix the card. Access continues for a grace period while it retries.
- **Available on request** — a feature your plan can carry that is switched on per account rather than sold. **Contact us to enable** opens the support form with the request filled in.
- **Common questions** — answers to the billing questions we are asked most, kept up to date by the imagine.io team.
**Locked pages stay in the sidebar.** Sales Channels, Projects and AI Images show an Upgrade pill rather than vanishing, and open to a short explanation of what the plan adds. Anything shoppers created while a page was locked is there when you upgrade.
Worth knowing
### Six things that catch people out.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#gotchas
**An empty scene with no error almost always means an unpublished system.** The importer and the editor both stop at a draft, and a draft is invisible to the SDK and to links. Open the system, **Layouts**, **Publish**.
**A configurator shows nothing until the catalog exists.** If a developer takes a key before you have built and published a system, they get an empty scene and assume something is broken. Finish the setup chain first, then hand over the key and the system id.
**An API key must list the website that uses it — with the port, for a developer's machine.** `localhost` alone matches port 80 only; a dev server on 5173 needs `localhost:5173`. A key with no websites works nowhere. The key looks valid in the dashboard either way.
**A read-only key loads fine and fails later.** Everything renders and prices; then save and share do nothing. If that is the symptom, the key is read only.
**Links made on a system carry no sales channel.** If a dealer sees catalog prices instead of theirs, the link was made under Scenes › Configurable Systems. Make it from the channel's **System Config** tab instead.
**Changes to a published system reach every site immediately.** A price, a rule or a new option applies to every configurator running against your organization, with no code change and no release. That is the point of the split — and the reason to edit the draft and publish a new version rather than change what is live.
Next
### Hand it to a developer.
Permalink: https://configurator-platform.imagine.io/admin-guide/index.html#developer
[SDK documentation Install and mount the configurator, replace any part of its interface with your own, drive it from your storefront, and react to the rules you write here.](../sdk/index.html)
[Platform overview What the platform does, how an integration is shaped, and the authentication model, in a few minutes.](../index.html)
[Package on npm @imagineio/configurator-sdk — the SDK itself, with its README, versions and install command.](https://www.npmjs.com/package/@imagineio/configurator-sdk)
---
# Launch post — Introducing the imagine.io Configurator Platform (6 October 2026)
Source: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html
Introducing the platform
## Introducing the imagine.io Configurator Platform: 3D Configuration With Product Logic Built In
3D product configurators with a constraints engine: every change is checked on the server, so only valid configurations are ever built. Share a link, embed it on your website, or customize it with the SDK.
[Gagandeep Singh](https://configurator-platform.imagine.io/authors/gagandeep-singh/index.html), imagine.io · 6 October 2026 · 6 min read
A customer changes a finish, adds a module, or chooses a different component. The product should update in 3D, but so should everything that depends on that choice. Which options are still available? Is the combination allowed? What does it cost?
A configurator needs to answer those questions together.
Today, we’re introducing the **imagine.io Configurator Platform**: a platform for bringing configurable products into 3D, built on a constraints engine. Every change is checked on the server against your constraints, rules and pricing, so only valid configurations are ever built. Business teams can manage their catalog and publish a ready-made experience. Developers can integrate and customize that experience using the SDK. Both work with the same underlying product data and logic.
Three changes in the [engine demo](https://configurator-platform.imagine.io/demo/index.html): legs, fabric, one more piece. Each one is a single call to the engine; its response appears on the right with the changed lines highlighted.
### Bring your product catalog into 3D
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#catalog
The platform is built around products and the choices that make them configurable: components, variants, materials, options and the relationships between them.
That can mean a chair with different finishes, a sectional sofa assembled from modules, or a kitchen with cabinets and appliances. You can manage multiple configurable product lines within one organization, each with its own catalog, constraints, rules and prices.
Bring your 3D assets, define the available choices, and connect them to the product’s behavior. A choice can change a material, replace a component, switch a variant, or load another configuration. Customers explore those choices in an interactive 3D scene with live pricing. If your models are not ready yet, the two [sample catalogs](https://configurator-platform.imagine.io/docs/sample-catalogs/index.html), a sectional sofa and a kitchen, show what a catalog looks like and import in a few minutes.
[Image: A modular sectional sofa in the 3D configurator, with product options beside the scene.]
Configure the product visually while the engine resolves its options and pricing.
### A constraints engine, not just rules
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#rules-and-constraints
Other configurators have a rules engine. Ours is a constraints engine: every change is checked on the server against the limits you set, so only valid configurations are ever built. Rules still shape the result, hide, swap, load, price, but they can never produce something that breaks a constraint.
Rules describe what should happen when a condition is met. Selecting an option might swap a component, apply a material, hide a part, or narrow the choices available elsewhere. Constraints define the limits the configuration must respect, such as maximum quantities, compatibility requirements and placement restrictions. Your team defines both in the dashboard, using built-in controls or custom JSON for more advanced logic.
[Image: The dashboard’s rule editor, shown in two columns: the rule “Hide all handles (No handle)” on the Kitchen system with an empty channel scope; its trigger is Option Selected with the option “None” from the handle option set, and its effect is Hide Component Group on the Handles group, scoped to the placement]
A rule in the dashboard: the systems it applies to, an optional channel scope, a trigger and an effect. This one fires when the shopper picks the “None” handle option and hides every component in the Handles group. Constraints are defined the same way, with a type and a limit instead of a trigger.
Consider a kitchen configuration. A rule for a handleless option can hide the handles on the relevant cabinets. A hard constraint can limit a cabinet run to six units. When a customer tries to add a seventh, the engine rejects the change and provides a reason. The SDK keeps the previous configuration and shows that explanation to the customer.
[Image: The dashboard’s constraint editor, shown in two columns: the constraint “Stove must have at least one cabinet between it and the sink/dishwasher” of type Min Separation on the Kitchen system; its target is the Stove product, separated from the Kitchen Sink and Dishwasher products by at least 1 product]
A constraint in the dashboard: type Min Separation, target the stove, kept at least one product away from the kitchen sink and the dishwasher. There is no trigger: it is re-checked on the whole scene after every change.
Each configuration change goes to the engine. The evaluator applies the matching rules, checks the resulting configuration against the defined constraints, and returns the resolved state: the components and materials to display, the options that remain available, pricing and relevant messages. The SDK uses that response to update the interface and 3D scene.
[Image: The engine demo after changing the upholstery: the sectional in the new fabric, the five steps lit (catalog current, option selected, rules evaluated, 0 violations, 200 OK in 308 ms) and the response JSON with the new grand total and per-piece prices highlighted]
One change, one response. The five steps light up from the engine’s events; the JSON on the right is what it returned, with the lines that changed highlighted, here the price after a fabric change.
**Validation happens as the customer configures, not only at the end.** The constraints engine refuses an invalid change, with the reason, before it reaches the scene.
Because this logic runs on the server, a shared configurator, an embedded experience and a custom SDK interface use the same engine to evaluate the same product choices. For a closer look at the response, read the [evaluation guide](https://configurator-platform.imagine.io/sdk/index.html#evaluation). The concept pages explain [when to use a rule and when a constraint](https://configurator-platform.imagine.io/docs/concepts/rules-vs-constraints/index.html), [why the evaluation runs on the server](https://configurator-platform.imagine.io/docs/concepts/server-side-constraint-and-rule-evaluation/index.html), and [what a rejected change looks like](https://configurator-platform.imagine.io/docs/errors/422-rejected-by-constraint/index.html).
### Start without code. Customize with code.
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#integration
There are three ways to put a configurator in front of customers, all using the same catalog.
#### Publish a shareable link
For non-developers, the dashboard is the starting point. [Set up products, materials, options, rules, constraints and prices](https://configurator-platform.imagine.io/admin-guide/index.html), then publish a link to the configurator. Share it with a customer, add it to a sales conversation, or place it behind a button on your website. You do not need to build a custom frontend to start using the experience.
#### Embed it on your website
A ready-made configurator can also run inside your website through an iframe. Add the embed to a page that supports HTML and configure the allowed domain in the dashboard. The embedded experience uses the same catalog and product logic as the shared link, with no SDK installation required on the host page. See the [embed guide](https://configurator-platform.imagine.io/sdk/index.html#embed), or the step-by-step guides for [Shopify](https://configurator-platform.imagine.io/docs/guides/shopify/index.html), [WordPress](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html), [WooCommerce](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html), [Webflow](https://configurator-platform.imagine.io/docs/guides/webflow/index.html) and [React](https://configurator-platform.imagine.io/docs/guides/react/index.html).
#### Build with the SDK
For developers, the React SDK provides a working configurator that can be restyled, extended, or integrated into a custom application. Use theme tokens and CSS for branding. Replace individual interface components, add buttons and panels, or create a different layout. For a fully custom interface, hooks expose options, availability, pricing and actions.
Once your catalog and application are configured using the [SDK quickstart](https://configurator-platform.imagine.io/sdk/quickstart/index.html), mounting the experience looks like this:
```
import { mount } from '@imagineio/configurator-sdk';
const app = mount('#root', {
systemId: 12, // Replace with your configurable system's ID.
getToken: async () => {
const response = await fetch('/configurator-token', {
method: 'POST',
});
if (!response.ok) {
throw new Error('Unable to start a configurator session.');
}
return response.json();
},
});
```
Your backend implements the token endpoint, exchanging your API key for a short-lived session token. The API key stays on your server; the browser receives the session token, and the SDK handles refreshing it.
Starting with a shared link does not lock you into that approach. You can move to an embed or an SDK integration without rebuilding the underlying catalog.
### One catalog, multiple sales channels
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#channels
Your website, dealer network and sales portal may sell the same products differently. [Sales channels](https://configurator-platform.imagine.io/admin-guide/index.html#channels) let you manage those differences without duplicating the catalog. A sales channel is one storefront’s view of the same catalog: your own site, a dealer, or a marketplace listing such as Wayfair.
Each channel can expose its assigned products and option sets, apply its own product prices and option defaults, and use a different starting preset, theme and sharing link. Settings that are not overridden fall back to the catalog or system settings.
For example, your direct storefront can open with one starting configuration, while a dealer’s experience opens with another and uses dealer-specific pricing. Both still draw from the same underlying product catalog. [Per-channel pricing](https://configurator-platform.imagine.io/docs/concepts/per-channel-pricing/index.html) explains which price wins when a channel overrides a product or an option.
Manage the product centrally. Adapt how it is sold by channel.
[Image: The Direct storefront sales channel’s Overrides tab in the dashboard: every option set listed with a channel name field and an Enabled toggle; the Back Cushion set is expanded, showing each option’s base price delta, channel name and override delta]
A channel’s overrides screen. Every option set is on by default and a fresh channel has zero overrides. Rename a set for this storefront, switch one off, or set a channel price. Only the differences are stored.
### Connect the configuration to pricing, quotes and commerce
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#commerce
The configuration should remain useful after the customer finishes exploring it. Live pricing is calculated by the engine, with an itemized breakdown that reflects the configured products and options. That pricing also supports the quote, rather than requiring a separate calculation in the frontend.
The platform supports saved and shared configurations and branded quote PDFs. Developers can access structured configuration and bill-of-materials data, including product identifiers, quantities, selections and engine-calculated prices, to connect the experience to their own systems.
For an embedded configurator, the [commerce bridge](https://configurator-platform.imagine.io/sdk/index.html#commerce) lets your website read the quote, capture a product image, and retrieve the configuration snapshot for a cart or order workflow. Your integration connects those outputs to your storefront’s checkout, so the configuration can travel with the purchase. Saved projects and quotes require a plan that includes them. [Live pricing and quotes](https://configurator-platform.imagine.io/configurator-with-live-pricing-and-quotes/index.html) walks through the whole path, and the [WooCommerce guide](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html) shows the configuration carried onto a cart line.
### Take the configured product beyond the browser
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#imagery-and-ar
The platform also supports AR and generated imagery from the configured scene. Customers can open an AR link or scan a QR code to view the configured product at full size in their space. They can also generate product silo and lifestyle images from the current configuration, with generated assets available alongside projects and quotes.
These capabilities extend the same configuration into different ways of viewing and sharing it. Availability and generation allowances depend on the plan.
### AI in the dashboard and in the configurator
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#ai
The platform is built to be worked through an assistant, not only through forms. The dashboard has an [Admin Assistant](https://configurator-platform.imagine.io/admin-guide/index.html#assistant) that knows your catalog: ask it to create materials, products, option sets, rules and constraints from a description or a spreadsheet, to fix the problems an import reports, or to explain a setting and link to the page. Everything it creates goes through the same validation as the dashboard, so an assistant cannot produce a catalog the engine would refuse.
Inside the configurator, shoppers get an assistant of their own. They ask in plain words, “show me the three-seat layout in black”, and it answers or makes the change, with the constraints engine checking the result like any other click. Generated product imagery of the exact configuration rounds it off: silo and lifestyle images on demand, metered per plan.
### Build and evaluate for free
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#start
You can start building and evaluating a configurator on the free plan. It includes unlimited configurators, products, variants and materials, along with the dashboard, constraints, rules and pricing engine, and API access.
Free use is for non-commercial evaluation and includes the imagine.io watermark. A paid plan licenses commercial use, removes the watermark, and unlocks additional capabilities such as sales channels and saved projects with quotes. Current plan details and usage allowances are available in the [dashboard](https://admin-configurator.imagine.io/).
No 3D models yet? imagine.io's 3D production team builds configurator-ready models from your photos, drawings or CAD files, and can set up the catalog with you; [book a walkthrough](https://configurator-platform.imagine.io/#book-a-walkthrough) to scope it.
Start with one product line. Define its options, add its rules and constraints, and test how each choice affects the configuration. Then choose the experience that fits your team: a shared link, an embed, or a custom SDK integration. [What the free plan includes](https://configurator-platform.imagine.io/free-3d-product-configurator/index.html) lists exactly what you get and where the paid plan begins.
### Frequently asked questions
Permalink: https://configurator-platform.imagine.io/blog/introducing-imagine-io-configurator-platform/index.html#faq
**How long does it take to go live?**
A developer gets a running configurator in about fifteen minutes with the [SDK quickstart](https://configurator-platform.imagine.io/sdk/quickstart/index.html). With your own products, the time goes into preparing the 3D models, the options and the rules; publishing a link or embedding it takes an afternoon once the catalog is in.
**Do I need a developer?**
Not to start. The dashboard builds the catalog, the constraints, the rules and the prices, and a sharing link or an iframe embed goes onto a page without code. A developer is needed for the SDK route, or to wire the configuration into your cart with the [commerce bridge](https://configurator-platform.imagine.io/sdk/index.html#commerce).
**Which platforms does it work with?**
Any site that lets you add a block of HTML. There are step-by-step guides for [Shopify](https://configurator-platform.imagine.io/docs/guides/shopify/index.html), [WordPress](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html), [WooCommerce](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html), [Webflow](https://configurator-platform.imagine.io/docs/guides/webflow/index.html) and [React](https://configurator-platform.imagine.io/docs/guides/react/index.html).
**Can I try it without my own 3D models?**
Yes. Two [sample catalogs](https://configurator-platform.imagine.io/docs/sample-catalogs/index.html), a sectional sofa and a kitchen, import from the dashboard in a few minutes, so you can see the configurator working before you prepare your own models.
**Is there AI in it?**
Yes, in two places. The dashboard's [Admin Assistant](https://configurator-platform.imagine.io/admin-guide/index.html#assistant) creates materials, products, option sets, rules and constraints from a description or a file, fixes import problems and explains settings. Inside the configurator, shoppers ask for changes in plain words and the assistant makes them, with every result checked by the constraints engine. Generated product images of the exact configuration are metered per plan.
**What does it cost to start?**
Nothing. The free plan is for non-commercial evaluation and carries the imagine.io watermark, with unlimited configurators, products, variants and materials. Commercial use, your own domain and the watermark removed are part of a paid plan; the details are in the [dashboard](https://admin-configurator.imagine.io/).
Published 2026-10-06. [← All posts](https://configurator-platform.imagine.io/blog/index.html)
---
# SDK quickstart — install, token route, mount()
Source: https://configurator-platform.imagine.io/sdk/quickstart/index.html
Get running
## SDK quickstart: a running 3D configurator in fifteen minutes
Get a catalog in and publish it, create a key, install the package, add a token route, call mount() once. Nine steps, on a page of their own.
[Gagandeep Singh](https://configurator-platform.imagine.io/authors/gagandeep-singh/index.html), imagine.io · 26 October 2026
Install `@imagineio/configurator-sdk`, add a small server route that exchanges your API key for a session token, and call `mount()` once with the system id. From an empty Vite app to a live configurator with live pricing in about fifteen minutes. Rules, constraints and pricing run on the server; the browser only renders.
**You need** a catalog with a published layout (import a [sample catalog](https://configurator-platform.imagine.io/docs/sample-catalogs/index.html), a sofa or a kitchen, or upload your own) and two values: your organisation's API key and the system id of the configurator (a system is one configurable product line). All of it comes from the [imagine.io dashboard](https://admin-configurator.imagine.io/); steps 4 to 6 show where.
### Nine steps
Permalink: https://configurator-platform.imagine.io/sdk/quickstart/index.html#steps
-
#### Create a Vite React app
Skip this if you are adding the SDK to an existing Vite app. Vite is the supported path: the SDK ships ES modules and a Vite plugin that serves its static files and keeps react and three deduped.
```
npm create vite@latest my-configurator -- --template react
cd my-configurator
```
-
#### Install the SDK
Version 0.1.6 and later support React 18 and React 19. The 3D packages (three, fiber, drei) are installed for you, at the versions that match your React.
**React 19**, which a fresh Vite template ships: install the package on its own. npm adds three.js 0.186, @react-three/fiber 9 and @react-three/drei 10. Keep React at 19.3 or earlier; @react-three/fiber 9 does not accept 19.4 yet.
```
npm install @imagineio/configurator-sdk
```
**React 18**: name the React 18 versions in the same command, so npm installs three.js 0.159, @react-three/fiber 8 and @react-three/drei 9. A fresh Vite template ships React 19 types, so install the React 18 ones too.
```
npm install @imagineio/configurator-sdk react@^18.2 react-dom@^18.2 three@~0.159.0 @react-three/fiber@^8.15 @react-three/drei@^9.88 @react-three/postprocessing@^2.16 postprocessing@~6.36.0
npm install -D @types/react@^18.2 @types/react-dom@^18.2
```
One visible difference: three.js 0.186 lights the same HDR environment slightly differently from 0.159, so a scene can look a little different on React 19 than on React 18. That comes from three.js; no setting changes it.
-
#### Add the Vite plugin
One plugin, two jobs. It serves the SDK's static files in development and copies them into your build: mainly the Draco decoder, which the browser needs to unpack the compressed 3D models, so without it models fail silently. And it keeps react and three deduped, so a second copy pulled in by another dependency cannot blank the canvas.
```
// vite.config.js
import imagineConfigurator from '@imagineio/configurator-sdk/vite';
export default defineConfig({
plugins: [react(), imagineConfigurator()],
});
```
-
#### Get a catalog in: import a sample or upload your own
The configurator shows nothing until the organisation has a catalog. Sign in to the [imagine.io dashboard](https://admin-configurator.imagine.io/), or sign up first if your organisation has no account yet, then get a catalog in, either way:
- **Import a sample catalog.** A sectional sofa or a kitchen, with models, textures, rules and prices, ready in a few minutes: download, extract, drop the folder on [Catalog › Import Catalog](https://admin-configurator.imagine.io/catalog-import). The [sample catalogs page](https://configurator-platform.imagine.io/docs/sample-catalogs/index.html) has the links and the five steps. The fastest way to see the SDK running.
- **Upload your own.** Products and variants, materials, components, option sets and options, then a configurable system that ties them together. The [admin guide](https://configurator-platform.imagine.io/admin-guide/index.html#setup) walks through each in order, or the same importer takes your own spreadsheet and assets.
[Image: The imagine.io dashboard sign-in screen]
Sign in, or create the account, at the dashboard.
-
#### Publish the layout
Both routes end in a **draft**. Open the system under [Scenes › Configurable Systems](https://admin-configurator.imagine.io/configurable-systems), then **Layouts › Publish**. Until you do, the configurator mounts into an empty scene with no error, because nothing failed.
While the system is open, note its **system id**: the number at the end of the address bar, also listed next to each system. The mount step needs it.
[Image: The Layouts tab of a configurable system, with the Publish button]
Layouts › Publish. The system id is the number at the end of the address bar.
-
#### Get your API key
Go to [Settings › API Keys](https://admin-configurator.imagine.io/settings/api-keys) and press **Create key**. Name it after the site that will use it, choose **Read & write** or **Read only**, and list the **websites** that may use it: `shop.example.com` for a site, `*.example.com` for its subdomains, and for your machine `localhost` with its port, `localhost:5173`. A key with an empty list works nowhere. One key serves every system in the organisation.
[Image: The API Keys page: one key listed with its masked value, a permission selector and a Revoke action]
Settings › API Keys. Copy the key when it is shown; its permission and websites can be changed later.
-
#### Add the key and mount
Put the key in an env file, not in your source. Create `.env.local` next to `package.json`; Vite loads it and git ignores it.
```
VITE_API_KEY=YOUR_ORG_API_KEY
```
The SDK reads `VITE_API_KEY` on its own. Replace `src/main.jsx` with this; the SDK brings its own styles.
```
import { mount, config } from '@imagineio/configurator-sdk';
// Optional: a sales channel, for per-channel prices, hidden options and a theme
config.setChannelId('dealer-42');
// Boot the system, load catalog and scene, render the full default UI
const app = mount('#root', { systemId: 1 });
// later: app.unmount();
```
-
#### Production: a session token instead of the key
The API key is long-lived and reads your whole catalog, so it must never reach a browser. In production your server asks imagine.io for a **session token**, which lasts 30 minutes and is safe for the browser to hold, and the SDK uses that instead. One route on your server:
```
// server.js
app.post('/configurator-token', async (req, res) => {
const r = await fetch('https://api-configurator.imagine.io/api/v1/auth/token/', {
method: 'POST',
headers: { 'X-Api-Key': process.env.CONFIGURATOR_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ scope: 'session', system_id: 12, origin: 'https://www.your-site.com' }),
});
res.status(r.status).json(await r.json());
});
```
The three body fields are optional and each narrows what the token can do: `scope` is `session` (can save projects and upload renders) or `catalog` (load, configure and price only); `system_id` locks it to one system; `origin` locks it to your site. Then hand `mount()` the route. No `VITE_API_KEY` exists in this build.
```
const app = mount('#root', {
systemId: 12,
getToken: async () => (await fetch('/configurator-token', { method: 'POST' })).json(),
});
```
The SDK sends the token as `Authorization: Bearer` on every request, calls your route again shortly before the token expires and once more on a `401`. If the key ever leaks, revoke it in the dashboard: every token made from it stops working within about 30 seconds. More in [how session tokens work](https://configurator-platform.imagine.io/docs/concepts/session-tokens/index.html).
-
#### Run
```
npm run dev
```
What you should see: a brief loader, then the customisation options on the left and the 3D scene on the right. A different `systemId` is a different configurator, a sofa, a kitchen, a wardrobe, with no frontend change. An empty scene with no error means the layout was never published: step 5. Blank page or missing models? The [troubleshooting section](https://configurator-platform.imagine.io/sdk/index.html#troubleshooting) covers every known cause.
### What next
Permalink: https://configurator-platform.imagine.io/sdk/quickstart/index.html#next
You have a running configurator. The three things most teams do next each have a walkthrough in the SDK docs:
### Frequently asked questions
Permalink: https://configurator-platform.imagine.io/sdk/quickstart/index.html#faq
**Do I have to use Vite?**
For the quickstart, yes: it is the documented and tested path, and the SDK's Vite plugin does two things for you, serving the static files (mainly the Draco decoder) and keeping react and three deduped. The package itself is compiled ES modules, so another bundler can load it if you do those two things by hand; the React guide's FAQ lists them.
**Why does npm install fail with ERESOLVE?**
Two causes. A React 18 app that installed the package on its own: npm picked the React 19 versions, so name the React 18 ones in the same command: npm install @imagineio/configurator-sdk react@^18.2 react-dom@^18.2 three@~0.159.0 @react-three/fiber@^8.15 @react-three/drei@^9.88 @react-three/postprocessing@^2.16 postprocessing@~6.36.0. A React 19 app that already has three.js 0.187 or newer, which the SDK does not accept yet: run npm install @imagineio/configurator-sdk three@~0.186.0. Do not use --legacy-peer-deps; it only hides the conflict.
**Which React versions does the SDK support?**
React 18 and React 19, in version 0.1.6 and later. One package covers both; your React version decides which 3D packages npm adds: three.js 0.186, @react-three/fiber 9 and @react-three/drei 10 on React 19; three.js 0.159, @react-three/fiber 8 and @react-three/drei 9 on React 18. On React 19, keep React at 19.3 or earlier; @react-three/fiber 9 does not accept 19.4 yet.
**How do I move an app from React 18 to React 19?**
Remove the React 18 3D packages and reinstall from scratch; installing React 19 over them stops with ERESOLVE, because package-lock.json still holds @react-three/fiber 8. Run npm uninstall three @react-three/fiber @react-three/drei @react-three/postprocessing postprocessing, delete node_modules and package-lock.json, then run npm install react@^19.3.1 react-dom@^19.3.1 and npm install -D @types/react@^19.3.0 @types/react-dom@^19.3.0. npm then adds the React 19 versions for the SDK.
**Can I ship VITE_API_KEY to production?**
No. The API key is long-lived and reads the whole catalog. In production a route on your server exchanges it for a 30-minute session token, and mount() gets that route as getToken. The browser only ever holds the token.
**Where does the system id come from?**
Scenes › Configurable Systems in the dashboard. Each configurator built for your organisation is listed with its id; it is also the number at the end of the address bar when a system is open.
**Why is the scene empty after I mount?**
Almost always because the layout was not published. A catalog, imported or built by hand, stops at a draft; open the system under Scenes › Configurable Systems and press Publish on the Layouts tab. The other cause is a systemId that names a different system.
---
# Guides — add a 3D configurator to Shopify, WordPress, Webflow or React
Source: https://configurator-platform.imagine.io/docs/guides/index.html
Guides
## Add a 3D product configurator to your platform
One page per platform: the answer, the code, the steps, and the cart hand-off.
Five short guides, one per platform. Each starts with the two-sentence answer and the code, then the steps, the cart hand-off and the problems that come up most. Four of them embed a sharing link with one iframe; the React guide mounts the SDK. A page built with the SDK can itself be embedded, which is the third route, explained below.
[Shopify One iframe in a Custom Liquid section; the quote posted to /cart/add.js. Guide](https://configurator-platform.imagine.io/docs/guides/shopify/index.html) [WordPress A Custom HTML block on any page; the quote to a form or your backend. Guide](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html) [WooCommerce The product page; the configuration carried onto the cart line in PHP. Guide](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html) [Webflow An Embed element, a CMS field per item; the quote handed to a form or your checkout. Guide](https://configurator-platform.imagine.io/docs/guides/webflow/index.html) [React The SDK: install, token route, mount(); the quote read with quote.read(). Guide](https://configurator-platform.imagine.io/docs/guides/react/index.html)
### Three routes, one engine
Permalink: https://configurator-platform.imagine.io/docs/guides/index.html#routes
Every route runs the same configurator against the same catalog, rules and prices. They differ only in who owns the interface and where the code runs.
-
#### Embed a sharing link
One iframe with a link made in the dashboard. Keep the configurator's own customisation options, or [hide them](https://configurator-platform.imagine.io/sdk/index.html#em-params) and drive everything from your own buttons on the page through the [postMessage bridge](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol): select options, change the layout, read the quote, [hear every event](https://configurator-platform.imagine.io/sdk/index.html#eb-events). The 3D view and the engine stay inside the frame; the interface around it can be entirely yours. No install, no API key on the page. For any site whose pages are templates: a Shopify theme, WordPress, WooCommerce, Webflow, Squarespace, Wix, or a plain HTML page. Guides: [Shopify](https://configurator-platform.imagine.io/docs/guides/shopify/index.html), [WordPress](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html), [WooCommerce](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html), [Webflow](https://configurator-platform.imagine.io/docs/guides/webflow/index.html).
-
#### Mount the SDK
The React package in your own app: the configurator itself runs in your page, no iframe, and you can [restyle](https://configurator-platform.imagine.io/sdk/index.html#howto-theme-layout) or [replace](https://configurator-platform.imagine.io/sdk/index.html#cz-override) any part of its interface, [add your own 3D](https://configurator-platform.imagine.io/sdk/index.html#howto-3d), and [read every event](https://configurator-platform.imagine.io/sdk/index.html#events) in code. For a React app or a React storefront such as Shopify Hydrogen or a Next.js shop. There is nothing to mount into on a Liquid theme, a WordPress theme or Webflow. Guide: [React](https://configurator-platform.imagine.io/docs/guides/react/index.html); the full reference: [SDK documentation](https://configurator-platform.imagine.io/sdk/index.html).
-
#### Build with the SDK, then embed your page
Make your own configurator page with the SDK, host it, and put that page in an iframe on Shopify or anywhere else. The bridge activates on any page that mounts the SDK inside an iframe, so the store side is identical to route 1: the same ready handshake, the same `getQuote`, the same `price.changed`. This is the route for “we want to change the configurator itself, not only the buttons around it, and we are on Shopify”. Read the [React guide](https://configurator-platform.imagine.io/docs/guides/react/index.html) for the page and the [Shopify guide](https://configurator-platform.imagine.io/docs/guides/shopify/index.html) for the store; lock the bridge to your store’s origin as the [bridge chapter](https://configurator-platform.imagine.io/sdk/index.html#eb-scope) shows.
### Related
Permalink: https://configurator-platform.imagine.io/docs/guides/index.html#related
[SDK quickstart From an empty Vite app to a running configurator in about fifteen minutes.](https://configurator-platform.imagine.io/sdk/quickstart/index.html) [Embed a public link (SDK docs) The iframe, the URL parameters and every postMessage command.](https://configurator-platform.imagine.io/sdk/index.html#embed) [Admin guide: publish a public link Where the link, its theme and its allowed domains are set.](https://configurator-platform.imagine.io/admin-guide/index.html#publish-link)
---
# Guide — add a 3D configurator to Shopify
Source: https://configurator-platform.imagine.io/docs/guides/shopify/index.html
Guide
## How to add a 3D product configurator to Shopify
[Gagandeep Singh](https://configurator-platform.imagine.io/authors/gagandeep-singh/index.html), imagine.io · 26 October 2026
Paste one iframe tag into a Shopify page or product template, and add your store domain to the link's allowed domains in the [imagine.io dashboard](https://admin-configurator.imagine.io/). The configurator loads inside the page with its own customisation options and live price, or with the [panel hidden](https://configurator-platform.imagine.io/sdk/index.html#em-params) and [your own buttons driving it](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol). No app and no theme code needed; the cart hand-off is a short script that posts the engine's quote to Shopify's cart.
Where the embed goes: the link is made in the dashboard, pasted into the Shopify editor, and the configurator renders inside the page.
**This guide uses the embed route.** One iframe, a sharing link, and the bridge for the cart. Your own buttons are already covered: hide the configurator's panel and drive it from the page through the [bridge](https://configurator-platform.imagine.io/sdk/index.html#commerce) (step 5 below). Want to change the configurator itself, the parts inside the frame? Build it with the [SDK](https://configurator-platform.imagine.io/docs/guides/react/index.html), host that page, and embed _it_ with the same iframe: the bridge activates on any page that mounts the SDK inside an iframe, so everything below about the cart works unchanged. All three routes: [which route fits which site](https://configurator-platform.imagine.io/docs/guides/index.html#routes).
### The embed code
Permalink: https://configurator-platform.imagine.io/docs/guides/shopify/index.html#embed
One element. The configurator boots, loads its catalog and renders itself, with its customisation options and live price. Replace `lk_YOUR_LINK` with your sharing link.
```
```
### Step by step
Permalink: https://configurator-platform.imagine.io/docs/guides/shopify/index.html#steps
-
#### Create the sharing link and allow your domain
In the [imagine.io dashboard](https://admin-configurator.imagine.io/) open [Scenes › Configurable Systems](https://admin-configurator.imagine.io/configurable-systems), pick the system, and on its [Sharing Links](https://admin-configurator.imagine.io/configurable-systems) tab create a link. Give it a name for where it will live, choose a theme or leave the default, and under **Allowed domains** add every domain the page will be served from. Leave the list empty while you test locally, and fill it in before you go live: a link embedded on a domain that is not listed shows a “not authorized” card instead of the configurator.
**Copy embed code** on the row gives you the iframe below with the link filled in.
[Image: The Sharing Links tab of a system, with one link showing its name, theme and allowed domains]
Scenes › Configurable Systems › Sharing Links. One link per place you use it; the allowed domains are set here.
-
#### Open the theme editor
In Shopify admin go to **Online Store › Themes** and press **Customize** on the live theme. Open the template where the configurator should live: the product template for one product, or a page template for a dedicated “Design your sofa” page.
-
#### Add a Custom Liquid section and paste the iframe
Press **Add section** (or **Add block** inside the product information section) and choose **Custom Liquid**. Paste the iframe from above with your link in `src`. Save. The configurator appears in the preview straight away if your preview domain is in the allowed list. Shopify's own themes include the Custom Liquid section; a third-party theme may name it differently or put custom HTML elsewhere, in which case the theme's documentation says where. Shopify's guide to the editor: [Customizing themes](https://help.shopify.com/en/manual/online-store/themes/customizing-themes).
-
#### Size it for the page
The iframe takes the width of its section. Give it a height that fits your layout, `640px` on desktop is a good start, and for a full-page experience use `height: 80vh`. On phones the configurator lays itself out for the narrow width.
-
#### Decide who owns the customisation options
Keep the configurator's panel, or hide it with `?hide=sidebar` on the link and drive the scene from your own swatches through the postMessage bridge. The 3D view stays.
```
https://configurator.imagine.io/lk_YOUR_LINK?hide=sidebar
```
With the panel hidden, your page sends the choices in. Wait for the frame to say it is ready, read the option sets to build your own swatches from, then select by name or by id. The ten-line `callConfigurator` helper is the one from the cart section below.
```
const iframe = document.getElementById('configurator');
window.addEventListener('message', (e) => {
if (e.data?.type === 'configurator:ready') start(); // the frame is listening
});
async function start() {
// Every option set and option, to build your own swatches from
const sets = await callConfigurator(iframe, 'getOptionSets');
// Your swatch -> the configurator. By name, or by id when your CMS stores ids
await callConfigurator(iframe, 'selectOption', { optionSet: 'Fabric', option: 'Cognac' });
await callConfigurator(iframe, 'selectOption', { optionSetId: 41, optionId: 118 });
// Hide or show parts of the configurator's interface after boot
await callConfigurator(iframe, 'hideUI', { regions: ['sidebar'] });
}
```
What you can pass and what comes back: [the URL parameters](https://configurator-platform.imagine.io/sdk/index.html#em-params) (`hide`, `gui`, `theme`, `project`, `config`), [the full protocol](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol), every command with its payload and its real reply (select options, read the quote and the state, camera, interface regions, undo and redo), [the events the frame sends out](https://configurator-platform.imagine.io/sdk/index.html#eb-events), and [the helper](https://configurator-platform.imagine.io/sdk/index.html#eb-helper). One thing to know: a command the frame accepts can still be refused by a rule a moment later, which arrives as an `evaluate.rejected` event, so roll a cart line back on that event, not on the command's reply.
-
#### Add the domains you forgot
Shopify serves your store on `your-store.myshopify.com` and on your custom domain. Add both to the link's allowed domains, plus any preview domain you test on. The check reads the referrer, so keep the iframe's `referrerpolicy` at `strict-origin-when-cross-origin` or looser.
-
#### Test on the real store
Open the product page on the live domain, change a few options and watch the price. Then wire the cart below.
### Hand the configuration to your cart
Permalink: https://configurator-platform.imagine.io/docs/guides/shopify/index.html#cart
Three calls turn what the shopper built into a cart line: the itemised quote, a picture of it, and a snapshot that can reopen the exact build later. Add a button next to the iframe, write the ten-line helper once, then post the quote to Shopify's cart on the shop's own domain, which keeps per-line properties.
```
```
```
// Ten lines you write once: posts a command into the iframe and resolves with its reply.
function callConfigurator(iframe, action, payload) {
return new Promise((resolve, reject) => {
const requestId = 'req-' + Math.random().toString(36).slice(2);
const onReply = (e) => {
const m = e.data;
if (m?.type !== 'configurator:response' || m.requestId !== requestId) return;
window.removeEventListener('message', onReply);
m.success ? resolve(m.data) : reject(new Error(m.error));
};
window.addEventListener('message', onReply);
iframe.contentWindow.postMessage({ action, payload, requestId }, '*');
});
}
```
```
const iframe = document.getElementById('configurator');
const add = document.getElementById('add-to-cart');
window.addEventListener('message', (e) => {
const m = e.data;
if (m?.type === 'configurator:ready') add.disabled = false;
// The price follows every change the shopper makes. No polling.
if (m?.type === 'configurator:event' && m.event === 'price.changed') {
add.textContent = `Add to cart: ${m.data.currency} ${m.data.grandTotal}`;
}
});
add.onclick = async () => {
const quote = await callConfigurator(iframe, 'getQuote'); // itemised, priced by the engine
const { dataUrl } = await callConfigurator(iframe, 'getScreenshot'); // thumbnail for the cart
const snapshot = await callConfigurator(iframe, 'getConfiguration'); // reopen the exact build later
await fetch('/cart/add.js', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
items: [{
id: SHOPIFY_VARIANT_ID, // the Shopify variant that carries the configured product
quantity: 1,
properties: { // what the merchant needs to fulfil the order
Configuration: quote.system.name,
Price: `${quote.currency} ${quote.totals.grandTotal}`,
Lines: quote.lines.map((l) => l.name).join(', '),
_snapshot: JSON.stringify(snapshot),
_image: dataUrl,
},
}],
}),
});
};
```
The mapping from a configurator line to a Shopify variant is yours: the engine prices the configuration, Shopify charges the variant. Most stores use one “configured product” variant per product line and carry the engine's price and lines as properties, or create a draft order from the quote on the server. Properties do not survive a cart permalink, so use `/cart/add.js` or the Storefront API when you need them. The [e-commerce walkthrough](https://configurator-platform.imagine.io/sdk/index.html#howto-ecom) in the SDK docs shows the same hand-off with the SDK mounted on the store page.
### Frequently asked questions
Permalink: https://configurator-platform.imagine.io/docs/guides/shopify/index.html#faq
**Do I need a Shopify app?**
No. A sharing link is embedded with one iframe in a Custom Liquid section, and the cart hand-off is a short script on the page. Nothing is installed in your store and no theme code is edited.
**Will the configurator slow down my product page?**
The iframe loads lazily and the 3D runs inside it, isolated from your theme's scripts. Your page's own weight does not change; the configurator's assets load only when the frame is on screen.
**My site has a Content-Security-Policy. What does it need?**
Allow the configurator origin in frame-src, for example frame-src https://configurator.imagine.io. The configurator host permits framing by the domains in the link's allowed domains, so add your site there too.
**Can I use my own swatches instead of the configurator's customisation options on Shopify?**
Yes. Add ?hide=sidebar to the link so the panel disappears, then call selectOption from your page through the postMessage bridge. getOptionSets returns every option set and option to build your buttons from. The SDK docs cover each command.
### Troubleshooting
Permalink: https://configurator-platform.imagine.io/docs/guides/shopify/index.html#troubleshooting
**The page shows a “not authorized” card instead of the configurator.**
The page's domain is not in the link's Allowed domains. Add it in Scenes › Configurable Systems › Sharing Links, including any preview or staging domain you test on. The check reads the referrer, so the iframe must not set referrerpolicy to no-referrer.
**The configurator is blank, or the events arrive but every command times out.**
Two usual causes. The page is opened from the file system rather than a web server: a file:// page has no origin the browser will deliver replies to. Or the iframe has a sandbox attribute that strips allow-scripts or allow-same-origin. Remove the sandbox attribute and serve the page over http.
**Fullscreen or the Copy button does not work inside the embed.**
The iframe needs allow="xr-spatial-tracking; fullscreen; clipboard-write". Without fullscreen the browser blocks the fullscreen toggle. Without clipboard-write in the iframe’s allow attribute, the browser blocks copying inside the configurator.
**A licence notice appears on the real site but not in testing.**
The free plan is for non-commercial evaluation with the imagine.io watermark. Running on your own domain and storefront is part of a paid plan; the plans are in the dashboard under Settings › Billing.
### Other platforms
Permalink: https://configurator-platform.imagine.io/docs/guides/shopify/index.html#platforms
### Related
Permalink: https://configurator-platform.imagine.io/docs/guides/shopify/index.html#related
[Embed a public link (SDK docs) The iframe, the URL parameters and every postMessage command, with the real replies.](https://configurator-platform.imagine.io/sdk/index.html#embed) [The e-commerce bridge The eleven things a product page wires, from the ready handshake to the order record.](https://configurator-platform.imagine.io/sdk/index.html#commerce) [Admin guide: publish a public link Where the link, its theme and its allowed domains are set.](https://configurator-platform.imagine.io/admin-guide/index.html#publish-link)
---
# Guide — add a 3D configurator to WordPress
Source: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html
Guide
## How to add a 3D product configurator to WordPress
[Gagandeep Singh](https://configurator-platform.imagine.io/authors/gagandeep-singh/index.html), imagine.io · 26 October 2026
Paste one iframe tag into a Custom HTML block on any WordPress page, and add your site's domain to the link's allowed domains in the [imagine.io dashboard](https://admin-configurator.imagine.io/). This guide covers a page on any WordPress site; for a WooCommerce product page and its cart, read the [WooCommerce guide](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html). The configurator loads with its own customisation options and live price, or with the [panel hidden](https://configurator-platform.imagine.io/sdk/index.html#em-params) and [your own buttons driving it](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol). No plugin needed.
Where the embed goes: the link is made in the dashboard, pasted into the WordPress editor, and the configurator renders inside the page.
**This guide uses the embed route.** One iframe, a sharing link, and the bridge for the cart. Your own buttons are already covered: hide the configurator's panel and drive it from the page through the [bridge](https://configurator-platform.imagine.io/sdk/index.html#commerce) (step 5 below). Want to change the configurator itself, the parts inside the frame? Build it with the [SDK](https://configurator-platform.imagine.io/docs/guides/react/index.html), host that page, and embed _it_ with the same iframe: the bridge activates on any page that mounts the SDK inside an iframe, so everything below about the cart works unchanged. All three routes: [which route fits which site](https://configurator-platform.imagine.io/docs/guides/index.html#routes).
### The embed code
Permalink: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html#embed
One element. The configurator boots, loads its catalog and renders itself, with its customisation options and live price. Replace `lk_YOUR_LINK` with your sharing link.
```
```
### Step by step
Permalink: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html#steps
-
#### Create the sharing link and allow your domain
In the [imagine.io dashboard](https://admin-configurator.imagine.io/) open [Scenes › Configurable Systems](https://admin-configurator.imagine.io/configurable-systems), pick the system, and on its [Sharing Links](https://admin-configurator.imagine.io/configurable-systems) tab create a link. Give it a name for where it will live, choose a theme or leave the default, and under **Allowed domains** add every domain the page will be served from. Leave the list empty while you test locally, and fill it in before you go live: a link embedded on a domain that is not listed shows a “not authorized” card instead of the configurator.
**Copy embed code** on the row gives you the iframe below with the link filled in.
[Image: The Sharing Links tab of a system, with one link showing its name, theme and allowed domains]
Scenes › Configurable Systems › Sharing Links. One link per place you use it; the allowed domains are set here.
-
#### Add a Custom HTML block
Edit the page in the block editor, press **+**, and choose **Custom HTML**. Paste the iframe from above with your link in `src`. Page builders work the same way: an **HTML** widget in Elementor, a **Code** module in Divi, a **Raw HTML** block in Bricks.
-
#### Keep the HTML intact
Some security plugins and user roles strip iframes on save. If the tag disappears, save the page as an Administrator, or allow the `iframe` tag for the role that edits pages. Caching and optimisation plugins that lazy-load iframes are fine; the configurator already loads lazily.
-
#### Size it for the page
The iframe takes the width of its container. Give it a height that fits your layout, `640px` is a good start, or `80vh` for a full-page experience. On phones the configurator lays itself out for the narrow width.
-
#### Decide who owns the customisation options
Keep the configurator's panel, or hide it with `?hide=sidebar` on the link and drive the scene from your own swatches through the postMessage bridge. The 3D view stays.
```
https://configurator.imagine.io/lk_YOUR_LINK?hide=sidebar
```
With the panel hidden, your page sends the choices in. Wait for the frame to say it is ready, read the option sets to build your own swatches from, then select by name or by id. The ten-line `callConfigurator` helper is the one from the cart section below.
```
const iframe = document.getElementById('configurator');
window.addEventListener('message', (e) => {
if (e.data?.type === 'configurator:ready') start(); // the frame is listening
});
async function start() {
// Every option set and option, to build your own swatches from
const sets = await callConfigurator(iframe, 'getOptionSets');
// Your swatch -> the configurator. By name, or by id when your CMS stores ids
await callConfigurator(iframe, 'selectOption', { optionSet: 'Fabric', option: 'Cognac' });
await callConfigurator(iframe, 'selectOption', { optionSetId: 41, optionId: 118 });
// Hide or show parts of the configurator's interface after boot
await callConfigurator(iframe, 'hideUI', { regions: ['sidebar'] });
}
```
What you can pass and what comes back: [the URL parameters](https://configurator-platform.imagine.io/sdk/index.html#em-params) (`hide`, `gui`, `theme`, `project`, `config`), [the full protocol](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol), every command with its payload and its real reply (select options, read the quote and the state, camera, interface regions, undo and redo), [the events the frame sends out](https://configurator-platform.imagine.io/sdk/index.html#eb-events), and [the helper](https://configurator-platform.imagine.io/sdk/index.html#eb-helper). One thing to know: a command the frame accepts can still be refused by a rule a moment later, which arrives as an `evaluate.rejected` event, so roll a cart line back on that event, not on the command's reply.
-
#### Add every domain you serve from
Add the live domain and any staging domain to the link's allowed domains. The check reads the referrer, so keep the iframe's `referrerpolicy` at `strict-origin-when-cross-origin` or looser.
### Hand the configuration to your cart
Permalink: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html#cart
The bridge gives your page the itemised quote, a thumbnail and a snapshot of the build. On a WordPress site without a store, hand them to a form (a quote request with the snapshot in a hidden field), a CRM, or your own backend. On a WooCommerce store, the cart line is covered in the [WooCommerce guide](https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html).
```
```
```
// Ten lines you write once: posts a command into the iframe and resolves with its reply.
function callConfigurator(iframe, action, payload) {
return new Promise((resolve, reject) => {
const requestId = 'req-' + Math.random().toString(36).slice(2);
const onReply = (e) => {
const m = e.data;
if (m?.type !== 'configurator:response' || m.requestId !== requestId) return;
window.removeEventListener('message', onReply);
m.success ? resolve(m.data) : reject(new Error(m.error));
};
window.addEventListener('message', onReply);
iframe.contentWindow.postMessage({ action, payload, requestId }, '*');
});
}
```
```
const iframe = document.getElementById('configurator');
const add = document.getElementById('add-to-cart');
window.addEventListener('message', (e) => {
const m = e.data;
if (m?.type === 'configurator:ready') add.disabled = false;
// The price follows every change the shopper makes. No polling.
if (m?.type === 'configurator:event' && m.event === 'price.changed') {
add.textContent = `Add to cart: ${m.data.currency} ${m.data.grandTotal}`;
}
});
add.onclick = async () => {
const quote = await callConfigurator(iframe, 'getQuote'); // itemised, priced by the engine
const { dataUrl } = await callConfigurator(iframe, 'getScreenshot'); // thumbnail for the cart
const snapshot = await callConfigurator(iframe, 'getConfiguration'); // reopen the exact build later
// Hand it to a form plugin's hidden fields, or post it to your own endpoint
const form = document.getElementById('quote-form');
form.elements.configuration.value = JSON.stringify({ quote, snapshot });
form.elements.total.value = `${quote.currency} ${quote.totals.grandTotal}`;
form.requestSubmit();
};
```
The quote's `lines` carry every placed product with its chosen options already resolved to names, and `totals.grandTotal` is the engine's price. The [bridge chapter](https://configurator-platform.imagine.io/sdk/index.html#commerce) documents every field.
### Frequently asked questions
Permalink: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html#faq
**Do I need a plugin?**
No. The embed is a Custom HTML block; nothing is installed. A WooCommerce store needs a few lines of PHP to carry the configuration onto the cart line, shown in the WooCommerce guide.
**My site has a Content-Security-Policy. What does it need?**
Allow the configurator origin in frame-src, for example frame-src https://configurator.imagine.io. The configurator host permits framing by the domains in the link's allowed domains, so add your site there too.
**Can I use my own swatches instead of the configurator's customisation options on WordPress?**
Yes. Add ?hide=sidebar to the link so the panel disappears, then call selectOption from your page through the postMessage bridge. getOptionSets returns every option set and option to build your buttons from. The SDK docs cover each command.
### Troubleshooting
Permalink: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html#troubleshooting
**The iframe disappears when I save the page.**
WordPress strips iframes for roles without the unfiltered_html capability: for a Contributor, the block's content is sanitised and the iframe and script tags are removed on save. Some security plugins do the same for everyone. Save as an Administrator or Editor, or allow the iframe tag for the editing role. WordPress's own page on the block: [Custom HTML](https://wordpress.org/documentation/article/custom-html/).
**The page shows a “not authorized” card instead of the configurator.**
The page's domain is not in the link's Allowed domains. Add it in Scenes › Configurable Systems › Sharing Links, including any preview or staging domain you test on. The check reads the referrer, so the iframe must not set referrerpolicy to no-referrer.
**The configurator is blank, or the events arrive but every command times out.**
Two usual causes. The page is opened from the file system rather than a web server: a file:// page has no origin the browser will deliver replies to. Or the iframe has a sandbox attribute that strips allow-scripts or allow-same-origin. Remove the sandbox attribute and serve the page over http.
**Fullscreen or the Copy button does not work inside the embed.**
The iframe needs allow="xr-spatial-tracking; fullscreen; clipboard-write". Without fullscreen the browser blocks the fullscreen toggle. Without clipboard-write in the iframe’s allow attribute, the browser blocks copying inside the configurator.
**A licence notice appears on the real site but not in testing.**
The free plan is for non-commercial evaluation with the imagine.io watermark. Running on your own domain and storefront is part of a paid plan; the plans are in the dashboard under Settings › Billing.
### Other platforms
Permalink: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html#platforms
### Related
Permalink: https://configurator-platform.imagine.io/docs/guides/wordpress/index.html#related
[Embed a public link (SDK docs) The iframe, the URL parameters and every postMessage command, with the real replies.](https://configurator-platform.imagine.io/sdk/index.html#embed) [The e-commerce bridge The eleven things a product page wires, from the ready handshake to the order record.](https://configurator-platform.imagine.io/sdk/index.html#commerce) [Admin guide: publish a public link Where the link, its theme and its allowed domains are set.](https://configurator-platform.imagine.io/admin-guide/index.html#publish-link)
---
# Guide — add a 3D configurator to WooCommerce
Source: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html
Guide
## How to add a 3D product configurator to WooCommerce
[Gagandeep Singh](https://configurator-platform.imagine.io/authors/gagandeep-singh/index.html), imagine.io · 26 October 2026
Paste one iframe tag into the product's description, or print it from a theme hook, and add your store's domain to the link's allowed domains in the [imagine.io dashboard](https://admin-configurator.imagine.io/). The configurator loads on the product page with its own customisation options and live price, or with the [panel hidden](https://configurator-platform.imagine.io/sdk/index.html#em-params) and [your own buttons driving it](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol). No plugin; the cart line takes a few lines of PHP in the child theme, shown below. For a page that is not a product, see the [WordPress guide](https://configurator-platform.imagine.io/docs/guides/wordpress/index.html).
Where the embed goes: the link is made in the dashboard, pasted into the WooCommerce editor, and the configurator renders inside the page.
**This guide uses the embed route.** One iframe, a sharing link, and the bridge for the cart. Your own buttons are already covered: hide the configurator's panel and drive it from the page through the [bridge](https://configurator-platform.imagine.io/sdk/index.html#commerce) (step 5 below). Want to change the configurator itself, the parts inside the frame? Build it with the [SDK](https://configurator-platform.imagine.io/docs/guides/react/index.html), host that page, and embed _it_ with the same iframe: the bridge activates on any page that mounts the SDK inside an iframe, so everything below about the cart works unchanged. All three routes: [which route fits which site](https://configurator-platform.imagine.io/docs/guides/index.html#routes).
### The embed code
Permalink: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html#embed
One element. The configurator boots, loads its catalog and renders itself, with its customisation options and live price. Replace `lk_YOUR_LINK` with your sharing link.
```
```
### Step by step
Permalink: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html#steps
-
#### Create the sharing link and allow your domain
In the [imagine.io dashboard](https://admin-configurator.imagine.io/) open [Scenes › Configurable Systems](https://admin-configurator.imagine.io/configurable-systems), pick the system, and on its [Sharing Links](https://admin-configurator.imagine.io/configurable-systems) tab create a link. Give it a name for where it will live, choose a theme or leave the default, and under **Allowed domains** add every domain the page will be served from. Leave the list empty while you test locally, and fill it in before you go live: a link embedded on a domain that is not listed shows a “not authorized” card instead of the configurator.
**Copy embed code** on the row gives you the iframe below with the link filled in.
[Image: The Sharing Links tab of a system, with one link showing its name, theme and allowed domains]
Scenes › Configurable Systems › Sharing Links. One link per place you use it; the allowed domains are set here.
-
#### Paste it into the product page
Open the product under **Products**, switch the description editor to the **Text** (or **Code**) tab, and paste the iframe where the configurator should appear. Update the product.
For every product of a line, a developer can instead print the iframe from a hook such as `woocommerce_after_single_product_summary` in the child theme, with each product's sharing link stored in a custom field, so no product description carries code.
-
#### Keep the HTML intact
Some security plugins and user roles strip iframes on save. If the tag disappears, save the product as an Administrator or Shop manager, or allow the `iframe` tag for the role that edits products. Caching and optimisation plugins that lazy-load iframes are fine; the configurator already loads lazily.
-
#### Size it for the page
The iframe takes the width of its container. Give it a height that fits the product layout, `640px` is a good start, or `80vh` for a full-page experience. On phones the configurator lays itself out for the narrow width.
-
#### Decide who owns the customisation options
Keep the configurator's panel, or hide it with `?hide=sidebar` on the link and drive the scene from your own swatches through the postMessage bridge. The 3D view stays.
```
https://configurator.imagine.io/lk_YOUR_LINK?hide=sidebar
```
With the panel hidden, your page sends the choices in. Wait for the frame to say it is ready, read the option sets to build your own swatches from, then select by name or by id. The ten-line `callConfigurator` helper is the one from the cart section below.
```
const iframe = document.getElementById('configurator');
window.addEventListener('message', (e) => {
if (e.data?.type === 'configurator:ready') start(); // the frame is listening
});
async function start() {
// Every option set and option, to build your own swatches from
const sets = await callConfigurator(iframe, 'getOptionSets');
// Your swatch -> the configurator. By name, or by id when your CMS stores ids
await callConfigurator(iframe, 'selectOption', { optionSet: 'Fabric', option: 'Cognac' });
await callConfigurator(iframe, 'selectOption', { optionSetId: 41, optionId: 118 });
// Hide or show parts of the configurator's interface after boot
await callConfigurator(iframe, 'hideUI', { regions: ['sidebar'] });
}
```
What you can pass and what comes back: [the URL parameters](https://configurator-platform.imagine.io/sdk/index.html#em-params) (`hide`, `gui`, `theme`, `project`, `config`), [the full protocol](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol), every command with its payload and its real reply (select options, read the quote and the state, camera, interface regions, undo and redo), [the events the frame sends out](https://configurator-platform.imagine.io/sdk/index.html#eb-events), and [the helper](https://configurator-platform.imagine.io/sdk/index.html#eb-helper). One thing to know: a command the frame accepts can still be refused by a rule a moment later, which arrives as an `evaluate.rejected` event, so roll a cart line back on that event, not on the command's reply.
-
#### Add every domain you serve from
Add the live domain and any staging domain to the link's allowed domains. The check reads the referrer, so keep the iframe's `referrerpolicy` at `strict-origin-when-cross-origin` or looser.
-
#### Test on the store
Open the product on the live domain, change a few options and watch the price. Then wire the cart below.
### Hand the configuration to your cart
Permalink: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html#cart
The bridge gives the page the itemised quote, a thumbnail and a snapshot of the build. To get them onto the WooCommerce cart line: the JavaScript below posts them to a small endpoint, and a few lines of PHP in the child theme store them as cart item data so they travel onto the order.
```
```
```
// Ten lines you write once: posts a command into the iframe and resolves with its reply.
function callConfigurator(iframe, action, payload) {
return new Promise((resolve, reject) => {
const requestId = 'req-' + Math.random().toString(36).slice(2);
const onReply = (e) => {
const m = e.data;
if (m?.type !== 'configurator:response' || m.requestId !== requestId) return;
window.removeEventListener('message', onReply);
m.success ? resolve(m.data) : reject(new Error(m.error));
};
window.addEventListener('message', onReply);
iframe.contentWindow.postMessage({ action, payload, requestId }, '*');
});
}
```
```
const iframe = document.getElementById('configurator');
const add = document.getElementById('add-to-cart');
window.addEventListener('message', (e) => {
const m = e.data;
if (m?.type === 'configurator:ready') add.disabled = false;
// The price follows every change the shopper makes. No polling.
if (m?.type === 'configurator:event' && m.event === 'price.changed') {
add.textContent = `Add to cart: ${m.data.currency} ${m.data.grandTotal}`;
}
});
add.onclick = async () => {
const quote = await callConfigurator(iframe, 'getQuote'); // itemised, priced by the engine
const { dataUrl } = await callConfigurator(iframe, 'getScreenshot'); // thumbnail for the cart
const snapshot = await callConfigurator(iframe, 'getConfiguration'); // reopen the exact build later
await fetch('/wp-json/mystore/v1/configured-cart', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': wpApiSettings.nonce },
body: JSON.stringify({ product_id: WOO_PRODUCT_ID, quote, image: dataUrl, snapshot }),
});
};
```
```
// functions.php (child theme): accept the post and add a cart line with the configuration attached
add_action('rest_api_init', function () {
register_rest_route('mystore/v1', '/configured-cart', [
'methods' => 'POST', 'permission_callback' => '__return_true',
'callback' => function (WP_REST_Request $r) {
$data = ['imagine_quote' => $r['quote'], 'imagine_snapshot' => $r['snapshot'], 'imagine_image' => $r['image']];
$key = WC()->cart->add_to_cart((int) $r['product_id'], 1, 0, [], $data);
return ['cart_item_key' => $key];
},
]);
});
// Show the configuration on the cart and the order, and carry it onto the order line
add_filter('woocommerce_get_item_data', function ($item_data, $cart_item) {
if (!empty($cart_item['imagine_quote'])) {
$item_data[] = ['name' => 'Configuration', 'value' => $cart_item['imagine_quote']['system']['name']];
}
return $item_data;
}, 10, 2);
add_action('woocommerce_checkout_create_order_line_item', function ($item, $key, $values) {
if (!empty($values['imagine_snapshot'])) $item->add_meta_data('_imagine_snapshot', wp_json_encode($values['imagine_snapshot']));
}, 10, 3);
```
The price the engine returns is in `quote.totals.grandTotal`. WooCommerce charges the product's own price unless you set it from the quote in a `woocommerce_before_calculate_totals` hook, which is the usual next step for configured products. The [bridge chapter](https://configurator-platform.imagine.io/sdk/index.html#commerce) documents every field of the quote.
### Frequently asked questions
Permalink: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html#faq
**Do I need a plugin?**
No. The embed is one iframe in the product description or a theme hook, and the cart hand-off is a few lines of PHP in the child theme, shown above. Nothing is installed from a marketplace.
**Can WooCommerce charge the engine's price?**
Yes, with one more hook. WooCommerce charges the product's own price by default; set the cart item's price from quote.totals.grandTotal in a woocommerce_before_calculate_totals hook and the cart, the checkout and the order carry the engine's number.
**My site has a Content-Security-Policy. What does it need?**
Allow the configurator origin in frame-src, for example frame-src https://configurator.imagine.io. The configurator host permits framing by the domains in the link's allowed domains, so add your site there too.
**Can I use my own swatches instead of the configurator's customisation options on WooCommerce?**
Yes. Add ?hide=sidebar to the link so the panel disappears, then call selectOption from your page through the postMessage bridge. getOptionSets returns every option set and option to build your buttons from. The SDK docs cover each command.
### Troubleshooting
Permalink: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html#troubleshooting
**The iframe disappears when I save the product.**
WooCommerce runs on WordPress, which strips iframes for roles without the unfiltered_html capability: the content is sanitised on save and the iframe and script tags are removed. Some security plugins do the same for everyone. Save as an Administrator, or allow the iframe tag for the role that edits products. Which roles have it: WordPress's [Roles and Capabilities](https://wordpress.org/documentation/article/roles-and-capabilities/) page.
**The page shows a “not authorized” card instead of the configurator.**
The page's domain is not in the link's Allowed domains. Add it in Scenes › Configurable Systems › Sharing Links, including any preview or staging domain you test on. The check reads the referrer, so the iframe must not set referrerpolicy to no-referrer.
**The configurator is blank, or the events arrive but every command times out.**
Two usual causes. The page is opened from the file system rather than a web server: a file:// page has no origin the browser will deliver replies to. Or the iframe has a sandbox attribute that strips allow-scripts or allow-same-origin. Remove the sandbox attribute and serve the page over http.
**Fullscreen or the Copy button does not work inside the embed.**
The iframe needs allow="xr-spatial-tracking; fullscreen; clipboard-write". Without fullscreen the browser blocks the fullscreen toggle. Without clipboard-write in the iframe’s allow attribute, the browser blocks copying inside the configurator.
**A licence notice appears on the real site but not in testing.**
The free plan is for non-commercial evaluation with the imagine.io watermark. Running on your own domain and storefront is part of a paid plan; the plans are in the dashboard under Settings › Billing.
### Other platforms
Permalink: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html#platforms
### Related
Permalink: https://configurator-platform.imagine.io/docs/guides/woocommerce/index.html#related
[Embed a public link (SDK docs) The iframe, the URL parameters and every postMessage command, with the real replies.](https://configurator-platform.imagine.io/sdk/index.html#embed) [The e-commerce bridge The eleven things a product page wires, from the ready handshake to the order record.](https://configurator-platform.imagine.io/sdk/index.html#commerce) [Admin guide: publish a public link Where the link, its theme and its allowed domains are set.](https://configurator-platform.imagine.io/admin-guide/index.html#publish-link)
---
# Guide — add a 3D configurator to Webflow
Source: https://configurator-platform.imagine.io/docs/guides/webflow/index.html
Guide
## How to add a 3D product configurator to Webflow
[Gagandeep Singh](https://configurator-platform.imagine.io/authors/gagandeep-singh/index.html), imagine.io · 26 October 2026
Drop an Embed element onto the Webflow page and paste one iframe tag into it, then add your site's domain to the link's allowed domains in the [imagine.io dashboard](https://admin-configurator.imagine.io/). The configurator loads with its own customisation options and live price, or with the [panel hidden](https://configurator-platform.imagine.io/sdk/index.html#em-params) and [your own buttons driving it](https://configurator-platform.imagine.io/sdk/index.html#eb-protocol). No code export, no custom attributes.
Where the embed goes: the link is made in the dashboard, pasted into the Webflow editor, and the configurator renders inside the page.
**This guide uses the embed route.** One iframe, a sharing link, and the bridge for the cart. Your own buttons are already covered: hide the configurator's panel and drive it from the page through the [bridge](https://configurator-platform.imagine.io/sdk/index.html#commerce) (step 5 below). Want to change the configurator itself, the parts inside the frame? Build it with the [SDK](https://configurator-platform.imagine.io/docs/guides/react/index.html), host that page, and embed _it_ with the same iframe: the bridge activates on any page that mounts the SDK inside an iframe, so everything below about the cart works unchanged. All three routes: [which route fits which site](https://configurator-platform.imagine.io/docs/guides/index.html#routes).
### The embed code
Permalink: https://configurator-platform.imagine.io/docs/guides/webflow/index.html#embed
One element. The configurator boots, loads its catalog and renders itself, with its customisation options and live price. Replace `lk_YOUR_LINK` with your sharing link.
```
```
### Step by step
Permalink: https://configurator-platform.imagine.io/docs/guides/webflow/index.html#steps
-
#### Create the sharing link and allow your domain
In the [imagine.io dashboard](https://admin-configurator.imagine.io/) open [Scenes › Configurable Systems](https://admin-configurator.imagine.io/configurable-systems), pick the system, and on its [Sharing Links](https://admin-configurator.imagine.io/configurable-systems) tab create a link. Give it a name for where it will live, choose a theme or leave the default, and under **Allowed domains** add every domain the page will be served from. Leave the list empty while you test locally, and fill it in before you go live: a link embedded on a domain that is not listed shows a “not authorized” card instead of the configurator.
**Copy embed code** on the row gives you the iframe below with the link filled in.
[Image: The Sharing Links tab of a system, with one link showing its name, theme and allowed domains]
Scenes › Configurable Systems › Sharing Links. One link per place you use it; the allowed domains are set here.
-
#### Add an Embed element
In the Designer open the **Add** panel, find **Embed** under Advanced (or type “embed” in the search), and drag it to where the configurator should sit. Paste the iframe from above with your link in `src` and save.
-
#### Let it fill its parent
The Embed element sizes itself to the iframe. Give the iframe `width:100%` (already in the snippet) and set the height on the iframe or on the parent div, `640px` for a section, `80vh` for a full-page experience. Put the Embed inside a Container or Section so it follows your page's width on every breakpoint.
-
#### One per CMS item
For a configurator per product on a CMS Collection page, add a plain-text field such as `configurator-link` to the collection, put the Embed on the template page, and use the Embed's **Add field** button to insert that field into the `src`. One template, one iframe, a link per item.
-
#### Decide who owns the customisation options
Keep the configurator's panel, or hide it with `?hide=sidebar` on the link and drive the scene from your own buttons through the postMessage bridge, in the page's **Before