🚀 UI Package Integration Guide

The injectConfigurator function injects the OV25 configurator UI into existing DOM elements on your page. It finds elements by CSS selectors and either replaces or appends the configurator components.

📦 Installation

Install the package using npm:

npm i ov25-ui@latest

💡 Note: Always use @latest to ensure you have the most recent version with all the latest features and bug fixes.

📦 Usage

import { injectConfigurator, type InjectConfiguratorInput } from 'ov25-ui';
 
// Single configurator
injectConfigurator(config);
 
// Multiple configurators on the same page
injectConfigurator([config1, config2, config3]);

✅ Required Fields

Field	Type	Description
`apiKey`	`StringOrFunction`	OV25 API key
`productLink`	`StringOrFunction`	Product ID or path (e.g. `'217'`, `'snap2/4'` for multi-product modular, `'range/126'`)
`selectors`	`SelectorsConfig`	DOM targets for gallery, price, name, variants, swatches, configureButton
`callbacks`	`CallbacksConfig`	`addToBasket`, `buyNow`, `buySwatches` (required); `onChange` (optional)

type StringOrFunction = string | (() => string);
 
interface SelectorsConfig {
  gallery?: ElementSelector;
  price?: ElementSelector;
  name?: ElementSelector;
  variants?: ElementSelector;
  swatches?: ElementSelector;
  configureButton?: ElementSelector;
}

Full Config Type

interface InjectConfiguratorOptions {
  apiKey: StringOrFunction;
  productLink: StringOrFunction;
  configurationUuid?: StringOrFunction;
  images?: string[];
  uniqueId?: string;
  selectors: SelectorsConfig;
  carousel?: CarouselConfig;
  configurator?: ConfiguratorConfig;
  callbacks: CallbacksConfig;
  branding?: BrandingConfig;
  flags?: FlagsConfig;
}
 
type InjectConfiguratorInput = InjectConfiguratorOptions | LegacyInjectConfiguratorOptions;

Minimal Example

const config: InjectConfiguratorInput = {
  apiKey: () => '15-5f9c5d4197f8b45ee615ac2476e8354a160f384f01c72cd7f2638f41e164c21d',
  productLink: () => '217',
  selectors: {
    gallery: { selector: '.configurator-container', replace: true },
    price: { selector: '#price', replace: true },
    name: { selector: '#name', replace: true },
  },
  callbacks: {
    addToBasket: () => {},
    buyNow: () => {},
    buySwatches: () => {},
  },
};
injectConfigurator(config);

🎯 Selectors

Each selector can be a string (CSS selector) or an object:

type ElementConfig = {
  selector?: string;
  id?: string;  // deprecated, use selector
  replace?: boolean;
};
 
type ElementSelector = string | ElementConfig;

Selector	Purpose	Required	Notes
`gallery`	Main 3D/image container	Standard products	For multi-product modular configs, gallery chrome may live inside the configurator modal
`price`	Price display	When not hiding pricing	Omit when `flags.hidePricing: true`
`name`	Product name	Recommended
`variants`	Variant controls	Products with variants	Omit for products without variants
`swatches`	Swatch selector	Products with swatches	Omit when no swatches
`configureButton`	Button that opens configurator	Multi-product modular	Required for multi-product modular flows; optional for standard single-product

Replace vs Append

replace: true – Replaces the target element's content with the configurator UI
replace: false or omitted – Appends the UI inside the target element

Examples from Tests

Standard product with full selectors:

selectors: {
  gallery: { selector: '.configurator-container', replace: true },
  variants: '#ov25-controls',
  swatches: '#ov25-swatches',
  price: { selector: '#price', replace: true },
  name: { selector: '#name', replace: true },
},

Multi-product (modular) with configure button:

selectors: {
  gallery: { selector: '.configurator-container', replace: true },
  configureButton: { selector: '#ov25-fullscreen-button', replace: false },
  variants: '#ov25-controls',
  swatches: '#ov25-swatches',
  price: { selector: '#price', replace: true },
  name: { selector: '#name', replace: true },
},

Configure button only:

