Skip to content

xrgallery/viewer SDK

The @xrgallery/viewer npm package lets you embed immersive 360° VR experiences in any web application. It works with React, Vue, Angular, Svelte, Next.js, Astro, or plain HTML.

Install

npm install @xrgallery/viewer

yarn add @xrgallery/viewer

pnpm add @xrgallery/viewer

<script src="https://unpkg.com/@xrgallery/viewer/dist/viewer-bundle.iife.js"></script>

Two Modes

Scene ID Mode

Load a tour from XRGallery cloud by its ID. No config needed — the viewer fetches everything from Firestore automatically.

const viewer = await XRGallery.create({
  element: '#app',
  sceneId: 'abc123'
});

Best for tours created in the XRGallery editor.

Config Mode

Pass your own config object directly. Fully self-contained — no cloud dependency, no external calls.

const viewer = await XRGallery.create({
  element: '#app',
  config: {
    experience: { title: "My Tour" },
    stages: [
      {
        id: "lobby",
        name: "Welcome",
        skybox: { type: "image", url: "/panorama.jpg" }
      }
    ]
  }
});

Best for self-hosted tours or custom integrations.

Minimal Example

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My VR Tour</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    html, body { width: 100%; height: 100%; overflow: hidden; }
    #app { width: 100%; height: 100%; }
  </style>
</head>
<body>
  <div id="app"></div>
  <script src="https://unpkg.com/@xrgallery/viewer/dist/viewer-bundle.iife.js"></script>
  <script>
    XRGallery.create({
      element: '#app',
      config: {
        experience: { title: "Quick Demo" },
        stages: [{
          id: "main",
          name: "Main",
          skybox: { type: "image", url: "https://example.com/panorama.jpg" }
        }]
      }
    });
  </script>
</body>
</html>

Lifecycle

XRGallery.create() returns a Promise<ViewerInstance>. Use dispose() to clean up when you're done:

const viewer = await XRGallery.create({ element: '#app', sceneId: 'abc123' });

// Later — tear down the viewer
viewer.dispose();

// Check if already disposed
console.log(viewer.isDisposed()); // true

This is especially important in single-page apps (React, Vue, etc.) where components mount and unmount.

What's in the Bundle

The IIFE bundle (~3.3 MB gzipped) is fully self-contained:

  • Babylon.js 3D engine
  • HLS.js for video streaming
  • All UI components and controls
  • WebXR/VR support
  • Audio engine (spatial audio)

No additional runtime dependencies.

Next Steps