<viewer-3dvue> is a native Web Component. No dependencies, no framework required. It works anywhere you can paste HTML — a Liquid section, theme.liquid, or a product template.
<!-- In <head> or before </body> --> <script src="https://cdn.jsdelivr.net/gh/3dvue/api@v4/viewer-3dvue-min.js"></script>
<viewer-3dvue name="monViewer" src="https://app.3dvue.fr/view?p=AB01-CD02" ></viewer-3dvue> <!-- That's it. -->
A native Web Component — no React, Vue, or bundler required. Works in any environment that accepts HTML.
Add the script to your theme.liquid, inside <head> or just before </body>. One inclusion covers all your product pages.
src attribute on the <viewer-3dvue> component is the URL specific to your configurator — provided by 3DVue when your project is delivered.
<script src="https://cdn.jsdelivr.net/gh/3dvue/api@v4/viewer-3dvue-min.js"></script>
Paste the <viewer-3dvue> tag wherever you want to display the configurator — in your Liquid product section, a custom block, or a dedicated section. Two attributes are required: name (unique identifier) and src (your configurator URL).
name is used to target this viewer from HTML buttons or the JS API. Use a unique identifier per page if you have multiple viewers.
<!-- Required attributes --> <viewer-3dvue name="monViewer" src="https://app.3dvue.fr/view?p=AB01-CD02" ></viewer-3dvue> <!-- Optional: enables console logs --> <viewer-3dvue name="monViewer" src="https://app.3dvue.fr/view?p=AB01-CD02" debug ></viewer-3dvue>
Add viewer-3dvue attributes on your existing buttons or selects to trigger material changes. No JavaScript to write — the component automatically listens to click and change events.
<!-- Button that changes fabric on click --> <button viewer-3dvue="monViewer" viewer-3dvue-clic="setMaterial" viewer-3dvue-meshs-materials='{"1":"0n","2":"1a"}' > Midnight Blue </button> <!-- Select that changes colour --> <select viewer-3dvue="monViewer" viewer-3dvue-change="setMaterial" viewer-3dvue-mesh="2,4" > <option value="0n">Red</option> <option value="1a">Blue</option> <option value="2b">Green</option> </select>
The component automatically listens to click and change events on any element carrying the right attributes. Ideal for hooking into your existing Shopify swatches.
<button viewer-3dvue="monViewer" viewer-3dvue-clic="setMaterial" viewer-3dvue-meshs-materials='{"1":"0n","3":"2b","5":"1c"}' > Natural wood theme </button> // {"meshIndex": "materialId"} // Index 0 is reserved — starts at 1
viewer-3dvue-mesh.<select viewer-3dvue="monViewer" viewer-3dvue-change="setMaterial" viewer-3dvue-mesh="2,4" > <option value="0n">Red</option> <option value="1a">Blue</option> </select> // viewer-3dvue-mesh="2,4" // applies to mesh 2 AND mesh 4
When you need programmatic control — dynamic model loading, image capture, SVG export. All methods check that the viewer is ready before executing.
const viewer = document.querySelector('viewer-3dvue[name="monViewer"]'); // All methods check that the viewer is loaded (LOAD_COMPLETE) // If not ready → console warning, call ignored
// On object 0 (default) viewer.setMaterial({ "1": "0n", "3": "2b" }); // On a specific object (multi-segment) viewer.setMaterial({ "1": "1a" }, 1); // setMaterial(materialList, objectIndex = 0)
// Load a new model (replaces current) viewer.loadModel("AB01-CD02"); // Add a segment to the existing model viewer.addModel("EF03"); viewer.addModel("EF03-GH04"); // Remove a segment by its index viewer.removeModel(1); // ⚠ Cannot remove the last remaining segment
viewer.captureToBase64(); viewer.addEventListener("onCaptureBase64Complete", (e) => { const { base64, error } = e.detail; if (error) { console.error(error); return; } // base64 = "data:image/png;base64,..." document.querySelector("#preview").src = base64; });
// Returns camera to its initial position viewer.resetCamera(); // Manual pause (saves GPU) viewer.pauseRenderer(); viewer.startRenderer(); // ℹ These methods are managed automatically // when the component leaves/enters the viewport
The SVG API lets you add text and images directly onto the 3D product via dropzones defined in the model. Used for customisable products — marking, text engraving, client logo upload.
| Method | Description |
|---|---|
addSVGText(text, opts) |
Adds text to a dropzone. Options: fill, fontFamily, selectable |
addSVGImage(source, opts) |
Adds an image (File or ArrayBuffer) to a dropzone. Zero-copy via Transferable Objects. |
setSVGElementParam(param, value, id) |
Modifies a parameter of an existing SVG element. id=null targets the selected element. |
exportSVG() |
Generates the SVG file of the configured product — print-ready proof. |
// 1. Add text onto the product viewer.addSVGText("My text", { fill: "#ffffff", fontFamily: "Arial", dropzone: "dropzone001", selectable: true }); // 2. Upload logo from a file input const file = input.files[0]; await viewer.addSVGImage(file, { dropzone: "dropzone001" }); // 3. Export the SVG proof viewer.exportSVG(); viewer.addEventListener("onSVGExportComplete", (e) => { const { path, error } = e.detail; // path = URL of the generated SVG file });
API reference, HTML attributes, events, Shopify Liquid examples. Everything is documented and kept up to date.
View documentationNo automated ticketing. You speak directly with Matthieu, the developer who designed the API. Response within 24 hours.
Book a callTest the configurator in real conditions before integrating. See exactly what your customers will see on your store.
View demoYou manage the code on the Shopify side, we handle everything else — modelling, materials, configuration. In 30 minutes, we'll show you what we can do with your catalogue.