AutoViz SDK Integration Guide

Overview

Create custom HTML/CSS buttons for launching AutoViz tools; SDK handles tool launching via data-params.

Quick Start

Add the AutoViz SDK script to your page:

<script src="https://sdk-v2.autoviz.io" defer></script>

The defer attribute ensures the script loads without blocking page rendering and executes after the DOM is ready.

Create an element with class="autoviz" and data attributes:

<button class="autoviz my-button-class"
        data-tool="viewer"
        data-group="super-model-series-x"
        data-select-field="finish_name"
        data-select-current="gloss-black"
        data-display-mode="fullscreen"
        data-fullscreen-avoid="#header">
  VIEW IN 3D
</button>

Style with your own CSS—the SDK won't modify your HTML.

SDK NPM Package

For React applications, you can use our NPM package instead of manually adding script tags. The NPM package provides a React component that automatically loads the SDK script and converts props to data attributes.

Installation

npm install @autoviz/sdk

Usage

import { AutoViz } from '@autoviz/sdk';

function MyComponent() {
  return (
    <AutoViz 
      tool="viewer"
      group="super-model-series-x"
      selectField="finish_name"
      selectCurrent="gloss-black"
      displayMode="fullscreen"
      fullscreenAvoid="#header"
    >
      <button className="my-button-class">
        VIEW IN 3D
      </button>
    </AutoViz>
  );
}

Features:

✅ Automatic SDK script loading
✅ TypeScript support with full type definitions
✅ All SDK data attributes available as props
✅ Works with any React framework (Next.js, Vite, etc.)

📦 View full NPM package documentation →

Data Attributes

Core Attributes

Attribute	Type	Required	Description	Example
`data-tool`	string	Yes	Tool to launch (viewer, configurator, sims, arto, catalog)	`data-tool="viewer"`
`data-part-id`	number	Optional	AutoViz part ID	`data-part-id="12345"`
`data-variant-id`	number	Optional	Specific variant ID	`data-variant-id="67890"`
`data-group`	string	Optional	Product group identifier for selections	`data-group="series-z"`
`data-select-field`	string	Optional	Field name for selections	`data-select-field="finish_name"`
`data-select-current`	string	Optional	Current selection value	`data-select-current="chrome"`

Optional UI Customization Attributes

