# API Reference

> Every prop on ModelViewer and Slot, every event payload, and the precedence rules.

**Site index:** [https://modelviewer.2plot.dev/llms.txt](https://modelviewer.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://modelviewer.2plot.dev/sitemap.xml  


---



### `dmv.ModelViewer`

#### Required

**Enforced.** Omitting either raises a `TypeError` at construction naming the
missing prop — the same error, in the same words, that every Dash component
raises for a required argument. Passing the keyword explicitly as `None` fails
the same way, because `alt=None` is not an accessible description.

| Prop | Type | Notes |
| :-- | :-- | :-- |
| `src` | `str` | URL of the `.glb` / `.gltf`. Relative paths resolve against `assets/`. |
| `alt` | `str` | Accessible description. Not decorative — it is the entire experience for a screen-reader user. |

#### Layout

| Prop | Type | Default | Notes |
| :-- | :-- | :-- | :-- |
| `id` | `str \| dict` | — | Callback id. Pattern-matching dicts work. |
| `style` | `dict` | — | **Give it a height.** The element has no intrinsic size. |
| `class_name` | `str` | — | CSS class on the viewer element, e.g. `class_name="hero-viewer"`. Styles it from `assets/`; the element itself is the styling target, not a wrapper. |
| `children` | list of `Slot` | — | Hotspots, AR button, poster, progress bar. |

#### Camera

| Prop | Type | Default | Notes |
| :-- | :-- | :-- | :-- |
| `camera_controls` | `bool` | `True` | Orbit, zoom, pan. |
| `touch_action` | `'pan-y' \| 'pan-x' \| 'none'` | `'pan-y'` | Which gestures the page keeps. The default lets a phone scroll the page vertically *through* the viewer; `touch_action="none"` gives every gesture to the model and is right only for a full-screen viewer. |
| `camera_orbit` | `str` | — | `"theta phi radius"`. Two-way. |
| `camera_target` | `str` | — | `"X Y Z"` in metres. |
| `field_of_view` | `str` | — | e.g. `"30deg"`. |
| `min_field_of_view` / `max_field_of_view` | `str` | — | Zoom limits, e.g. `min_field_of_view="15deg"`, `max_field_of_view="45deg"` to stop the user zooming to a blank close-up or losing the model in the distance. |
| `min_camera_orbit` / `max_camera_orbit` | `str` | — | Orbit limits as `"theta phi radius"`; `"auto auto auto"` for none. `max_camera_orbit="auto 90deg auto"` is the common one — it stops the camera dropping below the floor plane. |
| `interpolation_decay` | `float` | — | Camera easing. Lower is slower; `0` is a jump cut. |
| `camera_change_debounce` | `float` | `100` | Milliseconds. **Do not set to 0 without meaning it.** |

#### Rendering

| Prop | Type | Default | Notes |
| :-- | :-- | :-- | :-- |
| `poster` | `str` | — | Image shown until the model is ready, e.g. `poster="/assets/astronaut.png"`. Worth setting for a large `.glb`: without one the viewer is an empty box for the whole download. |
| `tone_mapping` | `str` | `'neutral'` | |
| `shadow_intensity` | `float` | — | |
| `variant_name` | `str \| None` | `None` | |

#### Augmented reality

| Prop | Type | Default |
| :-- | :-- | :-- |
| `ar` | `bool` | `True` |
| `ar_modes` | `str` | `'webxr scene-viewer quick-look'` |
| `ar_scale` | `'auto' \| 'fixed'` | `'auto'` |

#### Escape hatches

| Prop | Type | Notes |
| :-- | :-- | :-- |
| `attributes` | `dict[str, str]` | Raw kebab-case attributes. |
| `mv_*` | `str` | Wildcard. `mv_environment_image` → `environment-image`. |

Precedence: **named prop > `mv_*` > `attributes`**.

#### Read-only (set by the component)

| Prop | Payload |
| :-- | :-- |
| `camera` | `{"orbit": str, "target": str, "field_of_view": str}` — only for user interaction |
| `model_state` | `{"status": "loading" \| "loaded" \| "error", "progress": float, "detail": str?}` |
| `model_info` | `{"dimensions": {"x": float, "y": float, "z": float}, "variants": [str], "animations": [str]}` |
| `ar_status` | `"not-presenting" \| "session-started" \| "object-placed" \| "failed"` |
| `ar_tracking` | `"tracking" \| "not-tracking"` |
| `scene_point` | `{"position": str, "normal": str, "uv": [float, float]}` or `None` |

#### Input-only

| Prop | Type | Default | Notes |
| :-- | :-- | :-- | :-- |
| `pick_on_click` | `bool` | `False` | Arms `scene_point`. |

---

### `dmv.Slot`

| Prop | Type | Default | Notes |
| :-- | :-- | :-- | :-- |
| `slot` | `str` | — | **Required.** `"hotspot-*"`, `"ar-button"`, `"ar-prompt"`, `"ar-failure"`, `"poster"`, `"progress-bar"`. |
| `children` | components | — | Any Dash component. |
| `position` | `str` | — | `"X Y Z"` in model space. Required for hotspots. |
| `normal` | `str` | — | `"X Y Z"` surface normal; drives occlusion. |
| `id` | `str \| dict` | — | Callback id. |
| `style` | `dict` | — | |
| `class_name` | `str` | — | Added alongside the built-in `dmv-slot`, e.g. `class_name="hotspot-dot"` — the built-in class stays, so a rule on `.dmv-slot` still applies. |
| `n_clicks` | `int` | `0` | Increments on click. Use as an `Input`. |

---

### Module level

| Name | Type | Notes |
| :-- | :-- | :-- |
| `dmv.__version__` | `str` | Read from installed metadata, not from a bundled JSON file. |
| `dmv.MODEL_VIEWER_VERSION` | `str` | The vendored `<model-viewer>` version — `"4.3.1"`. |
| `dmv.DEFAULT_AR_MODES` | `str` | `"webxr scene-viewer quick-look"`. |
| `dmv.DEFAULT_CAMERA_CHANGE_DEBOUNCE` | `int` | `100`. |
| `dmv.configure(use_cdn=...)` | function | See below. |

#### `configure(use_cdn=False)`

```python
dmv.configure(use_cdn=False)                        # default: vendored (in-wheel)
dmv.configure(use_cdn=True)                         # public jsDelivr, pinned version
dmv.configure(use_cdn="https://cdn.example/mv.js")  # your own mirror
```

Must run **before the first request is served**. Dash reads the hook's resource
list while generating the index page, so a call from inside a callback or a
lazily-imported page module may or may not take effect. Put it at module scope.

---

### Not in 1.0.0

Stated so you do not go looking:

- **Animation playback props.** Use `attributes={"autoplay": "", "animation-name": ...}`.
- **Imperative methods** — no `play()`, `pause()`, or programmatic `activateAR()`.
- **`ios_src` as a named prop.** Use `mv_ios_src`.
- **Annotation/label auto-layout.** `Slot` positions are yours to compute.


---

*Source: /api-reference*
