Skip to main content

Accessing the Visual API

While the Visual Component is designed to remove the need for using the Visual API directly when displaying a 3D product on your site, it still allows access to the Visual instance under the hood to give you greater control over your 3D products when needed.

When using the Visual Component, you can access the Visual API via the visual class on the atlatl-visual element.

<atlatl-visual client-id="a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5">
    <av-product namespace="my_namespace" name="my_product_name"></av-product>
</atlatl-visual>
// The Visual Component
const visualComponent = document.querySelector('atlatl-visual')

// The Visual instance on the Visual Component
const visual = visualComponent.visual
info

All properties and methods available on the Visual instance can be found in the API Reference.

Accessing properties and methods on the Visual instance​

Depending on your UI’s needs, it may useful to access certain properties when using the Visual Component.

Example 1: Getting the canvas element​

A common example is accessing the <canvas> element within the Visual Component to add event listeners for user interactions, such as when clicking or dragging starts.

To illustrate this, it is common to show some instructions on top of or next to the 3D product to let the user know it is interactive. However, those instructions may no longer be needed once the user begins to interact with it. In the example below, the page initially shows those instructions next to the Visual Component, then hides them once the user clicks or drags on the 3D product.

<atlatl-visual client-id="a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5">
    <av-product namespace="my_namespace" name="my_product_name"></av-product>
</atlatl-visual>
<p id="instructions">Click or drag the 3D product to rotate it.</p>
// The Visual Component
const visualComponent = document.querySelector('atlatl-visual')

// The canvas element within the Visual Component
const canvas = visualComponent.visual.canvasElement

// Listen for when the user clicks or drags on the canvas, then hide the instructions
canvas.addEventListener('pointerdown', () => {
    document.getElementById('instructions').style.display = 'none'
})

Example 2: Destroying the Visual instance​

For sites that need to dynamically load and destroy multiple instances on the same page, such as SPAs built with React or Vue, destroying the Visual instance before initializing a new one is critical.

This can be accomplished by awaiting visual.destroy() on the Visual instance.

// The Visual Component
const visualComponent = document.querySelector('atlatl-visual')

async function destroyTheVisualInstance() {
    // The Visual instance on the Visual Component
    const visual = visualComponent.visual

    // Destroy the Visual instance
    await visual.destroy()

    console.log('The Visual instance has been destroyed. It is now safe to initialize a new one!')

    // visual.destroyed will be true once .destroy() has resolved
    console.log(visual.destroyed) // true
}

Full code example​

scripts.js
// Hide the custom loading screen once the page loads and Dopple Visual is ready
window.addEventListener('load', async () => {
    // The Visual Component
    const visualComponent = document.querySelector('atlatl-visual')
    await atlatlVisual.ready()

    // The canvas element within the Visual Component
    const canvas = visualComponent.visual.canvasElement

    // Listen for when the user clicks or drags on the canvas, then hide the instructions
    canvas.addEventListener('pointerdown', () => {
        document.getElementById('instructions').style.display = 'none'
    })
})