🚀 UI Package Integration Guide

{
  "stringReplacements": {
    "configureButtonText": [
      { "template": "Customise" }
    ]
  }
}

{
  "stringReplacements": {
    "optionHeader": [
      {
        "trigger": { "name": "OPTION_NAME", "value": "fabric" },
        "template": "Choose your fabric"
      },
      {
        "template": "${OPTION_NAME}"
      }
    ]
  }
}

{
  "apiKey": "15-...",
  "productLink": "217",
  "selectors": {
    "gallery": { "selector": ".configurator-container", "replace": true },
    "price": { "selector": "#price", "replace": true },
    "name": { "selector": "#name", "replace": true }
  },
  "configurator": {
    "displayMode": { "desktop": "sheet", "mobile": "drawer" },
    "triggerStyle": { "desktop": "single-button", "mobile": "single-button" },
    "variants": { "displayMode": { "desktop": "tree", "mobile": "list" } }
  },
  "carousel": { "desktop": "stacked", "mobile": "carousel" },
  "branding": { "logoURL": "https://example.com/logo.svg" },
  "flags": { "hidePricing": false, "autoOpen": false }
}

npm i ov25-ui@latest

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

type StringOrFunction = string | (() => string);
 
interface SelectorsConfig {
  /** Root target for full-page display modes that own their own shell (e.g. dining). */
  root?: ElementSelector;
  gallery?: ElementSelector;
  /** Optional header override for inline-sticky; omission enables automatic detection. */
  header?: string;
  /** Optional external carousel targets for each viewport. */
  desktopCarousel?: ElementSelector;
  mobileCarousel?: ElementSelector;
  price?: ElementSelector;
  name?: ElementSelector;
  variants?: ElementSelector;
  swatches?: ElementSelector;
  configureButton?: ElementSelector;
  /** Multi-product modular: external mount point for the starting-module menu. */
  initialiseMenu?: ElementSelector;
}

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

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);

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

selectors: {
  gallery: { selector: '.configurator-container', replace: true },
  variants: '#ov25-controls',
  header: '#shopify-section-announcement-bar, #shopify-section-header',
},

<div class="product-layout">
  <div class="configurator-container"></div>
  <aside>
    <div id="ov25-controls"></div>
    <div data-ov25-mobile-carousel-target></div>
  </aside>
</div>

selectors: {
  gallery: { selector: '.configurator-container', replace: true },
  variants: '#ov25-controls',
  desktopCarousel: '#desktop-product-gallery',
  mobileCarousel: '[data-ov25-mobile-carousel-target]',
},

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

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 },
},

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 },
},

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

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

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

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

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

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

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

type ResponsiveValue<T> = { desktop: T; mobile?: T };
 
type ConfiguratorDisplayMode = 'inline' | 'inline-sticky' | 'sheet' | 'drawer' | 'modal' | 'inline-sheet';
type VariantDisplayMode = 'wizard' | 'list' | 'tabs' | 'accordion' | 'tree';
 
type ConfiguratorConfig = {
  displayMode: ResponsiveValue<ConfiguratorDisplayMode>;
  triggerStyle?: ResponsiveValue<'single-button' | 'split-buttons'>;
  variants?: {
    displayMode: ResponsiveValue<VariantDisplayMode>;
    /** Multi-product modular only: which edge the variant sheet attaches to. Default 'RIGHT'. */
    position?: ResponsiveValue<'LEFT' | 'RIGHT'>;
    useSimpleVariantsSelector?: boolean;
    /** Option ids or display names (case-insensitive) to omit from the variant UI. Iframe defaults still apply. */
    hideOptions?: string[];
  };
  /** Multi-product modular only: where the compatible-modules picker is shown. Default 'BOTTOM'. */
  modules?: {
    position?: ResponsiveValue<'LEFT' | 'RIGHT' | 'BOTTOM'>;
  };
};

import { injectConfigurator, type InjectConfiguratorInput } from 'ov25-ui';
 
const config: InjectConfiguratorInput = {
  apiKey: '15-...',
  productLink: '58',
  selectors: {
    gallery: { selector: '.configurator-container', replace: true },
    variants: '#ov25-controls',
    // Optional. Omit this to use automatic header detection.
    header: '#announcement-bar, #site-header',
    // Recommended on mobile so thumbnails sit with the product controls.
    mobileCarousel: '#mobile-product-carousel',
  },
  configurator: {
    displayMode: { desktop: 'inline-sticky', mobile: 'inline-sticky' },
    variants: { displayMode: { desktop: 'list', mobile: 'list' } },
  },
  callbacks: {
    addToBasket: () => {},
    buyNow: () => {},
    buySwatches: () => {},
  },
};
 
