Player SDK

The CarHub Player SDK renders an interactive 360° vehicle player directly in your page. It accepts the same report data as the legacy Carviz player, but gives you typed events, imperative controls, custom theming and framework bindings. It does not use an iframe.

Install

Install the framework-independent package:

pnpm add @carhub/player

The SDK supports modern evergreen browsers. It uses Shadow DOM, ResizeObserver, pointer events and AbortController.

Create a player

Give the player a container. It fills the container width and derives its height from the displayed media.

<div id="player" style="max-width: 960px"></div>

import { CarhubPlayer } from "@carhub/player";

const player = new CarhubPlayer("#player", {
  token: "5da89076-bdbc-47ba-9f61-a55878c06786",
  apiKey: "pk_live_…",
  tabview: "360",
});

player.on("hotspotclick", ({ damage }) => {
  console.log(damage.location, damage.type);
});

apiKey is visible to everyone who loads your page. Use only a publishable, read-only key scoped to report reads. Never place a secret API key in browser code.

Load report data

Choose one data-loading route. report takes precedence over token, and fetchReport takes precedence over the built-in request.

Option	Use when
`report`	You already have the report JSON. No request or browser credential is needed.
`fetchReport`	Your backend loads the report. This keeps credentials server-side.
`token` and `apiKey`	You use a publishable, read-only report key in the browser.

// Use a report you already fetched.
new CarhubPlayer("#player", { report });

// Load through your own backend.
new CarhubPlayer("#player", {
  token,
  fetchReport: (reportToken, signal) =>
    fetch(`/api/reports/${reportToken}`, { signal }).then((response) => response.json()),
});

You can also supply jwt for reports that require a JWT. The built-in loader sends it as X-JWT and retries anonymously if the request returns 401.

Configure the player

Pass configuration when you create the player. These defaults match the Player 360 embed contract.

Option	Type	Default	Effect
`upscaled`	`boolean`	`true`	Prefer enhanced images when available.
`upscaleToggle`	`boolean`	`true`	Show the enhanced/original image toggle.
`photomode`	`boolean`	`false`	Hide the 360° spin and show photos only.
`hotspot`	`boolean`	`true`	Show damage markers on images and 360° frames.
`sharable`	`boolean`	`true`	Show the share button.
`zoomable`	`boolean`	`true`	Enable wheel and pinch zoom in the 360° view.
`fullscreenable`	`boolean`	`true`	Enable the fullscreen image viewer.
`interior`	`boolean`	`false`	Include the interior photo tab.
`damages`	`boolean`	`true`	Include the damage gallery and damage detail cards.
`carousel`	`boolean`	`true`	Show the thumbnail carousel.
`selector`	`boolean`	`true`	Show the view selector.
`tabview`	`TabId`	`"exterior"`	Select the initial view.
`excludeTab`	`TabId[] \| string`	`[]`	Hide specified views. A comma-separated string is accepted.
`autoplay360`	`boolean`	`true`	Start the 360° spin automatically.
`color`	`string`	`null`	Accent colour. Accepts `#RGB`, `#RRGGBB` or bare hex.

The available TabId values are 360, exterior, interior, interior360, others and damages.

new CarhubPlayer("#player", {
  report,
  interior: true,
  excludeTab: ["others"],
  color: "16A34A",
});

Use iframe-compatible query parameters

Query parameters are off by default. Enable them when you want the SDK to follow the iframe embed contract. Query values then take precedence over supplied options, which take precedence over defaults.

new CarhubPlayer("#player", {
  report,
  readQueryParams: true,
});

For example, ?tabview=360&hotspot=false&excludeTab=interior,damages overrides the corresponding options.

Control the player

The instance exposes methods for navigation and playback.

player.setView("damages");
player.showSlide(2);
player.setFrame(18);
player.play();
player.pause();
player.setUpscaled(true);
player.openFullscreen();
player.closeFullscreen();
player.share();
player.setReport(nextReport);
player.destroy();

showSlide() uses one global slide list, ordered exterior, interior, interior 360°, others and damages. The player automatically switches to the matching view. Read the active state with player.currentView, player.tabs, player.frame and player.currentReport. Attach listeners immediately after creating the player. Initial events are emitted in a microtask, so the listener receives ready.

