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.

Global Shadow Containers

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

• ov25-mobile-drawer-container
• ov25-configurator-view-controls-container
• ov25-popover-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: createCSSVariablesStylesheet(cssString) is appended to each shadow root's adoptedStyleSheets.
• Document: setupCSSVariables(cssString) adds the same stylesheet to document.adoptedStyleSheets for light-DOM components (gallery, price, name).

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.

Snap2 Variants Panel

• data-ov25-variants-panel, data-open="true" for the slide panel.
• Styled in globals.css.

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

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-variants-header: background: #0c5358
• .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;
    }
  `,
},