@vizor-vr/vue

Vue 3 wrappers for the Vizor VR player. Type-safe components with native event emits.

Install

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

Usage

<script setup lang="ts">
import { VzVideo } from '@vizor-vr/vue';
</script>

<template>
  <VzVideo src="video.mp4" format="MONO_360" autoplay @ready="onReady" />
</template>

Components

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

Composables and prop/emit definitions are exported for advanced usage: useVizorEvents, useVizorRef, vizorProps, vizorImgProps, vizorEmits.

SSR

The wrappers import @vizor-vr/player/register as a side effect, which registers the underlying custom elements. Registration no-ops on the server, so importing is SSR-safe — but the player itself needs the browser DOM. Under Nuxt/SSR, render inside <ClientOnly> (or a client-only component).

Props

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

| Prop | Element attribute | Type | | ------------------------------------------------------------------------------------------------------ | ------------------- | ------------------------------------- | | src | src | string | | format | format | 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 |

VzImg omits the playback-only props (loop, muted, preload).

Events

Each Vue emit maps to a DOM event on the element; events with a detail payload emit that payload:

| Vue event | DOM event | Payload | | ---------------------------------------- | -------------------------------------------- | --------------------------------- | | @ready | vz-ready | — | | @play / @pause / @ended | play / pause / ended | — | | @timeupdate | timeupdate | Event | | @error | vz-error | { code, message } | | @quality-change | vz-quality-change | { quality, auto } | | @fullscreen-enter / @fullscreen-exit | vz-fullscreen-enter / vz-fullscreen-exit | — | | @xr-session-start / @xr-session-end | vz-xr-enter / vz-xr-exit | — | | @license-validated | vz-license | { valid, tier, message? } | | @chapter-change | vz-chapter-change | { chapterId, title, startTime } | | @tour-navigate | vz-tour-navigate | { fromProbeId, toProbeId } | | @hub-select | vz-hub-select | { id, src, title, index } | | @scene-click | vz-scene-click | { lat, lon } |

VzPlaylist additionally emits @playlist-change ({ index, title, total }) and @playlist-end. Payload types are exported as VizorEmitPayloads, sourced from VzEventDetailMap in @vizor-vr/shared, so payload shapes stay in sync with the player.

Note: @xr-session-start / @xr-session-end / @license-validated keep their emit names but are fired from 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 emits never fired. The former @annotation-click, @orientation-change, and @caption-change emits were removed for the same reason — the player emits no vz-annotation-click, vz-orientation-change, or vz-caption-change events.

Components expose el (the underlying custom element ref) plus play(), pause(), and seek(time) for imperative control. Attributes not covered by a declared prop (e.g. autoplay) fall through to the underlying element via Vue's standard attribute inheritance.

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.