Configurator Styling

This document explains how to customize the OV25 configurator UI: Shadow DOM and why styles must pass through inject, display modes, global CSS variables, data attributes, class names, and the ov: Tailwind prefix.

1. Overview: Shadow DOM and Why Inject Is Needed

Many configurator components render inside Shadow DOM. Shadow roots do not inherit styles from the host document, so custom styles must be passed via branding.cssString in the inject config. Without this, your CSS will not reach the configurator UI.

Components by Shadow DOM Usage

Source: src/utils/inject.tsx – shouldCreateShadowDOM returns false only for gallery, price, name (the Price and Name components then wrap their own content in Ov25ShadowHost).

Global Shadow Containers

Created by inject, each receives [sharedStylesheet, userCustomCssStylesheet(cssString)]:

• ov25-mobile-drawer-container
• ov25-snap2-checkout-sheet-container
• ov25-configurator-view-controls-container
• ov25-popover-portal-container
• ov25-modal-portal-container
• ov25-toaster-container
• ov25-swatchbook-portal-container

2. Passing Custom Styles

Use branding.cssString in your inject config:

branding: {
  cssString: `
    .ov25-variant-control { background-color: red; }
    #ov25-variants-header { background: #1a1a1a !important; }
  `,
},

How branding.cssString Is Applied

• Shadow DOM: createuserCustomCssStylesheet(cssString) is appended to each shadow root's adoptedStyleSheets (global containers and every Ov25ShadowHost, including price and name).
• Document: there is no document-level stylesheet adoption - the gallery renders in light DOM and inherits the host page's styles directly.

Reference: dev/react-test/tests/single-custom-css.jsx.

3. Display Modes and Their Styling Hooks

Variant Display Modes

Inline vs Sheet/Drawer

• data-ov25-inline-list on #ov25-aside-menu when variants are inline.
• Variables: --ov25-inline-list-aside-min-height, --ov25-inline-list-aside-max-height-mobile.

Inline (sticky)

The inline-sticky display mode keeps the standard or bed-configurator gallery visible while the page-level variant list scrolls.

• The active gallery host has data-ov25-inline-sticky-active="true".
• data-ov25-inline-sticky-mobile identifies whether the mobile sticky layout is active.
• The runtime measures fixed/sticky storefront headers and exposes its resolved geometry through --ov25-sticky-* custom properties on the gallery and variants hosts.
• On mobile, the viewer is full width and the carousel is moved to the configured mobile target. The automatic mobile fallback target is [data-ov25-sticky-mobile-carousel].
• A carousel moved outside the gallery is marked with data-ov25-external-carousel.

Use the Shopify or WooCommerce Header Selector setting only when automatic header detection does not identify the correct storefront header. Desktop and mobile carousel targets are configured separately by those integrations.

Snap2 Variants Panel

• data-ov25-variants-panel, data-open="true" for the slide panel.
• Styled in globals.css.
• Snap2 supports Dialog and Inline on desktop, and Dialog, Drawer, and Inline on mobile.
• In the desktop Dialog layout, variant position controls the side of the main variant panel. Module position controls whether compatible modules use the left side, right side, or bottom module panel.

4. Global CSS Variables Reference

Override these in :root or via branding.cssString to theme the configurator.

Color Variables

Layout and Sizing

Typography

Display-Mode-Specific

View Controls and Overlays

Swatch Flash Animations

Note: --ov25-text-md-size is referenced in #ov25-mobile-savings-amount but not defined in :root; use an existing variable or add it.

5. Class Names and Data Attributes for Targeting

Use these selectors in branding.cssString to target specific UI elements.

Stable Class Names

Snap2 module cards also expose stable part selectors:

The module name and tooltip remain mounted so custom CSS can switch their visibility. In the Snap2 initialise menu, the name is visible on mobile by default and the tooltip is used on desktop.

6. SwatchBook

SwatchBook has its own set of IDs and classes for customization.

7. Data Attributes

8. IDs

9. Tailwind Prefix (ov:)

All Tailwind utilities use the ov: prefix (e.g. ov:flex, ov:p-2). This avoids clashes with host page Tailwind. Custom styles should not rely on unprefixed Tailwind classes from the configurator.

10. Iframe Dimensions Styling

The dimensions overlay (width, height, depth) is rendered inside the 3D iframe. cssString is sent via VIEW_DIMENSIONS and VIEW_MINI_DIMENSIONS messages. Target these classes in your branding.cssString:

• .ov25-dimensions-width
• .ov25-dimensions-height
• .ov25-dimensions-depth
• .ov25-dimensions-mini

Example: dev/react-test/tests/single-custom-css.jsx.

11. Replaced Elements

When replace: true on a selector, the host element gets ov25-configurator-{componentName} (e.g. ov25-configurator-gallery, ov25-configurator-variants). Use these to target replaced containers from outside Shadow DOM.

12. Hardcoded Values

These are not driven by CSS variables; override with !important or higher specificity if needed:

• .ov25-gradient: linear-gradient(90deg, #26E8FE 0%, #808AFF 50%, #A41EFE 100%)

13. Examples

Override CSS variables

branding: {
  cssString: `
    :root {
      --ov25-primary-color: #1a1a1a;
      --ov25-cta-color: #2563eb;
    }
  `,
},

Target variant controls

branding: {
  cssString: `
    .ov25-variant-control {
      background-color: #f5f5f5;
      border-radius: 8px;
    }
  `,
},

Style dimensions overlay (inside iframe)

branding: {
  cssString: `
    .ov25-dimensions-width, .ov25-dimensions-height, .ov25-dimensions-depth, .ov25-dimensions-mini {
      border: 2px dashed green;
      scale: 1.2;
    }
  `,
},

Customize SwatchBook

branding: {
  cssString: `
    #ov25-swatchbook { border-radius: 16px; }
    .ov25-swatch-item { border: 1px solid #e5e5e5; }
    .ov25-swatchbook-empty-title { font-size: 1.25rem; }
  `,
},

Override variants header

branding: {
  cssString: `
    #ov25-variants-header {
      background: #1a1a1a !important;
    }
  `,
},