Events

The WebPlayer component provides various events that you can listen to or handle via callback props. These events allow you to respond to different states and actions within the WebPlayer.

Event Handling Options

There are two main ways to handle WebPlayer events:

1. Using callback props on the WebPlayer component when using frameworks
2. Adding event listeners directly (vanilla JavaScript)

The table below lists all available events, their types, and descriptions. An example of how to use these events is provided below each table.

React/Next

Event	Type	Description
onCompositionLoading	(url: string) => void	Triggered when the composition is loading.
onCompositionLoaded	(composition: Composition) => void	Triggered when the composition has successfully loaded.
onCompositionLoadError	(error: unknown) => void	Triggered when there is an error loading the composition.
onItemChange	(props: { index: number; item: Item }) => void	Triggered when there is on a carrousel focus changed.
onExtendModeOn	() => void	Triggered when the extend mode is turned on.
onExtendModeOff	() => void	Triggered when the extend mode is turned off.
onHotspotsOn	() => void	Triggered when hotspots are turned on.
onHotspotsOff	() => void	Triggered when hotspots are turned off.
onGalleryOpen	() => void	Triggered when the gallery is opened.
onGalleryClose	() => void	Triggered when the gallery is closed.

Example

<WebPlayer
  ...
  onCompositionLoaded={composition => console.log("Composition loaded !", composition)}
>

Vue

Event	Type	Description
@compositionLoading	(url: string) => void	Triggered when the composition is loading.
@compositionLoaded	(composition: Composition) => void	Triggered when the composition has successfully loaded.
@compositionLoadError	(error: unknown) => void	Triggered when there is an error loading the composition.
@itemChange	(props: { index: number; item: Item }) => void	Triggered when there is on a carrousel focus changed.
@extendModeOn	() => void	Triggered when the extend mode is turned on.
@extendModeOff	() => void	Triggered when the extend mode is turned off.
@hotspotsOn	() => void	Triggered when hotspots are turned on.
@hotspotsOff	() => void	Triggered when hotspots are turned off.
@galleryOpen	() => void	Triggered when the gallery is opened.
@galleryClose	() => void	Triggered when the gallery is closed.

Example

<WebPlayer
  ...
  @compositionLoaded="
    composition => console.log('Composition loaded', composition)
  "
>

Native

Event	Type	Description
EVENT_COMPOSITION_LOADING	(url: string) => void	Triggered when the composition is loading.
EVENT_COMPOSITION_LOADED	(composition: Composition) => void	Triggered when the composition has successfully loaded.
EVENT_COMPOSITION_LOAD_ERROR	(error: unknown) => void	Triggered when there is an error loading the composition.
EVENT_ITEM_CHANGE	(props: { index: number; item: Item }) => void	Triggered when there is on a carrousel focus changed.
EVENT_EXTEND_MODE_ON	() => void	Triggered when the extend mode is turned on.
EVENT_EXTEND_MODE_OFF	() => void	Triggered when the extend mode is turned off.
EVENT_HOTSPOTS_ON	() => void	Triggered when hotspots are turned on.
EVENT_HOTSPOTS_OFF	() => void	Triggered when hotspots are turned off.
EVENT_GALLERY_OPEN	() => void	Triggered when the gallery is opened.
EVENT_GALLERY_CLOSE	() => void	Triggered when the gallery is closed.

Example

import { DEFAULT_EVENT_PREFIX, EVENT_COMPOSITION_LOADING } from "@car-cutter/native-webplayer";

document.addEventListener(DEFAULT_EVENT_PREFIX + EVENT_COMPOSITION_LOADING, (event) => {
  console.log("Composition loaded", event.detail);
});

info

• The default prefix for all WebPlayer events is "cc-webplayer:". This prefix helps to avoid potential conflicts with other events in your application. You can access it through the constant DEFAULT_EVENT_PREFIX
• You can customize the event prefix by setting the eventPrefix property on the WebPlayer component.