Embed Reference

All embed attributes, the JavaScript API, and multi-viewer setup for Vitrine 3D viewers.

Basic embed

Add the script once per page, then place <div> elements wherever you want a viewer:

<script src="https://cdn.vitrine3d.com/vitrine.js"></script>

<div
  data-vitrine
  data-vitrine-id="your-showcase-id"
  style="width: 100%; max-width: 800px; aspect-ratio: 4/3"
></div>

The viewer fills its container. Use CSS to control dimensions — width, max-width, height, and aspect-ratio all work.

Attributes

Attribute	Type	Description
`data-vitrine`	flag	Required. Marks the element as a viewer.
`data-vitrine-id`	string	Showcase ID from the dashboard. Loads the model, config, and thumbnail.
`data-model`	URL	Direct GLB/glTF URL (alternative to showcase ID).
`data-config`	JSON	Inline config patch as JSON string. Overrides showcase defaults.
`data-poster`	`"false"`	Set to `"false"` to disable the loading thumbnail.

Using `data-config`

You can override any scene setting inline:

<div
  data-vitrine
  data-vitrine-id="abc123"
  data-config='{"bg_mode":"transparent","bloom_enabled":false}'
></div>

This is useful for showing the same model with different settings on the same page (e.g., different background colors for each variant).

JavaScript API

The global Vitrine object provides two methods:

`Vitrine.boot(element)`

Manually boots a viewer element. Normally viewers auto-boot on page load and when new elements appear (via MutationObserver). Use this if you add elements dynamically and need immediate control.

const el = document.createElement('div');
el.dataset.vitrine = '';
el.dataset.vitrineId = 'abc123';
el.style.cssText = 'width:100%;aspect-ratio:16/9';
document.body.appendChild(el);

Vitrine.boot(el);

`Vitrine.update(element, config)`

Pushes a config patch to a running viewer. Use this for variant switching, interactive controls, or scroll-driven effects.

// Switch background color
Vitrine.update(el, { bg_color: [0.1, 0.1, 0.1, 1.0] });

// Toggle bloom
Vitrine.update(el, { bloom_enabled: true, bloom_intensity: 0.15 });

The config object accepts the same fields as data-config.

Multiple viewers

You can place multiple viewers on the same page. Each gets its own WASM instance:

<div data-vitrine data-vitrine-id="shoe-black" style="width:300px;aspect-ratio:1"></div>
<div data-vitrine data-vitrine-id="shoe-white" style="width:300px;aspect-ratio:1"></div>
<div data-vitrine data-vitrine-id="shoe-red" style="width:300px;aspect-ratio:1"></div>

Viewers boot sequentially to avoid overwhelming the GPU. Each viewer only renders when visible (IntersectionObserver) and uses zero GPU when idle.

Sizing

The viewer is not an iframe — it participates in your page layout directly. Set dimensions with CSS:

/* Fill container width, fixed aspect ratio */
[data-vitrine] {
  width: 100%;
  aspect-ratio: 4/3;
}

/* Fixed size */
[data-vitrine] {
  width: 600px;
  height: 450px;
}

/* Responsive with max-width */
[data-vitrine] {
  width: 100%;
  max-width: 800px;
  aspect-ratio: 16/9;
}

Lazy loading

Viewers only boot when they enter the viewport (or are close to it). No extra configuration needed — this is the default behavior. Thumbnail posters display immediately for showcases that have them.

Rendering backend

The viewer automatically selects WebGPU when available and falls back to WebGL2 otherwise. See WebGPU Support for details on browser support and troubleshooting.

Embed Reference

On this page