@autoviz/sdk

React component for AutoViz SDK with automatic script loading. No need to manually add script tags to your HTML.

Installation

npm install @autoviz/sdk
# or
yarn add @autoviz/sdk
# or
pnpm add @autoviz/sdk

Quick Start

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

function ProductPage() {
  return (
    <AutoViz 
      tool="configurator" 
      partId="12345"
      theme="dark"
    >
      <button className="customize-btn">
        Customize Product
      </button>
    </AutoViz>
  );
}

Features

• ✅ Automatic SDK Loading - No need to manually add script tags
• ✅ TypeScript Support - Full type definitions included
• ✅ React Integration - Native React component with proper ref forwarding
• ✅ Environment Support - Dev, staging, and production environments
• ✅ All SDK Features - Supports all AutoViz SDK data attributes as props
• ✅ Same Codebase - Uses the exact same SDK code deployed to CDN

Props

Core Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | tool | 'viewer' \| 'configurator' \| 'sims' \| 'arto' \| 'catalog' | 'configurator' | Tool to launch | | partId | string \| number | - | AutoViz part ID | | variantId | string \| number | - | Specific variant ID | | displayMode | 'modal' \| 'fullscreen' \| 'fillparent' | - | Display mode | | fullscreenAvoid | string | - | CSS selector to avoid overlapping |

Selection Props

| Prop | Type | Description | |------|------|-------------| | group | string | Product group identifier | | selectField | string | Field name for selections | | selectCurrent | string | Current selection value |

UI Customization Props

