@vizor-vr/react

React wrappers for the Vizor VR player. Type-safe components with native event props.

Install

npm install @vizor-vr/react @vizor-vr/player

Usage

import { VzVideo } from '@vizor-vr/react';

export function Player() {
  return (
    <VzVideo src="video.mp4" format="MONO_360" autoplay onReady={() => console.log('ready')} />
  );
}

Components

VzVideo, VzImg, VzTour, VzCinema, VzLive, VzPlaylist, VzAnnotation, VzCaption.

VzAnnotation renders a <vz-annotation> child (props: lat, lon, title, icon, timeStart, timeEnd, sortOrder, plus children as popup content). VzCaption renders a subtitle <track> (props: src, srclang, label, default).

SSR

The wrappers import @vizor-vr/player/register as a side effect, which registers the underlying custom elements. Registration no-ops when there is no DOM, so importing the package is safe on the server — but the player itself only runs in the browser. In Next.js App Router or other RSC setups, render the components from a Client Component ('use client').

Props

Props are camelCase and are reflected to the underlying element's kebab-case attributes:

| Prop | Element attribute | Type | | ------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------- | | src | src | string | | format | format | VzFormat \| string | | title | title | string | | poster | poster | string | | loop / muted | loop / muted | boolean | | preload | preload | 'auto' \| 'metadata' \| 'none' | | apiKey | api-key | string | | licenseKey | license-key | string | | apiEndpoint | api-endpoint | string | | contentId | content-id | string | | controlsBehavior | controls-behavior | 'autohide' \| 'always' \| 'minimal' | | hideControls | hide-controls | boolean | | primaryColor | primary-color | string | | lensAngle | lens-angle | number | | collabServer / collabRoom / collabRole / collabUserId / collabDisplayName / collabPassword | collab-* | string | | className / style | class / inline style | string / React.CSSProperties | | sources | <source> children | { src, type?, quality? }[] |

VzPlaylist takes its own props: autoplay (auto-advance), loopPlaylist, panel ('none' \| 'expandable'), onPlaylistChange, onPlaylistEnd.

Event props

Each handler prop listens for a DOM event on the element; detail-carrying events pass event.detail directly to your handler:

| Prop | DOM event | Handler argument | | ---------------------------------------- | -------------------------------------------- | --------------------------------- | | onReady | vz-ready | — | | onPlay / onPause / onEnded | play / pause / ended | — | | onTimeUpdate | timeupdate | Event | | onError | vz-error | { code, message } | | onQualityChange | vz-quality-change | { quality, auto } | | onFullscreenEnter / onFullscreenExit | vz-fullscreen-enter / vz-fullscreen-exit | — | | onXrSessionStart / onXrSessionEnd | vz-xr-enter / vz-xr-exit | — | | onLicenseValidated | vz-license | { valid, tier, message? } | | onChapterChange | vz-chapter-change | { chapterId, title, startTime } | | onTourNavigate | vz-tour-navigate | { fromProbeId, toProbeId } | | onHubSelect | vz-hub-select | { id, src, title, index } | | onSceneClick | vz-scene-click | { lat, lon } |

Handler payload types come from VzEventDetailMap in @vizor-vr/shared, so detail shapes stay in sync with the player.

Note: onXrSessionStart / onXrSessionEnd / onLicenseValidated keep their prop names but listen for the events the player actually emits (vz-xr-enter / vz-xr-exit / vz-license). Earlier versions listened for vz-xr-session-start / vz-xr-session-end / vz-license-validated, which the player never emits, so these props never fired. The former onAnnotationClick, onOrientationChange, and onCaptionChange props were removed for the same reason — the player emits no vz-annotation-click, vz-orientation-change, or vz-caption-change events.

The forwarded ref points at the underlying custom element, so imperative methods (ref.current.play(), .pause(), .seek(t)) work directly.

Documentation

Full guides and the complete attribute/event reference: docs.vizor-vr.com. Source lives in the vizor-vr monorepo on GitHub.

Security

See the monorepo security policy for how to report vulnerabilities ([email protected]).

License

MIT — see LICENSE.