Developer Documentation

Quick Start #

One script and one tag. There is no second way of doing this, so nothing here can be the wrong choice.

<script src="https://3d-lion.com/viewer/loader.js" defer></script>

<glb-viewer
  share-token="prj_your_token"
  style="display: block; width: 100%; height: min(78svh, 760px)">
</glb-viewer>

<script
  src="https://3d-lion.com/viewer/loader.js"
  data-token="prj_your_token" defer></script>

That's it. Colour zones, the camera tour and the controls all work — you write no JavaScript.

Your project token (prj_…) is on the project page in your dashboard. Nothing else is needed — your domain is checked on the server.

Common setups #

The things people ask for most are one attribute each. Drop the line inside the tag.

<glb-viewer
  share-token="prj_your_token"
  tour="scroll">
</glb-viewer>

<section style="height: 240vh">
  <glb-viewer share-token="prj_your_token"></glb-viewer>
</section>

.model-stage {
  height: var(--glb-stage-free, 100svh);
}

@media (min-width: 1024px) {
  .model-stage {
    height: min(var(--glb-stage-free, 100svh), 760px);
  }
}

.model-stage {
  --glb-stage-top: 72px;
}

The ones marked live in the table above can be changed at any time with setAttribute — the viewer applies the change without reloading the model.

Attributes #

Set them in HTML, or change them at runtime — everything marked live is re-applied immediately.

The ones without a tick decide what the viewer IS rather than how it behaves — the catalogue comes out of the server already sliced by scenario, the panel's shape is settled before the model is revealed, and a language is a different document. Change one of those and the viewer re-opens at a new address instead of quietly ignoring you.

JavaScript API #

The element exposes exactly one object, frozen, with eight namespaces. Everything else inside the viewer stays private, so your integration keeps working across releases.

const viewer = document.querySelector('glb-viewer');
const { colors, options, tour, camera, animations } = await viewer.ready;

// Every call is a promise: the model runs in its own frame and answers from there.
await colors.getZones();                 // [{ id, label, group, palette, defaultColor, hasView }]
await colors.selectZone('seats');        // flies to the view the author saved for the zone
await colors.selectZone(null);           // visitor left the zone — flies back out
await colors.setColor('seats', '#d8c9a6');
await colors.setColor('seats', '#d8c9a6', { focus: false });  // recolour, camera stays put
await colors.setColors({ seats: '#d8c9a6' });  // whole colourway, camera untouched
await colors.reset();

await options.getGroups();               // the non-colour choices the project carries
await options.select(groupId, optionId);

await tour.play(); await tour.togglePause(); await tour.stop();
await tour.setSpeed(2.4);
await tour.setResumePrompt(false);       // you draw your own resume control

await camera.home();                     // back to the opening view
await camera.setAutoRotate(true);
await camera.setMode('orbit');           // 'orbit' | 'free' | 'walk'
await camera.setLimits({ minDistance: 2, maxPolarAngle: 1.5 });

await animations.getEntries();           // [{ id, label }]
await animations.play(id); await animations.stop(id);

Awaiting viewer.ready leaves nothing to check and nothing to race: it resolves with the same API whenever you ask, before or long after the viewer boots.

Every namespace is always there and every call is a promise, because the answer comes back from the viewer's own frame. Ask a project with no zones to recolour one and the promise rejects — it never quietly returns undefined.

A panel in tone with your site #

The buyer's panel is painted in your colour and in nothing else. Being in tone with any site is what the translucency is for — and that translucency has a computed floor, because the panel has to hold its own text at 4.5:1 over whatever it stands on.

const { panel } = await viewer.ready;

panel.setSkin({
  surface: '#faf7f2',        // your colour — null follows the side your page is on
  surfaceOpacity: 0.7,       // a request: the floor below may raise it
  blur: 30,                  // 0…40 px, dropped once nothing shows through anyway
  accent: '#c07a3e',         // the chosen option and the primary button
  radius: 14,                // 0…32 px
  side: 'right',             // 'right' | 'left' | 'below'
});

// What the panel is standing on. Buys density, never colour.
panel.setBackdrop('#faf7f2');
panel.setBackdrop('#101010', { live: true });  // video, slideshow — counts as nothing said
panel.setBackdrop(null);                       // take the answer back

panel.setOptionDisplay('tiles');  // 'flat' | 'tiles'
panel.getSkin();

The opacity you set is a request, not a result. With no backdrop named, readability has to be guaranteed over every backdrop there is — so the panel settles denser than you asked. Name the backdrop and the request is honoured.

setBackdrop buys density and never colour. The panel on your page and the panel on somebody else's are the same colour; knowing the backdrop only changes how much shows through. Over the whole screen the scene answers instead: your page is no longer behind the panel there.