| Prop | Type | Description | |------|------|-------------| | theme | 'light' \| 'dark' | UI theme preference | | themeToggle | string \| number | Show theme toggle button | | background | string \| number | Show background, set to 0 for transparency | | primaryColor | string | Primary UI color (hex without #) | | hideNav | string \| number | Hide navigation controls | | hideClose | string \| number | Hide close button | | configButton | string \| number | Show configurator button in viewer |

Spec Props (Configuration Data)

| Prop | Type | Description | |------|------|-------------| | spec | Spec | Pre-selected configuration data | | spec.[specName] | SpecValues | Any spec type (e.g., frontWheel, rearWheel, tire, suspension) | | spec.[specName].[key] | string \| number | Any key/value pair for the spec |

The spec prop is fully dynamic - you can pass any spec names with any key/value pairs. Common examples:

• spec.frontWheel / spec.rearWheel - Wheel specs with diameter, width, lip
• spec.tire - Tire specs with size, profile, etc.
• Any custom spec type your app supports

Environment & React Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | environment | 'dev' \| 'staging' \| 'production' | 'production' | SDK environment | | children | React.ReactNode | - | Child elements (required) | | className | string | - | Additional CSS classes |

Examples

Basic Usage

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

function BasicExample() {
  return (
    <AutoViz tool="viewer" partId="12345">
      <button>View in 3D</button>
    </AutoViz>
  );
}

Advanced Configuration

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

function AdvancedExample() {
  return (
    <AutoViz
      tool="configurator"
      partId="12345"
      variantId="67890"
      group="wheels"
      selectField="finish_name"
      selectCurrent="chrome"
      theme="dark"
      primaryColor="FF6B6B"
      hideNav="1"
      configButton="1"
      className="my-custom-class"
    >
      <div className="customize-wrapper">
        <img src="/product-image.jpg" alt="Product" />
        <button className="btn-customize">
          Customize This Product
        </button>
      </div>
    </AutoViz>
  );
}

Multiple Tools

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

function MultipleTools() {
  return (
    <div>
      <AutoViz tool="viewer" partId="12345">
        <button>View in 3D</button>
      </AutoViz>
      
      <AutoViz tool="configurator" partId="12345">
        <button>Customize</button>
      </AutoViz>
      
      <AutoViz tool="sims" partId="12345">
        <button>See in My Space</button>
      </AutoViz>
    </div>
  );
}

Development Environment

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

function DevExample() {
  return (
    <AutoViz
      tool="configurator"
      partId="12345"
      environment="dev"  // Uses dev SDK
    >
      <button>Customize (Dev)</button>
    </AutoViz>
  );
}

Pre-Selected Configuration (Spec)

Pass configuration specifications to pre-populate the app. The spec prop is fully dynamic - use any spec names with any key/value pairs:

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

function WheelConfigExample() {
  return (
    <AutoViz
      tool="configurator"
      partId="12345"
      spec={{
        frontWheel: { diameter: '22', width: '10', lip: '3' },
        rearWheel: { diameter: '22', width: '12', lip: '3' }
      }}
    >
      <button>Customize Wheels</button>
    </AutoViz>
  );
}

You can also pass dynamic values that reference URL parameters:

<AutoViz
  tool="configurator"
  spec={{
    frontWheel: {
      diameter: '?custom_diameter',  // Gets value from URL param
      width: '10',                   // Static value
      lip: '3'
    }
  }}
>
  <button>Customize</button>
</AutoViz>

Any spec type is supported - the SDK generates data-spec-* attributes dynamically:

<AutoViz
  tool="configurator"
  spec={{
    tire: { size: '305', profile: '30', rating: 'Z' },
    suspension: { height: '2', type: 'coilover' }
  }}
>
  <button>Configure</button>
</AutoViz>
// Generates: data-spec-tire="?size=305&profile=30&rating=Z"
//            data-spec-suspension="?height=2&type=coilover"

Dynamic Values

The AutoViz SDK supports dynamic values that are resolved from the current page URL:

Query Parameter Values

Use ?param_name to get values from URL query parameters:

<AutoViz 
  tool="viewer"
  partId="12345"
  selectCurrent="?finish"  // Gets value from ?finish=chrome
>
  <button>View Product</button>
</AutoViz>

Path Segment Values

Use /index to get values from URL path segments:

<AutoViz 
  tool="viewer" 
  partId="/2"  // Gets 3rd path segment from /products/wheels/12345
  group="/1"   // Gets 2nd path segment 
>
  <button>View Product</button>
</AutoViz>

TypeScript

The package includes full TypeScript definitions. All props are properly typed:

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

// Props are fully typed
const props: AutoVizProps = {
  tool: 'viewer',        // ✅ Autocomplete available
  partId: 12345,        // ✅ string | number
  theme: 'dark',        // ✅ 'light' | 'dark'  
  children: <button>View</button>
};

function TypedExample(props: AutoVizProps) {
  return <AutoViz {...props} />;
}

Migration from Manual Integration

If you're currently using manual integration with script tags, migration is simple:

Before (Manual)

<!-- In HTML head -->
<script src="https://sdk-v2.autoviz.io"></script>

<!-- In your component -->
<div
  class="autoviz"
  data-tool="configurator"
  data-part-id="12345"
  data-theme="dark"
>
  <button>Customize</button>
</div>

After (React Component)

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

function Component() {
  return (
    <AutoViz
      tool="configurator"
      partId="12345"
      theme="dark"
    >
      <button>Customize</button>
    </AutoViz>
  );
}

Manual Integration (HTML Data Attributes)

For non-React integrations, you can use HTML data attributes directly.

Spec Attributes (Query String Format)

Use data-spec-* attributes with query string format. Any spec name is supported:

<!-- Static values -->
<div
  class="autoviz"
  data-tool="configurator"
  data-spec-front-wheel="?diameter=22&width=10&lip=3"
  data-spec-rear-wheel="?diameter=22&width=12&lip=3"
>
  <button>Customize</button>
</div>

Dynamic Values from URL

Use parameter names without values to pull from the current page URL:

<!-- If page URL is: /products/wheels?diameter=24&width=12&lip=4 -->
<div
  class="autoviz"
  data-tool="configurator"
  data-spec-front-wheel="?diameter&width&lip"
>
  <button>Customize</button>
</div>

Mixed Static and Dynamic

<!-- diameter from URL, width and lip are static -->
<div
  class="autoviz"
  data-tool="configurator"
  data-spec-front-wheel="?diameter&width=10&lip=3"
>
  <button>Customize</button>
</div>

Any Spec Type

The SDK dynamically parses all data-spec-* attributes:

<div
  class="autoviz"
  data-tool="configurator"
  data-spec-tire="?size=305&profile=30"
  data-spec-suspension="?height=2&type=coilover"
>
  <button>Configure</button>
</div>

Version Compatibility

This NPM package uses the exact same SDK code that's deployed to the CDN. The version numbers are synchronized, so:

• @autoviz/[email protected] uses the same code as https://sdk-v2.autoviz.io version 0.1.18
• Features and bug fixes are released simultaneously across both distribution methods
• You can migrate between manual integration and React component without any functionality changes

License

MIT