Attribute	Type	Description	Example
`data-display-mode`	string	Optional	Display mode (modal, fullscreen, fillparent)
`data-fullscreen-avoid`	string	Optional	CSS selector to avoid overlapping
`data-theme`	string	UI theme preference	`data-theme="dark"`
`data-theme-toggle`	string	Show theme toggle button	`data-theme-toggle="0"`
`data-background`	string	Show background, set to 0 for transparency	`data-background="1"`
`data-primary-color`	string	Primary UI color (hex without #)	`data-primary-color="FF0000"`
`data-hide-nav`	string	Hide navigation controls	`data-hide-nav="1"`
`data-hide-close`	string	Hide close button	`data-hide-close="1"`
`data-config-button`	string	Show configurator button in viewer	`data-config-button="1"`

Part Specification Attributes [beta]

Use data-spec-{name} attributes to pass wheel sizing and fitment data. See Part Specification for full documentation.

<button class="autoviz"
        data-tool="configurator"
        data-spec-front-wheel="?diameter=22&width=10&offset=25"
        data-spec-rear-wheel="?diameter=22&width=12&offset=30">
  Configure Wheels
</button>

Setting specific data-part-id and/or data-variant-id takes precedence over data-group and data-select- selections.

Valid Tool Values

Tool Value	Description
`viewer`	3D Viewer
`configurator`	Configurator
`sims`	See In My Space
`arto`	AR Try-On
`catalog`	Catalog browser

Valid Mode Values

Mode	Description
`modal`	Opens in modal dialog (default)
`fullscreen`	Opens in fullscreen overlay
`fillparent`	Fills parent container

Preventing Button Flash (FOUC)

The SDK validates that 3D models exist before showing buttons. To prevent buttons from flashing before validation completes, pre-hide them using one of these methods.

Important: The SDK uses visibility and opacity for showing/hiding, not display. Do not use display: none as the SDK cannot override it.

Method 1: CSS Rule (Recommended)

Hide .autoviz elements using visibility which the SDK can override:

<style>
  .autoviz {
    visibility: hidden;
    opacity: 0;
  }
  /* SDK adds autoviz-visible class which overrides these */
</style>

Method 2: Inline Style

Add inline visibility styles:

<button class="autoviz my-button"
        style="visibility: hidden; opacity: 0;"
        data-tool="viewer"
        data-group="my-wheel">
  View in 3D
</button>

Method 3: SDK Hidden Class

Use the SDK's built-in hidden class:

<button class="autoviz autoviz-hidden my-button"
        data-tool="viewer"
        data-group="my-wheel">
  View in 3D
</button>

SDK Visibility Classes:

Class	Description
`autoviz-hidden`	Element is hidden (height: 0, opacity: 0, visibility: hidden)
`autoviz-visible`	Element is visible (opacity: 1, visibility: visible)
`autoviz-disabled`	Element is dimmed and non-interactive

Do NOT use:

/* This will NOT work - SDK cannot override display */
.autoviz { display: none; }

Complete Examples

Example 1: Minimal Button

<button class="autoviz my-button-class"
        data-tool="viewer">
  View in 3D
</button>

Example 2: Product Configuration

<div class="autoviz my-custom-class"
     data-tool="viewer"
     data-group="series-z" 
     data-select-field="finish_name"
     data-select-current="chrome"
     data-display-mode="fullscreen"
     data-fullscreen-avoid=".site-header">
  <img src="wheel-thumb.jpg" alt="Configure Wheel">
  <span>Customize Your Wheel</span>
</div>

Example 3: Customized UI

<button class="autoviz my-button"
        data-tool="viewer"
        data-group="wheels"
        data-theme="dark"
        data-primary-color="FF6B6B"
        data-hide-nav="1"
        data-config-button="1">
  View in 3D
</button>

Dynamic Value Resolution

You can use dynamic values in data attributes that are resolved from the current page URL:

Query Parameter Values (?)

Use ?param_name to get values from URL query parameters:

<!-- URL: https://example.com/wheels?finish=chrome&color=red -->
<button data-select-current="?finish">View</button>
<!-- Resolves to: data-select-current="chrome" -->

<button data-theme="?theme">View</button>  
<!-- If ?theme=dark in URL, resolves to: data-theme="dark" -->

Path Segment Values (/)

Use /index to get values from URL path segments (0-based index):

<!-- URL: https://example.com/wheels/series-a/finish-1 -->
<button data-group="/1">View</button>
<!-- Resolves to: data-group="series-a" -->

<button data-select-current="/2">View</button>
<!-- Resolves to: data-select-current="finish-1" -->

Supported Attributes

Dynamic values work with these attributes:

data-group
data-part-id
data-variant-id
data-select-current
data-select-field
data-spec-* (see Part Specification)

Examples

<!-- URL: https://mystore.com/products/wheels/12345?finish=chrome&size=20 -->

<!-- Query param resolution -->
<button data-select-current="?finish">View</button>
<!-- Result: data-select-current="chrome" -->

<!-- Path segment resolution -->  
<button data-group="/1">View</button>
<!-- Result: data-group="wheels" -->

<button data-part-id="/2">View</button>
<!-- Result: data-part-id="12345" -->

Overview​

Quick Start​

SDK NPM Package​

Installation​

Usage​

Data Attributes​

Core Attributes​

Optional UI Customization Attributes​

Part Specification Attributes [beta]​

Valid Tool Values​

Valid Mode Values​

Preventing Button Flash (FOUC)​

Method 1: CSS Rule (Recommended)​

Method 2: Inline Style​

Method 3: SDK Hidden Class​

Complete Examples​

Example 1: Minimal Button​

Example 2: Product Configuration​

Example 3: Customized UI​

Dynamic Value Resolution​

Query Parameter Values (?)​

Path Segment Values (/)​

Supported Attributes​

Examples​