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.
Full Gallery: Multiple Images with UI
@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.