# API Reference

> Every DashPannellum prop — configuration, behavior and read-only state

**Site index:** [https://pannellum.2plot.dev/llms.txt](https://pannellum.2plot.dev/llms.txt) — every page on this site, as Markdown.  
**Network index:** [https://2plot.dev/llms.txt](https://2plot.dev/llms.txt) — The 2plot network; start here to discover sibling sites.  
**Sibling sites:** 13 more in The 2plot network — listed in the site index above.  
**Sitemap:** https://pannellum.2plot.dev/sitemap.xml  


---



### Component props

The table below is generated from the component's own metadata, so it always matches the installed version.


| Prop | Type | Description |
|------|------|-------------|
| `id` | string; optional | The ID used to identify this component in Dash callbacks. |
| `autoLoad` | boolean; default True | If True, automatically loads the panorama without user interaction. |
| `callbackHotspots` | dict; optional | Extra hotspots that report clicks back to Dash. Keys are scene IDs, values are arrays of hotspot objects ({pitch, yaw, type, text, name}). Clicking one updates the `lastClickedHotspot` prop. |
| `compass` | boolean; default False | If True, displays a compass in the panorama viewer. |
| `currentScene` | string; optional | Read-only. The ID of the current scene in tour mode. |
| `customControls` | boolean; default False | If True, hides the built-in zoom/fullscreen controls so you can build your own controls with Dash components. |
| `dynamicUpdate` | boolean; default False | If True, the viewer re-uploads its panorama texture every frame — required for scenes backed by a live <canvas> (`panoramaCanvasId`). This is the movement-mechanics primitive: redraw the canvas from a game loop and the sphere follows with no rebuild. Leave False for static panoramas. |
| `height` | string; default '400px' | The height of the panorama viewer (any CSS size, e.g. '400px'). |
| `hfov` | number; optional | Read-only. The current horizontal field of view (zoom), in degrees. |
| `hideLoadingSpinner` | boolean; default False | If True, suppresses Pannellum's "Loading..." box for this viewer — useful with preloaded scenes or data-URI panoramas where the flash is the only visible part of an otherwise instant transition. |
| `lastClickedHotspot` | string; optional | Read-only. The name of the last clicked callback hotspot. |
| `loadScene` | string; optional | Imperative scene switch — set to a scene ID from the tour config to load that scene without rebuilding the viewer. Unknown IDs and the already-active scene are ignored. |
| `loaded` | boolean; optional | Read-only. True once the panorama has loaded. |
| `lookAt` | dict; optional | Imperative camera write — set {pitch, yaw, hfov, animated} to pan/zoom the existing viewer without rebuilding it. Omitted fields keep their current value; `animated` is the transition duration in ms (default 1000, use a small value for joystick-style continuous steering). Image panorama modes only. |
| `multiRes` | dict; optional | Configuration object for multi-resolution (tiled) panoramas: {basePath, path, fallbackPath, extension, tileResolution, maxLevel, cubeResolution}. |
| `northOffset` | number; default 0 | The offset, in degrees, of the center of the panorama from North. |
| `orientation` | boolean; default False | Request gyroscope look-around (device orientation). Works on mobile devices with motion sensors; Pannellum runs the iOS 13+ permission prompt when needed, so on iOS set this to True from a clientside callback on a direct user tap. Whether it actually engaged is reported through `orientationSupported` and `orientationActive`. |
| `orientationActive` | boolean; optional | Read-only. True while gyro look-around is actively steering the camera (False if permission was denied or `orientation` is off). |
| `orientationSupported` | boolean; optional | Read-only. True when the device/browser can drive the camera from the gyroscope (requires motion sensors and a mobile browser). |
| `pitch` | number; optional | Read-only. The current pitch of the panorama view, in degrees. |
| `preloadScenes` | boolean; default True | If True (default), the other scenes' panorama images are prefetched into the browser cache once the viewer is up, so tour jumps don't show a loading box. |
| `showCenterDot` | boolean; default False | If True, displays a center dot in the panorama viewer — useful as a crosshair when authoring hotspot positions. |
| `tour` | dict; optional | Configuration object for tour mode. Follows the Pannellum tour format: {default: {firstScene, ...}, scenes: {sceneId: {...scene config}}}. A single equirectangular panorama is a tour with one scene. A scene may set `panoramaCanvasId` (the DOM id of a <canvas> element) instead of `panorama` to use Pannellum's dynamic mode: redraw the canvas and the sphere updates in place — no rebuild, no camera reset. Pair with the `dynamicUpdate` prop. |
| `useHttpStreaming` | boolean; default False | If True, loads the video.js HTTP streaming plugin so HLS/DASH sources (e.g. live streams) can be played as 360° video. |
| `video` | dict; optional | Configuration object for 360° video panoramas, rendered through video.js: {sources: [{src, type}], poster}. |
| `width` | string; default '600px' | The width of the panorama viewer (any CSS size, e.g. '100%' or '600px'). |
| `yaw` | number; optional | Read-only. The current yaw of the panorama view, in degrees. |


---

### Read-only props

These update from the viewer — use them as callback `Input`s, never set them yourself:

| Prop | Updates when |
|------|--------------|
| `loaded` | The panorama or video finishes loading |
| `pitch` | The camera pitch changes (throttled, change-detected) |
| `yaw` | The camera yaw changes (throttled, change-detected) |
| `hfov` | The zoom changes (throttled, change-detected) — new in 0.2.0 |
| `currentScene` | The active tour scene changes |
| `lastClickedHotspot` | A callback hotspot is clicked |
| `orientationSupported` | Gyro steering is possible here (mobile + HTTPS) — new in 0.4.0 |
| `orientationActive` | The gyroscope is steering right now — new in 0.4.0 |

### Imperative props (0.2.0 / 0.3.0)

These act on the live viewer **without a rebuild** — output them from
callbacks (or `window.dash_clientside.set_props` for high-frequency use):

| Prop | Action |
|------|--------|
| `lookAt` | `{pitch, yaw, hfov, animated}` — pan/zoom the camera; omitted fields hold |
| `loadScene` | Scene ID string — switch tour scenes |
| `callbackHotspots` | **Live**: per-name diff — position-only changes move the existing DOM node in place (0.3.1), other changes recreate just that hotspot |
| `dynamicUpdate` | Re-upload the texture each frame — pairs with the `panoramaCanvasId` scene key (0.3.0) for canvas-backed worlds |
| `orientation` | Request gyro look-around (0.4.0) — set from a clientside callback on a tap for the iOS permission prompt |

See [Scene Configuration](/components/scenes) for the fly-to pattern, the
[Joystick Arena](/components/arena) for the full movement stack, and
[Gyro Look-Around](/components/gyro) for device-orientation steering.

---

### Changes since 0.0.6


    - **Dash 4.2+ required** (was Dash 1/2 era). The package now ships `pyproject.toml` packaging and a React 18 build.
    - **`customControls` is now coherent across modes**: `True` hides the built-in zoom/fullscreen controls (previously it was ignored for image panoramas and inverted for video).
    - **Video no longer autoplays**; users press play. Set up your own interaction if you need autoplay (browsers block autoplay-with-audio anyway).
    - **`pitch`/`yaw` updates are throttled to 4/s and change-detected** (previously 10/s unconditionally), so idle viewers no longer trigger callbacks.

New in 0.1.0: configuration props are **live** — output a new `tour` (or `multiRes`/`video`) from a callback and the viewer re-initializes with it, so panoramas can be swapped dynamically. Callback hotspots use real Pannellum click handlers (they previously relied on a viewer event that never fired reliably), script loading is deduplicated so several viewers can share one page, and the `loaded` prop is properly declared.


---

*Source: /api*