player.on("ready", ({ report, tabs }) => {
  console.log("Loaded", report, tabs);
});

player.on("viewchange", ({ view, previous }) => {
  console.log(`${previous} → ${view}`);
});

player.on("error", ({ error, phase }) => {
  console.error(phase, error);
});

Event	Payload
`ready`	`report`, `tabs`
`viewchange`	`view`, `previous`
`framechange`	`frame`, `total`
`playstatechange`	`playing`
`hotspotclick`	`hotspot`, `damage`
`slidechange`	`index`, `slide`
`fullscreenchange`	`open`, `index`
`upscalechange`	`upscaled`
`share`	`url`, `preventDefault()`
`error`	`error`, `phase` (`fetch`, `render` or `asset`)
`destroy`	No payload

on, off and once are chainable. framechange can fire about 30 times a second during autoplay, so sample it before rendering UI from it. To replace sharing entirely, prevent the default behaviour:

player.on("share", ({ url, preventDefault }) => {
  preventDefault();
  openYourShareSheet(url);
});

Use a framework binding

The core player has bindings for React, Vue and Angular. They all expose the same options and events as @carhub/player.

pnpm add @carhub/player-react
# or: @carhub/player-vue, @carhub/player-angular

import { CarhubPlayerView } from "@carhub/player-react";

<CarhubPlayerView
  token="5da89076-bdbc-47ba-9f61-a55878c06786"
  apiKey="pk_live_…"
  tabview="360"
  interior
  onHotspotclick={({ damage }) => console.log(damage.location)}
/>;

You can also use the custom element without a framework:

<script type="module" src="https://unpkg.com/@carhub/player/dist/element.js"></script>

<carhub-player
  token="5da89076-bdbc-47ba-9f61-a55878c06786"
  api-key="pk_live_…"
  tabview="360"
  autoplay360
></carhub-player>

Its attributes mirror player options in kebab case. A bare boolean attribute is true; set attribute="false" to disable it.

Theme and translate labels

Set CSS custom properties on the host element. They cross the Shadow DOM boundary.

#player {
  --chp-accent: #16a34a;
  --chp-radius: 4px;
  --chp-surface: #f8fafc;
}

Set data-theme="light" or data-theme="dark" on the host element to fix the theme. Without it, the player follows the user’s colour-scheme preference. The player humanises damage and vehicle-part keys by default. Install the optional i18n export for the complete five-language dictionary:

import { CarhubPlayer, toMessages } from "@carhub/player";
import { vehicleParts, damageTypes } from "@carhub/player/i18n";

new CarhubPlayer("#player", {
  report,
  locale: "fr",
  messages: toMessages(vehicleParts, damageTypes),
});

Add interior panoramas

RICOH THETA equirectangular images use Photo Sphere Viewer. Install its optional peer dependencies to render them as interactive panoramas:

pnpm add @photo-sphere-viewer/core @photo-sphere-viewer/gyroscope-plugin

Without these packages, a panorama falls back to a flat image.

Migrate from the iframe

Replace the iframe with a container and SDK instance. Configuration names and defaults are compatible. Enable readQueryParams if you want existing URL query parameters to continue controlling the player.

<!-- Before -->
<iframe src="https://app.carviz.com/view/{token}/360"></iframe>

<!-- After -->
<div id="player"></div>

new CarhubPlayer("#player", {
  token,
  apiKey: "pk_live_…",
  readQueryParams: true,
});

Start here

Integration guides

SDK

API reference

Install

Create a player

Load report data

Configure the player

Use iframe-compatible query parameters

Control the player

Use a framework binding

Theme and translate labels

Add interior panoramas

Migrate from the iframe

​Install

​Create a player

​Load report data

​Configure the player

​Use iframe-compatible query parameters

​Control the player

​Subscribe to events

​Use a framework binding

​Theme and translate labels

​Add interior panoramas

​Migrate from the iframe

Install

Create a player

Load report data

Configure the player

Use iframe-compatible query parameters

Control the player

Subscribe to events

Use a framework binding

Theme and translate labels

Add interior panoramas

Migrate from the iframe