Script Tag (Direct Integration)

Add the Wedding Band Builder directly to your website with a single script tag. You get full JavaScript access to the viewer and API on the same page, with no iframes or message passing needed.

Image

Screenshot showing a webpage with the 3D ring viewer on the left and the built-in configuration panel on the right, integrated directly into the host page.

When to Use This

• You own the page and can add <script> tags
• You want direct JavaScript access to the API (no postMessage overhead)
• You want the built-in UI panel, or plan to build a custom one

Make Your Configurator Public

Before embedding, make your configurator accessible:

1. Open iJewel3D Dashboard
2. Right-click your Wedding Band Configurator file
3. Select Make Public

Image

Screenshot of the iJewel Dashboard context menu with "Make Public" highlighted.

Quick Start

1. Add the script and create a container:

<script src="https://releases.ijewel3d.com/libs/mini-viewer/latest/bundle.iife.js"></script>
<div id="viewer-root" style="width: 100%; height: 600px;"></div>

2. Initialize the viewer:

<script>
  new ijewelViewer.Viewer(document.getElementById('viewer-root'), {
    name: 'Wedding Band Builder',
    version: 'v5',
    basePath: 'https://your-cdn.com/wbb-assets/',
    plugins: {
      WeddingBandBuilder: {
        manifestUrl: 'wedding-band-project.json',
        showUI: true,
      },
    },
  }, {
    showCard: false,
    showSwitchNode: false,
    showUiButtons: true,
    showConfigurator: false,
    showZoomButtons: true,
    enableZoom: true,
  });
</script>

Image

Screenshot of a page with the Wedding Band Builder fully loaded: 3D viewer on the left, built-in panel on the right.

3. Access the API:

window.addEventListener('ijewel-viewer-ready', (e) => {
  const viewer = e.detail.viewer;
  const api = viewer.getPluginByType('WeddingBandBuilder').controller;

  // Change ring properties
  api.setWidth(5.0);
  api.setMaterial(1, 'Yellow', 'Polished');

  // Listen for price changes
  api.events.on('price:updated', (data) => {
    document.getElementById('price').textContent = `$${data.pricing.totalUsd.toFixed(2)}`;
  });
});

View complete example for a single copy-paste HTML file with everything wired up.

Headless Mode (Custom UI)

Set showUI: false to hide the built-in panel and build your own controls:

plugins: {
  WeddingBandBuilder: {
    manifestUrl: 'wedding-band-project.json',
    showUI: false,   // hide the built-in panel
  },
},

The 3D viewer renders full width with no overlaid UI. You control everything through the API by populating dropdowns from catalog methods, wiring controls to setters, and listening for events.

Image

Side-by-side: Left shows the viewer with built-in panel (showUI: true). Right shows the viewer full width with a custom-designed control panel below it (showUI: false).

See Custom UI (Headless) for a full guide on building custom controls.

Theming

Customize the built-in panel's appearance to match your brand:

api.setTheme('luxury-gold');

// Or with custom colors and fonts
api.setTheme({
  preset: 'modern-minimal',
  colors: { primary: '#2E5B3C', background: '#F5F7F5' },
  fonts: {
    body: "'Cormorant Garamond', serif",
    googleFonts: ['Cormorant+Garamond:wght@400;500;600'],
  },
});

Image

Grid of 4 screenshots showing the same ring with different themes applied: default, luxury-gold, dark, and a custom brand theme.

Available presets: default, luxury-gold, modern-minimal, dark, rose-elegant, bauhaus, euro-modern, soft-modern, swiss-precision, ijewel. See Theming & Branding for full customization options.

Framework Examples

Framework	What You Get	Example
Vanilla JS	Plain HTML/JS, no build step	View example
React	Component + hooks, headless variant	View example
Vue 3	Composable + SFC, headless variant	View example
Next.js	Client component, App Router + Pages Router	View example
Angular	Service + Component, RxJS observables	View example
Svelte	Component with slots, headless variant	View example

Video

Short video showing the complete setup: creating the HTML file, loading it in a browser, and interacting with the built-in panel to customize a ring.

Error Handling

api.events.on('error', (err) => {
  console.error(`[${err.source}] ${err.message}`);
});

Multiple Viewers

You can have multiple viewers on one page. Each gets its own API instance:

const viewer1 = new ijewelViewer.Viewer(root1, project1, options);
const viewer2 = new ijewelViewer.Viewer(root2, project2, options);

Configuration Reference

Project Options

Property	Type	Description
name	string	Display name shown in the loading screen
version	string	Project version (use 'v5')
basePath	string	Base URL for resolving asset paths in the manifest
plugins.WeddingBandBuilder.manifestUrl	string	URL to the manifest JSON file (relative to basePath)
plugins.WeddingBandBuilder.showUI	boolean	Whether to show the built-in configuration panel (defaults to true)

Viewer Options

Property	Type	Default	Description
showCard	boolean	false	Show the product info card
showSwitchNode	boolean	false	Show the model switcher
showUiButtons	boolean	true	Show viewer control buttons (quality, reset view, etc.)
showConfigurator	boolean	false	Show the generic configurator panel (not needed since WBB has its own)
showZoomButtons	boolean	true	Show +/- zoom controls
enableZoom	boolean	true	Allow scroll/pinch zoom

Container Sizing & Mobile Layout

Container Sizing

The viewer fills its container. Make sure the container has explicit dimensions:

/* Full viewport */
#viewer-root { width: 100vw; height: 100vh; }

/* Fixed size */
#viewer-root { width: 800px; height: 600px; }

/* Responsive (4:3 aspect ratio) */
#viewer-root { width: 100%; height: 0; padding-bottom: 75%; position: relative; }

DANGER

The viewer fills its container. If the container has zero height, nothing renders. Always set height explicitly:

<div id="viewer" style="width: 100%; height: 600px;"></div>

This is the most common cause of a blank viewer.

Mobile Responsiveness

The built-in panel automatically switches to a stacked layout on screens narrower than 768px. The 3D viewer sits on top and the configuration panel goes below, each taking 50% of the viewport height. Tab labels collapse to icons only.

Image

Side-by-side showing the desktop layout (viewer left, panel right) and mobile layout (viewer top, panel bottom with icon-only tabs).

URL Parameters

The viewer page accepts these query parameters:

Parameter	Default	Description
manifest	wedding-band-project.json	URL to the manifest JSON file
basePath	(viewer page directory)	Base URL for resolving asset paths
ui	true	Set to false for headless mode

Next Steps

• Custom UI (Headless) to build a fully custom UI
• Theming & Branding to customize the look and feel
• API Reference for complete method documentation
• Pricing Engine to configure the pricing engine