Name surface explicitly. The viewer stands in a frame of its own, and nothing is inherited across a frame boundary — it reads its own document, not the page beneath it, so it cannot guess whether your site is light or dark.

The accent never adapts. A button that changed colour because of a photograph on the page is a mistake in any brand's eyes.

Reading state #

Every namespace answers getState() with its current snapshot. Use it for values that change too often to broadcast — the tour progress, the camera pose — or to catch up if you attached your listeners late.

const { colors, options, tour, camera, animations } = await viewer.ready;

await colors.getState();      // { zones, colors, selectedZoneId }
await options.getGroups();    // [{ id, label, options: [{ id, chosen, unmet }] }]
await tour.getState();        // { isPlaying, isPaused, progress, hasWaypoints }
await camera.getState();      // { position: [x, y, z], target: [x, y, z] }
await animations.getState();  // { entries: [{ id, label, status }] }

Events #

The viewer tells you what happened, so you never poll it. Everything arrives as an ordinary DOM event on the element — addEventListener, and e.detail is the payload.

const viewer = document.querySelector('glb-viewer');

viewer.addEventListener('glb-viewer:zones', (e) => e.detail.zones);
viewer.addEventListener('glb-viewer:zone', (e) => e.detail.zoneId);   // null = deselected
viewer.addEventListener('glb-viewer:color', (e) => e.detail);          // { zoneId, hex }
viewer.addEventListener('glb-viewer:colors', (e) => e.detail.colors);
viewer.addEventListener('glb-viewer:options', (e) => e.detail.selection);
viewer.addEventListener('glb-viewer:tour:status', (e) => e.detail.isPlaying);
viewer.addEventListener('glb-viewer:build', (e) => e.detail.url);
viewer.addEventListener('glb-viewer:error', (e) => e.detail.code);

Domains and access #

Your key is tied to your domains, and the viewer page is tied to the same list at the browser level. A snippet copied onto someone else's site doesn't work there.

POST /api/v1/viewer/auth/verify
403  { "error": "Domain not allowed" }   // the origin is not on the allowlist

GET /api/v1/viewer/prj_your_token
403  { "code": "PRIVATE_PROJECT" }       // the project is not shared publicly
404  { "code": "NOT_PUBLISHED" }         // the project has never been published

We keep the domain list for you — tell us which addresses to add and we'll update it. Self-service management in the dashboard isn't there yet.

What the widget stores #

The widget runs on your page, so it is you the visitor asks. Here is everything we write to their device and keep on ours, in the same words you can put into your own policy.

This describes how the widget works; it is not a legal document. Agree the wording of your own policy with your own lawyer — especially if you have visitors in the EU, where writing an identifier requires consent.

React, Vue and the rest #

There are no framework packages and none are needed: <glb-viewer> is a plain element, so it works anywhere without a wrapper.

import { useEffect, useRef } from 'react';

export function Configurator({ token }) {
  const ref = useRef(null);

  useEffect(() => {
    let cancelled = false;
    ref.current.ready.then(async ({ colors }) => {
      if (!cancelled) await colors.setColors({ seats: '#d8c9a6' });
    });
    return () => { cancelled = true; };
  }, []);

  return (
    <glb-viewer
      ref={ref}
      share-token={token}
      style={{ display: 'block', width: '100%', height: 600 }}
    />
  );
}

<template>
  <glb-viewer
    ref="viewer"
    :share-token="token"
    style="display: block; width: 100%; height: 600px"
  />
</template>

<script setup>
import { onMounted, ref } from 'vue';

const viewer = ref(null);

onMounted(async () => {
  const { colors } = await viewer.value.ready;
  await colors.setColors({ seats: '#d8c9a6' });
});
</script>

In Vue, add glb-viewer to isCustomElement (vue.compilerOptions.isCustomElement in Nuxt) so the compiler stops looking for a component by that name.

Errors #

Every error carries a stable code — build your logic on that. The message is human copy and may change.

viewer.addEventListener('glb-viewer:error', ({ detail }) => {
  if (detail.code === 'WEBGL_NOT_SUPPORTED') showStaticGallery();
  else if (detail.code === 'PROJECT_NOT_FOUND') hideSection();
  else reportToMonitoring(detail.code, detail.message);
});

TypeScript #

The package ships hand-written declarations for the whole public surface, so the element, its API and every event payload are typed — with nothing internal leaking into your build.

/// <reference types="@glb-viewer/cdn" />

const viewer = document.querySelector('glb-viewer')!;  // GLBViewerElement
const { colors } = await viewer.ready;                 // GLBViewerApi
await colors.setColor('seats', '#d8c9a6');