@virtualdisplay.io/client
v4.0.0-alpha.37
Published
TypeScript-first 3D model integration library with iframe-based architecture
Maintainers
Readme
Virtualdisplay client
TypeScript library for embedding interactive 3D product models in web applications.
- Built-in viewer UI with loading indicator, product controls, and action bar
- Simple attribute-based API for product configurators
- Server-driven configuration, no client-side mapping needed
- Fire-and-forget messaging with automatic state synchronisation
- Zero external dependencies (all bundled)
- Works with any frontend framework or vanilla JavaScript
Installation
npm install @virtualdisplay.io/client
# or
pnpm add @virtualdisplay.io/client
# or
yarn add @virtualdisplay.io/clientQuick start
Simple product (no options)
import { VirtualdisplayClient } from '@virtualdisplay.io/client';
// Your 3D model is now displayed
const client = new VirtualdisplayClient({
parent: '#product-container',
license: 'your-license-key',
model: 'statue-model',
});Configurable product (with options)
import { VirtualdisplayClient } from '@virtualdisplay.io/client';
const client = new VirtualdisplayClient({
parent: '#product-container',
license: 'your-license-key',
model: 'sneaker',
});
// Select a product option. The 3D model updates automatically.
// Calls are buffered until the server provides the attribute mapping
client.select('Color', 'red');The server defines which attributes and values are available for each model. The client receives this configuration automatically via postMessage. No manual mapping required.
Mounting a specific app
A model can have several apps (a plain viewer, a configurator), each with its
own link and its own configuration. Pass the app's link key as app to mount
that exact app:
import { VirtualdisplayClient } from '@virtualdisplay.io/client';
const client = new VirtualdisplayClient({
parent: '#product-container',
app: 'sofa-deluxe-k3f9dm',
});license + model keeps working unchanged and shows the model's default
viewer. If both forms are supplied, app wins and a warning is logged that the
pair was ignored, so adding app to an existing integration is additive. One
of the two forms is required; supplying neither is a compile error.
How it works
The 3D server hosts the viewer in an iframe, keeping WebGL complexity isolated from your application. The client library handles all communication via postMessage.

On startup, the server sends the client its configuration (viewer settings, camera limits) and available product attributes. The loading indicator shows progress while the model downloads.

- Client creates iframe; outgoing messages are queued until the server is ready.
- Server sends
HANDSHAKEwhen its message listener is active; client flushes queue. - Server sends progress updates while the model downloads. The client displays these in the loading indicator.
- Server sends
CONFIGwith viewer settings and camera limits from model metadata. - Server sends
MAPPINGwith attribute definitions, values, and defaults.onReadyfires.
Product configuration
Configure product options by selecting attribute values. The server defines which attributes exist (e.g. "Color", "Size") and which values each has (e.g. "red", "blue"). You select values; the 3D model updates automatically.

select()returns immediately; the result arrives asynchronously.- Each attribute in the result has its own
successflag and optionalerror. - Attributes within the same component fail as a group.
Selecting values
// Select a product option. The 3D model updates automatically.
client.select('Color', 'blue');
client.select('Size', 'large');Can be called immediately after construction. Selections are buffered until the server handshake completes.
Tracking changes
Keep your UI in sync with the 3D server state:
client.onChange('Color', (selectedValue) => {
// selectedValue.value is the selected value (e.g. 'blue')
// selectedValue.isSelected is true
updateColorButton(selectedValue.value);
});Querying available values
// All values for an attribute
const colors = client.getValues('Color');
colors.forEach((av) => {
console.log(av.value, av.isSelected);
});
// A specific value
const blue = client.getValue('Color', 'blue');
if (blue?.isSelected) {
highlightButton('blue');
}Direct attribute access
For advanced use cases, get the Attribute instance directly:
const colorAttr = client.getAttribute('Color');
if (colorAttr) {
colorAttr.select('blue');
colorAttr.getValues(); // AttributeValue[]
// Each value carries the word to render. `value` is the key you pass back to
// `select`; `label` is what to show, which the model may name
// ({ value: 'RAL3020', label: 'Signaalrood' }). Where the model names none,
// `label` is the value made readable: `redWine` reads as "Red wine".
// A measurement is the exception: its values are millimetres, and what to
// show depends on the model's unit and the reader's locale.
colorAttr.getValues().map((v) => ({ key: v.value, shown: v.label }));
colorAttr.getValue('blue'); // AttributeValue | undefined
colorAttr.onChange((value) => { ... });
}Handling failed mutations
client.onMutationFailed(({ attribute, value }) => {
console.error(`Mutation failed: ${attribute} = ${value}`);
});Snapshots
Capture the current 3D view as an image. Useful for product shots, social sharing, or saving configurations.