selectors: {
  gallery: { selector: '.configurator-container', replace: true },
  price: { selector: '#price', replace: true },
  name: { selector: '#name', replace: true },
  configureButton: { selector: '[data-ov25-configure-button]', replace: true },
},

No variants – omit variants:

selectors: {
  gallery: { selector: '.configurator-container', replace: true },
  swatches: '#ov25-swatches',
  price: { selector: '#price', replace: true },
  name: { selector: '#name', replace: true },
},

No pricing – omit price, set flags.hidePricing: true:

selectors: {
  gallery: { selector: '.configurator-container', replace: true },
  variants: '#ov25-controls',
  swatches: '#ov25-swatches',
  name: { selector: '#name', replace: true },
},
flags: { hidePricing: true },

🎠 Carousel

Controls thumbnail display below the main image.

type ResponsiveValue<T> = { desktop: T; mobile?: T };
 
type CarouselDisplayMode = 'none' | 'carousel' | 'stacked';
 
type CarouselConfig = ResponsiveValue<CarouselDisplayMode> & {
  maxImages?: number | ResponsiveValue<number>;
};

Value	Description
`'none'`	No carousel thumbnails
`'stacked'`	Thumbnails stacked vertically
`'carousel'`	Thumbnails in horizontal carousel

Defaults: desktop: 'stacked', mobile inherits from desktop.

Examples

No carousel:

carousel: { desktop: 'none', mobile: 'none' },

Stacked with max images:

carousel: { desktop: 'stacked', mobile: 'stacked', maxImages: { desktop: 4, mobile: 6 } },

Horizontal carousel:

carousel: { desktop: 'carousel', mobile: 'carousel', maxImages: { desktop: 12, mobile: 6 } },

Standard:

carousel: { desktop: 'stacked', mobile: 'carousel' },

🎛️ Configurator

Controls how the configurator panel is shown and how variants are displayed.

type ResponsiveValue<T> = { desktop: T; mobile?: T };
 
type ConfiguratorDisplayMode = 'inline' | 'sheet' | 'drawer';
type VariantDisplayMode = 'wizard' | 'list' | 'tabs' | 'accordion' | 'tree';
 
type ConfiguratorConfig = {
  displayMode: ResponsiveValue<ConfiguratorDisplayMode>;
  triggerStyle?: ResponsiveValue<'single-button' | 'split-buttons'>;
  variants?: {
    displayMode: ResponsiveValue<VariantDisplayMode>;
    useSimpleVariantsSelector?: boolean;
  };
};

Display Mode

Desktop	Mobile	Description
`'inline'`	`'inline'`	Variants shown inline on the page
`'sheet'`	`'drawer'`	Full-screen sheet (desktop), bottom drawer (mobile)
`'sheet'`	`'inline'`	Sheet on desktop, inline on mobile

Defaults: desktop: 'sheet', mobile: 'drawer' (when desktop is sheet) or 'inline' (when desktop is inline).

Trigger Style

'single-button' – One "Configure" button
'split-buttons' – Separate Add to basket / Buy now

Default: 'single-button'

Variant Display Mode

Value	Description
`'tree'`	Hierarchical tree
`'list'`	Flat list
`'tabs'`	Tabbed groups
`'accordion'`	Collapsible sections (desktop only; mobile falls back to tree)
`'wizard'`	Step-by-step wizard

Defaults: desktop: 'tree', mobile: 'list'

useSimpleVariantsSelector

When true, shows a single "Configure" button that opens the variant panel. Useful when you don't want inline variant controls.

Examples

Inline + wizard:

configurator: {
  displayMode: { desktop: 'inline', mobile: 'inline' },
  triggerStyle: { desktop: 'single-button', mobile: 'single-button' },
  variants: { displayMode: { desktop: 'wizard', mobile: 'wizard' } },
},

Sheet + tabs:

configurator: {
  displayMode: { desktop: 'sheet', mobile: 'drawer' },
  triggerStyle: { desktop: 'single-button', mobile: 'single-button' },
  variants: { displayMode: { desktop: 'tabs', mobile: 'tabs' } },
},

Inline + accordion:

