360 Viewer — Website Embedding

Embed an exported panorama using a pinned public viewer package

Last updated: 2026-10-27

The optional Phong 360 Viewer web library displays exported 360° images on your own website. You do not need it to use the desktop app. For hosted sharing, use Gallery Publishing; for your own site, first export an equirectangular image.

Quick Start: Embed a Single 360° Image

This example targets published @ansonphong/360-viewer 6.0.5 and its Three.js 0.128.0 dependency. Host your panorama as a normal website asset, then add this to a page served over HTTP/HTTPS:

<link rel="stylesheet"
      href="https://unpkg.com/@ansonphong/360-viewer@6.0.5/dist/viewer.css">
<div id="panorama" style="width:100%;height:500px"></div>

<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
<script src="https://unpkg.com/@ansonphong/360-viewer@6.0.5/dist/viewer.umd.js"></script>
<script>
  const viewer = new Phong360Viewer({ container: 'panorama' });
  viewer.loadImage('/panoramas/example.jpg').catch(error => {
    console.error('Panorama could not be loaded', error);
  });
</script>

Replace the image URL with your exported JPG/PNG. The container must exist and have a nonzero height. A string container is its ID without #, not a CSS selector; a DOM element is also accepted. Load Three before the viewer bundle. In this version, the file named viewer.standalone.umd.js also expects window.THREE; its name does not remove that dependency.

The URLs are pinned so the example does not silently select a different viewer release. You can self-host the corresponding JS/CSS/dependency files instead. Test the page on your intended browser/device with a modest image before replacing it with a large delivery. Check both poles and the wrap seam.

Using a Bundler

In your own website project, install matching versions:

npm install --save-exact @ansonphong/360-viewer@6.0.5 three@0.128.0
import { Phong360Viewer } from '@ansonphong/360-viewer';
import '@ansonphong/360-viewer/viewer.css';

const viewer = new Phong360Viewer({
  container: document.getElementById('panorama')
});
await viewer.loadImage('/panoramas/example.jpg');
// When your page/component removes this viewer:
// viewer.destroy();

Run client-side after the container mounts. Keep one matching dependency set; replacing the Three version on an existing site is a separate compatibility change. The CSS import above uses the package's exported viewer.css path.

@ansonphong/360-viewer-library is a separate package for gallery chrome. Its version, dependency range, manifest/configuration and assets need their own matching setup. Use the maintainer's integration documentation for that task; the single-image example above does not configure a whole gallery. Do not combine old 360-engine/360-library-ui examples with the renamed packages.

Troubleshooting

  • Container not found: run after the element exists; pass its ID without # or the element itself, and give it a visible height.
  • Three is missing / viewer will not initialize: check script order and the matching dependency. The ordinary UMD and named standalone bundle both need it.
  • Image does not appear: open its URL, check browser console/network results and cross-origin image permission when using another host. A local file path on your computer is not a public website asset.
  • Slow or blank on a smaller device: test a smaller exported image and confirm WebGL support. A supported file size is not a memory guarantee.
  • Embedding in a changing page: call destroy() when removing the instance so its viewer resources and controls can be released.

The package's published version and included files own this example's API. Review the pinned package's included licence and dependency licences for redistribution.

Esc
Searching...
No results found.
Type to search the documentation
↑↓ Navigate ↵ Select Esc Close

We use cookies for analytics to understand how visitors use our site. Privacy Policy