WWDC 2026: Get started with the HTML Model Element (Session 215)

Use the native HTML <model> element to embed USDZ 3D content in Safari, add fallbacks and interactions, enable AR, and optimize assets for production.

Watch on Apple Developer

TL;DR

The HTML <model> element is now described as available across Safari on iOS, iPadOS, macOS, and visionOS, with native rendering and stereoscopic support on visionOS.
Use USDZ for the best starting point: it packages geometry, materials, textures, and animations in one file and works with the element's loading, playback, AR, and optimization workflows.
Production pages should include image fallback content, handle the element's ready promise, optionally load the W3C polyfill where native support is absent, and test both native and polyfilled behavior.
Interactivity ranges from one-attribute orbit controls to custom DOMMatrix transforms, requestAnimationFrame transitions, baked animation playback, AR Quick Look, and visionOS spatial experiences.

What the HTML Model Element Provides

The HTML <model> element brings 3D content to web pages using a native element, similar in spirit to using <img> for images. Apple introduced it on visionOS and describes expanded support across iOS, iPadOS, and macOS, using the same markup across Apple platforms.

The session positions <model> as a native alternative to JavaScript libraries such as model-viewer for supported browsers. A polyfill is available for browsers without native support, but not every capability can be polyfilled; stereoscopic display on spatial platforms is called out as a native-only capability.

Use native <model> when Safari platform integration and visionOS stereoscopic rendering matter.
Use a polyfill for broader browser reach, but test native and polyfilled behavior separately.
Track the emerging W3C model element specification if building long-lived web 3D infrastructure.

Prepare USDZ Assets

The recommended asset path is Capture, Convert, Create: scan real-world objects with iPhone, convert existing 3D files, or author from scratch in tools such as Blender. The session also mentions generating models from images or text prompts with tools such as Tripo3D and Meshy.ai.

USDZ is the recommended starting format. It is Universal Scene Description packaged into a single file and can include geometry, materials, textures, and animations. Safari supports other formats too, but the examples use USDZ throughout.

Start with USDZ for the best Model element experience in Safari.
Bake animations into the USDZ file if you want <model> to play them directly.
Use AOUSD resources for USDZ specification and pipeline information.

Load Models, Fallbacks, and Readiness

A model can be loaded directly with the src attribute or with a nested <source> element that includes a MIME type. Because 3D assets can be large, the page should provide loading UI and use the ready promise to know when the asset is ready to display.

Fallback content belongs inside the <model> element. Older Safari versions and browsers that do not support <model> can render an inner image, preserving a useful product view. For unsupported browsers, conditionally importing a polyfill can provide as much of the API as JavaScript can emulate.

Use <img> inside <model> as the simplest fallback.
Use model.ready.then(...) to hide loading indicators once the model is available.
Use model.ready.catch(...) to handle load failure and show fallback UI.
Check window.HTMLModelElement before loading a polyfill.

Load a USDZ model with a fallback image

Embeds a USDZ model while preserving an image fallback for browsers without native support or when fallback content is needed.

<model id="mallet" src="mallet.usdz">
  <img src="mallet.png" alt="Rubber mallet with wooden handle">
</model>

Wait for the model to be ready and conditionally polyfill

Uses the ready promise for loading state and loads a polyfill only when the native element is not defined.

<model id="mallet" src="mallet.usdz"></model>

<script>
  const model = document.getElementById("mallet");
  model.ready
    .then(result => {
      // Hide the loading indicator
    })
    .catch(error => {
      // Loading failed, show fallback
    });
</script>

<script type="module">
  if (!window.HTMLModelElement) {
    import("model-element-polyfill.js").then(() => {
      // Polyfill ready to use
    });
  }
</script>

Styling and Interaction

The model renders in its own virtual space, so it does not automatically pick up the page background. Set background-color directly on the <model> element to visually integrate it with the page; the background is rendered as fully opaque even when a transparent color is specified.