configurator: {
  displayMode: { desktop: 'inline', mobile: 'inline' },
  triggerStyle: { desktop: 'single-button', mobile: 'single-button' },
  variants: { displayMode: { desktop: 'accordion', mobile: 'list' } },
},

Configure button only with simple selector:

configurator: {
  displayMode: { desktop: 'sheet', mobile: 'drawer' },
  triggerStyle: { desktop: 'single-button', mobile: 'single-button' },
  variants: {
    displayMode: { desktop: 'tabs', mobile: 'list' },
    useSimpleVariantsSelector: true,
  },
},

📞 Callbacks

interface CallbacksConfig {
  addToBasket: (payload?: OnChangePayload) => void;
  buyNow: (payload?: OnChangePayload) => void;
  buySwatches: (swatches: Swatch[], swatchRulesData: SwatchRulesData) => void;
  onChange?: (payload: OnChangePayload) => void;
}

addToBasket – Add configured product or scene to basket. When invoked by the UI, receives a normalized OnChangePayload; skus and price may be null until those iframe messages have arrived.
buyNow – Checkout immediately. Same payload shape as addToBasket.
buySwatches – Purchase selected swatches. Receives Swatch[] and SwatchRulesData.
onChange – Optional. Fires when price or SKU updates. Payload is normalized by the UI package (see below); skus and price are each null until that message type has been received at least once.

📋 Payload Types (skus and price)

The iframe emits CURRENT_SKU and CURRENT_PRICE as postMessage events. Wire JSON can differ between single-product and multi-product configurators (one billable line vs many). The UI package normalizes both into one contract before your callbacks run.

OnChangePayload is an alias of UnifiedOnChangePayload:

type OnChangePayload = UnifiedOnChangePayload;
 
interface UnifiedOnChangePayload {
  skus: UnifiedSkuPayload | null;
  price: UnifiedPricePayload | null;
}

Key	Type	When populated
`skus`	`UnifiedSkuPayload \| null`	After first `CURRENT_SKU`
`price`	`UnifiedPricePayload \| null`	After first `CURRENT_PRICE`

Canonical fields for new integrations: use payload.skus.lines and payload.price.lines, and branch on payload.skus.mode / payload.price.mode ('single' \| 'multi').

Legacy (single-product only): when skus.mode === 'single', top-level skuString and skuMap match older integrations. For multi-product SKU payloads, mode === 'multi' and there is no top-level skuString—iterate lines instead.

Null-check and narrow mode before reading skuString:

import type { OnChangePayload } from 'ov25-ui';
 
onChange: (payload: OnChangePayload) => {
  if (payload.skus?.mode === 'single') {
    const sku = payload.skus.skuString;
    const colorSku = payload.skus.skuMap?.['Color'];
  }
  if (payload.skus?.mode === 'multi') {
    for (const line of payload.skus.lines) {
      console.log(line.id, line.quantity, line.skuString, line.skuMap);
    }
  }
  if (payload.price) {
    const displayPrice = payload.price.formattedPrice;
    const hasDiscount = payload.price.discount.percentage > 0;
    for (const line of payload.price.lines) {
      console.log(line.name, line.formattedPrice, line.selections);
    }
  }
},

Optional helpers (same package) if you handle raw postMessage outside injectConfigurator: normalizeSkuPayload, normalizePricePayload, parseIframeJsonPayload.

UnifiedSkuPayload (skus)

Discriminated union:

interface CommerceLineItemSku {
  id: string;
  skuString: string;
  skuMap: Record<string, string>;
  quantity: number;
}
 
interface UnifiedSkuPayloadSingle {
  mode: 'single';
  lines: CommerceLineItemSku[]; // length 1
  skuString: string;
  skuMap?: OptionSkuMap;
}
 
interface UnifiedSkuPayloadMulti {
  mode: 'multi';
  lines: CommerceLineItemSku[];
}
 
type UnifiedSkuPayload = UnifiedSkuPayloadSingle | UnifiedSkuPayloadMulti;
type OptionSkuMap = Record<string, string>;

`mode`	Meaning	Top-level `skuString` / `skuMap`	Canonical
`'single'`	One configured product	Set (backward compatible)	`lines[0]` plus legacy fields
`'multi'`	Multiple billable lines in the scene	Absent	`lines` only

