Properties

info

• Frameworks are using camelCase
• Native tools (VanillaJS, WebComponent) are using dashed-case to match HTML attributes (and use string values)

Frameworks

Property	Type	Default	Description
compositionUrl	string	🚫 Required	URL to the composition data
hideCategoriesNav	boolean	false	Hide the category-based navigation
infiniteCarrousel	boolean	false	Allow to navigate from 1st to last media (and vice versa)
permanentGallery	boolean	false	Display gallery under the carrousel
mediaLoadStrategy	"quality" "balanced" "speed"	"quality"	Strategy for loading medias.
minMediaWidth	number	0	Force minimum media width (in pixels)
maxMediaWidth	number	Infinity	Force maximum media width (in pixels)
preloadRange	number	1	Number of medias to preload before & after the viewport
autoLoad360	boolean	false	Load 360 images without having to click
categoriesFilter	string	*	Only display certain categories
extendBehavior	"full_screen" "event" "none"	full_screen	Handle extend mode
eventPrefix	string	"cc-webplayer:"	Prefix of cc-player events
demoSpin	boolean	false	Run a spin once the 360 images has been loaded
reverse360	boolean	false	Reverse the 360-degree rotation

Native

Attributes	Type	Default	Description
composition-url	string	🚫 Required	URL to the composition data
hide-categories-nav	boolean	false	Hide the category-based navigation
infinite-carrousel	boolean	false	Allow to navigate from 1st to last media (and vice versa)
permanent-gallery	boolean	false	Display gallery under the carrousel
media-load-strategy	"quality" "balanced" "speed"	"quality"	Strategy for loading medias.
min-media-width	number	0	Force minimum media width (in pixels)
max-media-width	number	Infinity	Force maximum media width (in pixels)
preload-range	number	1	Number of medias to preload before & after the viewport
auto-load360	boolean	false	Load 360 images without having to click
categories-filter	string	*	Only display certain categories
extend-behavior	"full_screen" "event" "none"	full_screen	Handle extend mode
event-prefix	string	"cc-webplayer:"	Prefix of cc-player events
demo-spin	boolean	false	Run a spin once the 360 images has been loaded
reverse360	boolean	false	Reverse the 360-degree rotation

note

Regarding the HTML, the attributes are technically all strings. But the WebComponent will handle the conversion to the correct type.

Generate composition URL

info

The composition URL could be any URL that returns a JSON object with the composition data.

In the following example, we are using a URL that is specific to the Car Cutter platform, but you can replace it with your own URL if you have a different backend.

NPM package

import { generateCompositionUrl } from "@car-cutter/your-npm-package-webplayer";

/**
 * @param {string} customerToken - The CarCutter Customer Token (computed by hasing the Customer ID with SHA-256).
 * @param {string} vin - The Vehicle Identification Number.
 * @returns {string} The URL to fetch the composition JSON.
 */
const compositionUrl = generateCompositionUrl(customerToken, vin);

<script/>

/**
 * Generates a URL for fetching the composition JSON for a given customer and vehicle.
 *
 * @param {string} customerToken - The CarCutter Customer Token (computed by hasing the Customer ID with SHA-256).
 * @param {string} vin - The Vehicle Identification Number.
 * @returns {string} The URL to fetch the composition JSON.
 */
export function generateCompositionUrl(
  customerToken: string,
  vin: string
): string {
  return `https://cdn.car-cutter.com/gallery/${customerToken}/${vin}/composition_v3.json`;
}

note

In order to keep your Customer ID secret, we are using the Customer Token and not the Customer ID. Make sure to not include the Customer ID in your frontend code.

Categories Filter

The categoriesFilter property allows you to filter which categories should be displayed in the WebPlayer. It supports wildcards (*) and multiple patterns separated by a vertical pipe (|).

Exact match

// Only show categories named exactly "exterior" or "interior"
<WebPlayer categoriesFilter="exterior|interior" />

With wildcard

// Show all categories ending with "rior" (e.g., "exterior", "interior")
<WebPlayer categoriesFilter="*rior" />

// Show categories starting with "360" and categories named "detail"
<WebPlayer categoriesFilter="360*|detail" />

info

When categoriesFilter is not specified, it defaults to "*" which shows all categories.

Extend Behavior

The extendBehavior property controls how the WebPlayer reacts when its extend button is clicked.

• "full_screen": Uses the browser's Full Screen API when entering extend mode
• "event": Triggers an event when extend mode is requested
• "none": Hide the extend button and disable extend mode functionality

tip

When using "event" behavior, you can handle the extend mode in your own application using the onExtendModeOn callback (in React) or by listening to the extendModeOn event (in vanilla JavaScript).