For basic interaction, stagemode="orbit" lets visitors rotate the model side to side, springing back from vertical tilt and rescaling the model to reduce clipping during rotation. For custom controls, remove orbit behavior and assign a DOMMatrix to entityTransform from JavaScript.

Prefer stagemode="orbit" for simple product exploration with minimal code.
Use entityTransform for exact view changes such as Side or Reset buttons.
When manually transforming a model, account for bounding boxes and clipping; the model can rotate out of the visible area.
Use requestAnimationFrame to animate custom transform transitions smoothly.

Enable built-in orbit interaction and set a matching background

Adds built-in rotation behavior and sets the model's own opaque background color.

<model id="mallet" src="mallet.usdz" stagemode="orbit"></model>

<style>
  model {
    background-color: #f4f1ec;
  }
</style>

Apply a custom orientation with entityTransform

Uses DOMMatrix rotation around the Y axis to switch the model to a specific view, then restores the initial transform.

<model id="boot" src="boot.usdz"></model>
<button id="button-side">Side</button>
<button id="button-reset">Reset</button>

<script>
  const model = document.getElementById("boot");
  const initialTransform = model.entityTransform;

  document.getElementById("button-side").addEventListener("click", () => {
    const transform = new DOMMatrix();
    transform.rotateSelf(0, 135, 0);
    model.entityTransform = transform;
  });

  document.getElementById("button-reset").addEventListener("click", () => {
    model.entityTransform = initialTransform;
  });
</script>

Animation, AR, and Spatial Experiences

If the USDZ file includes baked animation, the Model element can play the first animation track. The playbackRate property controls speed and direction: positive values play forward, negative values reverse, and larger magnitudes play faster.

To let users place the object in their environment on iOS and iPadOS, wrap the model in an <a rel="ar"> link to the same USDZ resource. On visionOS, <model> supports stereoscopic rendering and is also used by immersive website environments that place the visitor inside a 3D scene.

Use model.play() to start baked animation playback.
Set model.playbackRate before playback to control direction and speed.
Wrap <model> in <a rel="ar" href="..."> for AR Quick Look on iOS and iPadOS.
Consult the immersive website environments session for the visionOS environment API details.

Play a baked animation forward or in reverse

Controls the first animation track baked into the USDZ file using playbackRate and play().

<model id="bottle" src="bottle.usdz"></model>
<button id="button-play" onclick="play(5)">Play</button>
<button id="button-reverse" onclick="play(-5)">Reverse</button>

<script>
  const model = document.getElementById("bottle");

  function play(rate) {
    model.playbackRate = rate;
    model.play();
  }
</script>

Enable AR Quick Look

Links the model to AR Quick Look on iOS and iPadOS while keeping the inline 3D model on the page.

<a rel="ar" href="bottle.usdz">
  <model id="boot" src="bottle.usdz"></model>
</a>

Optimize for Production and Next Steps

Large 3D assets can make web pages feel slow, so the session recommends optimizing USDZ files before shipping. The usdcrush command-line tool is shown reducing a boot model from 7.9 MB to 1.9 MB with no perceived visual quality loss in the demo.

For catalogs that need fallback images or thumbnails, usdrecord can render images directly from a 3D file, including options such as output format and custom camera rendering when the file contains a camera. Both usdcrush and usdrecord are described as installed on macOS as part of the USD tool suite.

Run usdcrush on USDZ assets before production deployment.
Use usdrecord to generate fallback images or thumbnails from source 3D assets.
Review the WWDC24 USD and MaterialX session for deeper USD tooling coverage.
Provide feedback through WebKit, Feedback Assistant, and the W3C Immersive Web Community Group.

USD tooling mentioned for production pipelines

The session names usdcrush for size reduction and usdrecord for rendering thumbnails or fallback images; exact flags depend on the asset and output needs.

usdcrush boot.usdz
usdrecord input.usdz thumbnail.png

Get started with the HTML Model Element