OnChangeSkuPayload in TypeScript is an alias of UnifiedSkuPayload.

UnifiedPricePayload (price)

Order-level totals plus normalized per-line breakdown (replaces relying only on raw priceBreakdown / productBreakdowns from the iframe):

interface CommerceLineItemSelection {
  category?: string;
  name: string;
  sku?: string;
  price: number;
  formattedPrice: string;
  thumbnail?: string;
}
 
interface CommerceLineItemPrice {
  id: string;
  name: string;
  quantity: number;
  price: number;
  formattedPrice: string;
  subtotal: number;
  formattedSubtotal: string;
  discountedAmount: number;
  formattedDiscountAmount: string;
  discountPercentage: number;
  selections: CommerceLineItemSelection[];
  modelId?: string;
}
 
interface UnifiedPricePayload {
  mode: 'single' | 'multi';
  totalPrice: number;
  subtotal: number;
  formattedPrice: string;
  formattedSubtotal: string;
  discount: {
    amount: number;
    formattedAmount: string;
    percentage: number;
  };
  lines: CommerceLineItemPrice[];
  /** Present when the iframe sent single-product `priceBreakdown`. */
  priceBreakdown?: unknown[];
  /** Present when the iframe sent multi-product `productBreakdowns`. */
  productBreakdowns?: unknown[];
}

Field	Description
`totalPrice`, `subtotal`	Minor units (e.g. pence).
`formattedPrice`, `formattedSubtotal`	Display strings.
`lines`	Canonical per-line pricing; use for multi-product carts.
`priceBreakdown` / `productBreakdowns`	Optional passthrough of raw iframe arrays for legacy tooling.

OnChangePricePayload is an alias of UnifiedPricePayload.

Swatch and SwatchRulesData (buySwatches)

interface Swatch {
  name: string;
  option: string;
  manufacturerId: string;
  description: string;
  sku: string;
  thumbnail: {
    blurHash: string;
    thumbnail: string;
    miniThumbnails: { large: string; medium: string; small: string };
  };
}
 
type SwatchRulesData = {
  freeSwatchLimit: number;
  canExeedFreeLimit: boolean;
  pricePerSwatch: number;
  minSwatches: number;
  maxSwatches: number;
  enabled: boolean;
};

Example with onChange

function formatSkuSummary(skus: OnChangePayload['skus']) {
  if (!skus) return '—';
  if (skus.mode === 'single') return skus.skuString;
  return skus.lines.map((l) => `${l.quantity}× ${l.skuString}`).join(', ');
}
 
callbacks: {
  addToBasket: (payload?: OnChangePayload) =>
    alert(`Checkout: ${payload?.price?.formattedPrice ?? '—'} / ${formatSkuSummary(payload?.skus ?? null)}`),
  buyNow: (payload?: OnChangePayload) =>
    alert(`Buy now: ${payload?.price?.formattedPrice ?? '—'} / ${formatSkuSummary(payload?.skus ?? null)}`),
  buySwatches: () => alert('Add swatches to cart'),
  onChange: (payload: OnChangePayload) => {
    if (payload.skus?.mode === 'single') {
      console.log('SKU:', payload.skus.skuString, payload.skus.skuMap);
    } else if (payload.skus?.mode === 'multi') {
      console.log('SKU lines:', payload.skus.lines);
    }
    if (payload.price) console.log('Price:', payload.price.formattedPrice, payload.price.discount, payload.price.lines);
  },
},

⚙️ Optional Fields

configurationUuid

Saved configuration UUID for multi-product modular experiences. Restores a previously saved scene/configuration.

productLink: () => 'snap2/4',
configurationUuid: () => '68245136-580c-4481-864c-1da82f3a50db',

images

Override product images (e.g. for galleries with custom image sets).

images: Array.from({ length: imageCount }, (_, i) => `https://picsum.photos/600/600?random=${i + 1}`),

uniqueId

Disambiguates when multiple configurators share global containers (e.g. mobile drawer, toaster).

branding

type BrandingConfig = {
  logoURL?: string;
  mobileLogoURL?: string;
  cssString?: string;
};