injectConfigurator(config);

configurator: {
  displayMode: { desktop: 'inline', mobile: 'inline' },
  variants: {
    displayMode: { desktop: 'tree', mobile: 'list' },
    hideOptions: ['Wood Finish', 'feet'],
  },
},

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

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

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

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

import {
  injectConfigurator,
  STRING_REPLACEMENT_DEFINITIONS,
  type StringReplacementsConfig,
} from 'ov25-ui';

type StringReplacementsConfig = Record<string, StringReplacementRule[]>;
 
type StringReplacementRule = {
  trigger?: {
    name: string;
    value: string;
  };
  template: string;
};

injectConfigurator({
  // ...existing config
  stringReplacements: {
    configureButtonText: [
      { template: 'Customize' },
    ],
    productTitle: [
      { template: '${RANGE_NAME} - ${PRODUCT_NAME}' },
    ],
  },
});

injectConfigurator({
  // ...existing config
  stringReplacements: {
    optionHeader: [
      {
        trigger: { name: 'OPTION_NAME', value: 'leg' },
        template: 'Leg Type',
      },
      {
        trigger: { name: 'OPTION_NAME', value: 'fabric' },
        template: 'Fabric Choice',
      },
      {
        template: '${OPTION_NAME}',
      },
    ],
  },
});

for (const definition of STRING_REPLACEMENT_DEFINITIONS) {
  console.log(definition.key, definition.label, definition.defaultTemplate);
  console.log(definition.interpolationValues);
}

type StringReplacementDefinition = {
  key: string;
  label: string;
  description?: string;
  defaultTemplate: string;
  interpolationValues: Array<{
    name: string;
    description?: string;
  }>;
};

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

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

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);
    }
  }
},

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>;

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[];
}

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;
};

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);
  },
},

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

import { injectConfigurator, type ProductImageInput } from 'ov25-ui';
 
const images: ProductImageInput[] = [
  'https://cdn.example.com/product/lifestyle.jpg',
  {
    alt: 'Sofa in green wool',
    urls: {
      thumbnail: 'https://cdn.example.com/product/thumbnail.jpg',
      small_image: 'https://cdn.example.com/product/small.jpg',
      image: 'https://cdn.example.com/product/standard.jpg',
      hero: 'https://cdn.example.com/product/hero.jpg',
      original: 'https://cdn.example.com/product/original.jpg',
    },
  },
];
 
injectConfigurator({
  // ...required config
  images,
});

type ProductImageInput =
  | string
  | {
      alt?: string;
      urls?: Record<string, string>;
    };

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

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

type FlagsConfig = {
  hidePricing?: boolean;
  disableAddToCart?: boolean;
  disableBuyNow?: boolean;
  hideAr?: boolean;
  hideGestureHint?: boolean;
  deferThreeD?: boolean;
  showOptional?: boolean;
  forceMobile?: boolean;
  autoOpen?: boolean;
  currencySymbol?: string;
};

type BedAllowNonePartsInput = {
  headboard: boolean;
  base: boolean;
  mattress: boolean;
};
 
type BedPartSizeFilterFlags = {
  headboard: boolean;
  base: boolean;
  mattress: boolean;
};
 
type BedEmbedConfig = {
  /** Allow-list of parts that may be set to "None". Omit (or set all true) to allow None on every part. */
  allowNone?: BedAllowNonePartsInput;
  /** When `true` for a part, variant UI hides selections whose `metadata.bedSize` ≠ iframe current size. */
  filterSelectionsByCurrentSize?: BedPartSizeFilterFlags;
};

bed: {
  allowNone: { headboard: true, base: false, mattress: false },
  filterSelectionsByCurrentSize: { headboard: false, base: true, mattress: true },
},

type DiningEmbedConfig = {
  displayMode?: ResponsiveValue<'split' | 'full-page'>;
  displayOptions?: {
    /** Show in-scene dining attachment point buttons. Default true. */
    showAttachmentPoints?: boolean;
  };
  /** Optional hero images for the full-page style-choice screen. */
  styleImages?: { fullRange?: string; mixAndMatch?: string };
};

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: () => {} },
  },
]);

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 } }, ... },
  // ...
]);

<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>
<button
  onClick={async () => {
    const url = await window.ov25GenerateThumbnail?.();
    console.log('Thumbnail URL:', url);
  }}
>
  Generate thumbnail
</button>