- Filename is validated client-side (extension, no path traversal).
- Server always responds, either with image data or an error reason.
Taking a snapshot
const photo = client.snapshot.take('product-hero-shot.png');
// Register callback for when image is ready
photo.onDeveloped((photoData) => {
// photoData.filename - The filename you provided
// photoData.data - Base64 encoded image data
const img = document.createElement('img');
img.src = photoData.data;
document.body.appendChild(img);
});
// Handle errors (e.g., canvas not available)
photo.onError((error) => {
console.error('Snapshot failed:', error.message);
});Filename must end with .png. The server always returns PNG data.
Camera
The standard interface includes built-in camera controls when they are enabled in the Virtualdisplay portal. The camera can also be controlled programmatically.

- Commands accumulate via chaining;
.set()sends them all at once. .reset()sends immediately without chaining.- Position updates are continuous. They fire on both programmatic and user-driven camera movement.
Controlling the camera
// Chain commands, then send with .set()
client.camera.rotate(45).set();
client.camera.rotate(90).tilt(45).zoom(150).set();
// Reset to the default position configured in the portal (sends immediately)
client.camera.reset();Tracking camera position
The current camera position is updated in real-time as the user orbits, zooms, or tilts the model.
client.cameraPosition.onChange((position) => {
console.log(position.rotation, position.tilt, position.zoom);
});
// Read current values directly
console.log(client.cameraPosition.rotation);
console.log(client.cameraPosition.tilt);
console.log(client.cameraPosition.zoom);Annotations
Annotations are interactive markers placed on the 3D model. They are configured and saved in the Virtualdisplay portal. The client library exposes an API to toggle their visibility.
Toggling annotations
client.annotations.setEnabled(false); // Hide the markers
client.annotations.setEnabled(true); // Show them againIn an app that shows several models, this toggles the first model's markers.
viewerSettings.annotations (see below) and the marker button in the standard
interface govern every model's.
Personalisation
A print zone is a material the 3D artist named in the model, such as logo.
setImage shows a picture the Shopper chose on it, fitted without stretching;
clear brings back the zone's own texture. The picture stays in the browser
and is never uploaded.
input.addEventListener('change', async () => {
const file = input.files?.[0];
if (file === undefined) return;
try {
await client.personalisation.setImage('logo', file);
} catch (error) {
console.error(error.message); // PERSONALISATION_FAILED
}
});
await client.personalisation.clear('logo');Each call resolves once the model shows the result. A call rejects when the zone is not on the model, when the file is not a picture, and when a later call on the same zone replaces it before it shows.
zones lists every material of the model with its own texture, each a zone a
picture can go on, with its real size in millimetres; pick yours by name.
onZones calls back each time the viewer reports them. place moves and scales
the picture on a zone: x and y are the picture's centre and scale its width,
as fractions of the zone measured from its top left. Calls for one zone within
one animation frame collapse into the last, so call it on every pointer move.
A zone that shows no picture yet drops the placement, so call place once
setImage has resolved.
editing: true draws the zone's outline while the Shopper edits. The Placement
and ZoneSize types are exported.
client.personalisation.onZones((zones) => {
// [{ name: 'logo', aspect: 2.95, widthMm: 73.2, heightMm: 24.8 }]
});
client.personalisation.place('logo', { x: 0.5, y: 0.4, scale: 0.6, editing: true });Standard interface
The client renders a complete viewer UI automatically: loading indicator, attribute controls, camera controls, and an action bar with AR, fullscreen, and screenshot buttons. Each element is shown or hidden based on viewer settings configured in the Virtualdisplay portal.
Available settings
| Field | Type | Effect when false |
| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ar | boolean | Hides the AR button |
| fullscreen | boolean | Hides the fullscreen button |
| screenshot | boolean | Hides the screenshot button |
| cameraControls | boolean | Hides the camera control buttons |
| annotations | boolean | Hides all annotation markers |
| language | string | Sets the viewer UI language (BCP 47, e.g. 'nl', 'en', 'de') |
| configuratorLayout | string | Where the attribute controls sit, or whether they show: 'inframe-bottom-left' (default), 'sidebar-right' (a docked, scrollable right-hand panel), or 'hidden' (no built-in selector, client.select() and client.onChange() keep working). |
Overriding settings
The portal is the recommended place to change these settings: one source of truth, and the viewer behaves the same wherever it is embedded.
We know there are situations where the portal alone cannot cover the case at
hand. For those, ClientOptions.viewerSettings accepts a partial override of
the same fields. Use it sparingly: every override is one more place where
the embedded viewer disagrees with the portal. Omitted fields fall back to
the metadata value.
Any override that differs from the metadata is logged with console.warn.
The warning is always emitted, so the deviation stays traceable when
something needs explaining.
const client = new VirtualdisplayClient({
parent: '#product-container',
license: 'your-license-key',
model: 'sneaker',
viewerSettings: {
cameraControls: false,
},
});Lifecycle
Ready state
Use onReady to know when the model and attribute definitions are available.
Not required before calling select() or onChange(), those are buffered
automatically.
client.onReady(() => {
const values = client.getValues('Color');
console.log(
'Available colours:',
values.map((v) => v.value)
);
});Cleanup
client.destroy();Constructor options
import type { ViewerSettings } from '@virtualdisplay.io/client';
interface ClientOptions {
parent: string | HTMLElement; // Where to embed the 3D viewer
app?: string; // An app's link key: the alternative to license + model (see Mounting a specific app)
license: string; // License key from your Virtualdisplay account; with model, the classic address form
model: string; // Which 3D model to load
debug?: boolean; // Shows console logs for troubleshooting
language?: string; // Viewer language: 'nl', 'en', or 'de'
viewerSettings?: Partial<ViewerSettings>; // Override fields from model metadata (see Standard interface)
}One of the two address forms is required: app, or license + model. The
real type is a union that enforces this at compile time; the block above is the
flattened reference.
type ClientAddress =
| { app: string } // an app's link key
| { license: string; model: string }; // the classic address formError codes
The client throws VirtualdisplayError for known error conditions:
| Code | Meaning |
| ------------------------ | ------------------------------------------------ |
| NO_MAPPING | Attribute data not yet available from the server |
| ATTRIBUTE_NOT_FOUND | Requested attribute doesn't exist in the mapping |
| VALUE_NOT_FOUND | Requested value doesn't exist for attribute |
| PARENT_NOT_FOUND | Parent element for iframe not found |
| INVALID_PARAMETER | Invalid parameter (e.g. snapshot filename) |
| SNAPSHOT_FAILED | Server could not capture the snapshot |
| PERSONALISATION_FAILED | The picture could not be shown on the print zone |
Troubleshooting
Iframe not loading:
- Check that the parent element exists in the DOM
- Verify your license key is valid
- Ensure the model ID matches your license
Attributes not working:
- Verify attribute names match exactly (case-sensitive)
- Check that the value exists for the attribute
- Use
onMutationFailedto catch server-side errors
Changelog
See the npm version history for release notes.