cssString – Custom CSS injected into configurator components. See Configurator Styling for CSS variables, class names, and data attributes.

branding: {
  cssString: `
    .ov25-variant-control { background-color: red; }
    .ov25-dimensions-width, .ov25-dimensions-height { border: 2px dashed green; }
  `,
},

flags

type FlagsConfig = {
  hidePricing?: boolean;
  hideAr?: boolean;
  deferThreeD?: boolean;
  showOptional?: boolean;
  forceMobile?: boolean;
  autoOpen?: boolean;
};

Flag	Type	Description
`hidePricing`	`boolean`	Hide price display
`hideAr`	`boolean`	Hide AR features
`deferThreeD`	`boolean`	Defer 3D loading
`showOptional`	`boolean`	Show optional options
`forceMobile`	`boolean`	Force mobile layout (e.g. for device frame testing)
`autoOpen`	`boolean`	Auto-open configurator on load (non-inline only). Default `false`.

🏷️ Product Types (productLink)

Pattern	Example
Single product	`'217'`, `'58'`, `'607'`
Multi-product modular (`snap2/…` path)	`'snap2/4'`, `'snap2/126'`
Range	`'range/126'`, `'range/85'`

The snap2/ prefix is the URL convention for multi-product modular configurators; callback payloads still use mode: 'single' | 'multi', not this path string.

🔄 Multiple Configurators

Pass an array of configs. Each config must use distinct selectors (e.g. #gallery-1, #gallery-2). For standard configs, gallery and variants selectors must be unique across configs.

⚠️ Multi-product modular with replace: true on configure buttons: When multiple such configs use replace: true, only one configurator instance is active at a time. Clicking a different configure button switches to that product's configurator.

Multi-product modular, configure buttons only:

injectConfigurator([
  {
    apiKey: '15-...',
    productLink: 'snap2/126',
    selectors: { configureButton: { selector: '#ov25-fullscreen-button', replace: true } },
    callbacks: { addToBasket: () => {}, buyNow: () => {}, buySwatches: () => {} },
  },
  {
    apiKey: () => '15-...',
    productLink: () => 'snap2/292',
    selectors: { configureButton: { selector: '#test', replace: true } },
    callbacks: { addToBasket: () => {}, buyNow: () => {}, buySwatches: () => {} },
  },
]);

4 products with gallery, price, name:

injectConfigurator([
  { selectors: { gallery: '#gallery-1', price: { selector: '#price-1', replace: true }, name: { selector: '#name-1', replace: true } }, ... },
  { selectors: { gallery: '#gallery-2', price: { selector: '#price-2', replace: true }, name: { selector: '#name-2', replace: true } }, ... },
  // ...
]);

Inline variant controls per product – use configurator.displayMode: { desktop: 'inline', mobile: 'inline' }.

Ranges with variants – use productLink: 'range/126' with variants selector.

🌐 Global APIs

When the configurator is injected, these functions are exposed on window:

Function	Description
`window.ov25OpenConfigurator(optionName?)`	Open configurator; optionally focus an option group (e.g. `'wood finishes'`)
`window.ov25CloseConfigurator()`	Close configurator
`window.ov25OpenSwatchBook()`	Open swatch book
`window.ov25CloseSwatchBook()`	Close swatch book

Example:

<button onClick={() => window.ov25OpenConfigurator?.()}>Open configurator</button>
<button onClick={() => window.ov25OpenConfigurator?.('wood finishes')}>Open configurator (Wood finishes)</button>
<button onClick={() => window.ov25CloseConfigurator?.()}>Close configurator</button>
<button onClick={() => window.ov25OpenSwatchBook?.()}>Open swatches</button>
<button onClick={() => window.ov25CloseSwatchBook?.()}>Close swatches</button>

🕰️ Legacy Format

A flat config format is supported for backward compatibility. Use addToBasketFunction, buyNowFunction, buySwatchesFunction (or addSwatchesToCartFunction as alias), onChangeFunction, and flat selector/carousel/configurator fields instead of callbacks, selectors, carousel, configurator. The grouped format above is preferred.

Built with ❤️ by the Orbital Vision team

🚀 UI Package Integration Guide

On this page