Viewer and embeds

Install

<script async src="https://cdn.glboost.com/_/embed.js"></script>
<glboost-viewer asset="a1b2c3d4e5f6" ar poster="auto" style="height:480px"></glboost-viewer>

The element fills its container, so give the parent a height or an aspect ratio. Decoders for meshopt, Draco, and KTX2 load from the CDN on demand.

Attributes

asset

The asset id (required).

preset / spec

Which variant to load; default gpu. auto picks mobile on phones with little memory, data saver, or a slow connection and gpu elsewhere (ignored when sig is set). spec takes raw parameters such as tex=webp&maxtex=1024.

v

Pin a version.

exp, sig

Signature for private assets, minted by your server through POST /api/v1/assets/:id/sign.

poster

auto uses the poster captured in the dashboard; or any image URL.

ar

Show the AR button (WebXR, Scene Viewer, Quick Look). When the asset has a USDZ export, iOS opens it directly instead of converting the model on the device.

auto-rotate, no-controls

Rotate slowly; disable orbit controls.

environment

neutral, studio, outdoor, a custom environment id, or an https URL.

lod

auto loads the lightest ready level of the project LOD ladder that fits the element (half a triangle per rendered pixel, floor 20,000) and steps up when it grows; progressive starts with the lightest level for models over 2 MB and upgrades after each load; a ratio such as 0.5 pins a level. Ignored when sig is set.

reveal, loading

reveal="interaction" shows the poster with a play button and downloads the model on the first tap (needs a poster); loading passes to model-viewer (auto, lazy, eager).

variant-picker

Chips for the model's KHR_materials_variants, with the labels and swatches saved in the viewer settings; hidden under two variants. Hotspots can switch variants too.

tools

measure adds a ruler button: click two points on the model to read the distance between them.

measure-units, measure-scale

m (default), cm, mm, in, or ft; and model units per metre for models not built in metres.

no-settings, no-hotspots

Ignore the camera and lighting saved in the dashboard; hide hotspots.

variant

Select a KHR_materials_variants variant by name.

watermark

Force the GLBoost badge (Free plan embeds always show it).

alt

Accessible description.

JavaScript API

const el = document.querySelector('glboost-viewer');
await el.ready;
el.setCamera({ yaw: 30, pitch: 75, distance: 2.5, fov: 40 });
el.getCamera();                // { yaw, pitch, distance, fov }
el.recenter();
el.play('Idle', { speed: 1 }); el.pause(); el.animations;
el.setVariant('Red'); el.variants;
el.resolvedPreset;             // what preset="auto" chose for this device
const png = await el.toBlob({ mimeType: 'image/png' });
el.pickPoint(clientX, clientY);   // { position, normal } on the surface, or null
el.setPins([{ id: 'c1', label: '1', position, normal }]);
el.startMeasure(); el.measure; el.showMeasure(a, b); el.clearMeasure();
el.reload();

Events

load

{ assetId, versionId, spec, loadMs } after the first successful load.

progress

Download progress from model-viewer.

camera-change

The current pose and its source.

hotspot-click

The hotspot that was clicked.

pin-click

{ id } for review pins set with setPins.

lod-change

{ ratio, spec } whenever the lod attribute switches level after the first load.

variant-change

{ name } when the variant changes (chips, hotspots, setVariant).

measure-change

{ a, b, distance, text } when a measurement completes; null when it is cleared.

error

{ message } when the config or model fails to load.

data-ready

Not an event: an attribute the element sets on itself once the model has loaded and clears when a new load starts, for CSS (fade the element in) or for screenshots; GLBoost renders posters by waiting for glboost-viewer[data-ready].

iframe

<iframe src="https://glboost.com/e/a1b2c3d4e5f6?ar=1" allow="xr-spatial-tracking; fullscreen"
        style="width:100%;height:480px;border:0"></iframe>

Use the iframe on platforms that sandbox custom scripts. Query parameters mirror the attributes.

Private assets

Private assets return 403 without a valid signature. Your server mints one with the API (POST /api/v1/assets/:id/sign, up to 24 hours) and passes exp and sig to the element, or you send people to a share link instead.

React

npm install @glboost/react

import { GLBoostViewer } from '@glboost/react';

<GLBoostViewer asset="abc123def456" preset="gpu" ar style={{ width: '100%', height: 480 }} />

@glboost/react wraps the element with the attributes as camelCase props (autoRotate, variantPicker, measureUnits), typed callbacks for the events (onLoad, onHotspotClick, onCameraChange, onMeasureChange), a pins prop for review pins, and a ref to the element's JavaScript API. It loads embed.js from the CDN once per page; the dashboard uses the same package.