Product Configurator

Quick Start

Copy index.html, assets/style.css, assets/script.js and assets/img/speaker-poster.webp into your project. Open through a web server; ES modules need HTTP(S).

In the document head, retain the synchronous WebGL probe and eight-second fallback timeout from index.html, load the stylesheet, and include this import map before any three.js import:

Code snippet omitted: it ships with the download.

At the end of the body, load GSAP and the three.js module bridge:

Code snippet omitted: it ships with the download.

Use the complete error-handling bridge from index.html in production. It reveals the poster when a required module fails. The script automatically mounts every connected [data-configurator] root. The included markup supplies all controls, their labels and accessible defaults.

Already using three.js? Reuse the host's three.js namespace and RoomEnvironment constructor instead of importing a second copy. Assign them before loading the classic effect script. Keep the core and addon versions aligned.

Using It With Your Own Design

Markup contract. A [data-configurator] root contains one [data-viewer]. Keep the viewer keyboard-focusable with an accessible instruction label. Its [data-fallback] contains a product poster and useful description. The optional controls are [data-finish-option="name"], [data-grille-toggle], [data-feature="name"] and [data-reset]. Use native buttons; aria-pressed communicates selection. [data-finish-label], [data-grille-label], [data-feature-title], [data-feature-copy] and [data-status] receive text updates. Control hooks are scoped to their own instance.

Styling you can replace. The product wordmark, typography, panel layout, swatch appearance and neutral palette are demonstration styling. They can all change without changing the viewer. The buttons do not need the supplied visual classes.

CSS that matters. Give the root and viewer explicit, nonzero dimensions. Keep the viewer positioned, its canvas filling the viewer, touch-action: pan-y for horizontal swipes with page scrolling, and the root's clipping. Keep the fallback visible by default, hidden under .gl .fallback or .is-live .fallback only. The synchronous probe prevents a poster-to-canvas flash; the timeout restores the poster if loading stalls. Retain visible keyboard focus. The demo's data-vault-badge-pad is only needed in Vault previews.

Your product geometry. The createSpeaker(THREE, markDirty) factory is isolated at the start of assets/script.js. Replace it or pass a createModel adapter to mount(). This requires three.js development; there is no automatic model-file importer. The adapter returns:

• group: the THREE.Group the viewer rotates and frames. Center your object at its origin and size it to approximately 1.5 × 2.4 × 1.2 scene units, or adapt the viewer's camera/framing values.
• setFinish(name, duration): update the object's materials, calling markDirty() as they change. A duration of zero must apply the final state immediately.
• setGrille(open, duration): articulate a removable part in the group's local space. It therefore follows subsequent object rotation. This hook can represent another removable cover.
• dispose(): release all geometries, materials and textures owned by the adapter.

options.finishes supplies name-keyed records with a name label. The model owns what each finish actually changes. options.features supplies name-keyed { title, copy, x, y, open } records; x/y are rotation angles in radians and open selects the removable-part state. Adapt the finish buttons and feature hooks to those names. Keep example feature claims accurate for the product you display.

Options

There is no idle spin, autoplay or autonomous drift. GPU rendering runs only when a visible object has changed.

Accessibility

Native finish, feature, grille and reset buttons support keyboard activation and expose their pressed state. Tab to the viewer and use Left/Right to rotate, Up/Down to tilt and Home to restore the neutral view. Pointer dragging is direct; release momentum can always be interrupted with another drag. Horizontal touch swipes rotate the same assembly while vertical gestures can scroll the containing page.

Reduced motion retains the real 3D viewer and all its useful controls. Finish, feature and grille choices apply immediately, with no release inertia. Changes to the system preference preserve the current finish, angle, grille state and feature. Arrow-key rotation is immediate in either preference.

Without JavaScript, WebGL2 or a required CDN dependency, a rendered poster of the same speaker remains visible with a short description. Configuration controls remain visibly disabled because this fallback is a static view. Context loss also reveals the poster; restoration resumes the renderer.

Dependencies

No Lenis, external 3D model, model loader or paid texture library is required. Keep the supplied GSAP and three.js licensing notices when packaging dependencies.

Browser Support

Use a browser with WebGL2, ES modules, import maps, Pointer Events, ResizeObserver and IntersectionObserver. Unsupported or disabled WebGL receives the poster. Serve through HTTP(S), not a local file: URL.

Performance

The first performance lever is data-pixel-ratio="1", especially for larger embeds. The scene redraws only when input, transitions or resizing changes it; offscreen and background-tab rendering is skipped. Textures are procedural and generated once per mounted scene. The camera is resized from the viewer itself, so a container resize works without a window resize. Check your final model and texture budget on real mobile hardware; the included touch checks use an emulated phone.

Assets

All speaker geometry, wood grain and grille fabric are created by the included source. assets/img/speaker-poster.webp is a captured render of that model, with its source and provenance in assets/img-src/ and assets/img-manifest.json. There are no stock photos or generative image assets. Replace the poster when replacing the model. thumbnail.html is a build-only frozen presentation of the same model and controls, not a separate implementation.