@vizor-vr/svelte

Svelte 5 wrappers for the Vizor VR player. Type-safe components using runes.

Install

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

Usage

Event handlers are Svelte 5 callback props (onready={...}), not on: directives:

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

<VzVideo src="video.mp4" format="MONO_360" autoplay onready={() => console.log('ready')} />

Components

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

The underlying event-listener action is exported for advanced usage: vizorEvents (with the VizorEventHandlers type), usable directly on a raw element: <vz-video use:vizorEvents={{ onready }} />.

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 SvelteKit SSR, guard rendering with {#if browser} (from $app/environment).

Props

Props are camelCase and are bound to the underlying element's kebab-case attributes. Unrecognized props are spread onto the element as 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 | | style / class | inline style / class | string |

Event handler 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 } | | onplaylistchange (VzPlaylist) | vz-playlist-change | { index, title, total } | | onplaylistend (VzPlaylist) | vz-playlist-end | — |

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.

Components also export imperative methods: getElement(), play(), pause(), and seek(time).

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.