What if you could arrange 3D objects on a web page the same way you lay out boxes, with transform, anchors and a few CSS properties? That’s the idea behind spatial CSS, a proposed API that WebKit released as a limited developer preview in Safari on visionOS 27.3, announced on the WebKit blog on 16 November 2026.

It is early and experimental, but it shows where 3D on the web may be heading, and it builds on syntax front-end developers already know. This tutorial explains each piece of the preview with working examples and a sensible way to experiment today.

Where this fits: the <model> element

The foundation is the HTML <model> element, which displays an intrinsically 3D object (for example a .usdz file). WebKit says <model> is now available in Safari 27 on all platforms. Spatial CSS goes further: it lets several models share one 3D space and be positioned, anchored, lit and orbited with CSS.

A basic model looks like this:

<model src="chair.usdz" alt="A wooden chair"></model>

How to try the preview

The spatial CSS features are only in Safari on visionOS 27.3, behind a flag. On an Apple Vision Pro or in the visionOS Simulator (installed through Xcode), go to:

Settings → Apps → Safari → Advanced → Feature flags → CSS Portals

WebKit also hosts a demo page linked from its post. On other browsers and platforms, these properties are simply ignored, so you can experiment without breaking anything.

The six pieces of the preview

WebKit lists six features. We’ll build a small scene, a puzzle board with shaped blocks, to try them.

1. spatial: portal – a shared 3D space

Declaring an element as a portal turns it into a space that all its child elements share. In this preview it’s focused on <model> elements, though WebKit says the specification is written so the approach should eventually work for all content.

<div class="world">
  <model id="board" src="board.usdz"></model>
  <model id="octagon" src="octagon.usdz"></model>
  <model id="star" src="star.usdz"></model>
</div>

<style>
  .world {
    spatial: portal;
  }
</style>

2. transform – move models in true 3D

Inside a portal, the ordinary transform property becomes a real 3D transform. Distances can use physical units such as cm:

#octagon {
  transform: translateX(-50cm);
}

#star {
  transform: translateX(50cm);
}

Each model can be moved, rotated and scaled independently, and because these are normal CSS values, you can animate and transition them:

#star {
  transform: translateX(50cm);
  transition: transform 600ms ease;
}

#star.active {
  transform: translateX(0) rotateY(45deg);
}

3. position-anchor – snap models together

Fitting 3D objects together precisely is hard. <model> is a void element, so you can’t nest one model inside another. Instead, spatial CSS borrows the anchor positioning idea from 2D CSS. If the 3D file contains named reference points (often called “empties” or “null objects” in tools like Blender), you can snap another model to them:

#board {
  anchor-name: --board;
}

#octagon {
  position-anchor: --board#octagon-position;
  position-context: anchor;
}

#star {
  display: none;
}

Here octagon-position is an empty object authored inside board.usdz, marking where the octagon block should sit. No more copying coordinates out of your 3D editor.

4. @environment-map – reusable lighting

An environment map is the lighting reflected off an object, effectively the “room” it sits in. Previously this was an HTML attribute on <model>. Spatial CSS adds an at-rule, inspired by @keyframes, so lighting can be defined once and reused. The preview supports 360° HDR images:

@environment-map {
  name: "spooky";
  format: equirectangular;
  src: url("night.hdr");
}

.world.spooky {
  environment-map: "spooky";
}

Switching the mood of the whole scene is now a single class change.

5. portal-action: orbit – let users look around

Rotating a scene to view it from different angles (“orbiting”) is one of the most common 3D interactions. Spatial CSS enables it declaratively:

.world {
  spatial: portal;
  portal-action: orbit;
}

This mirrors the <model> element’s stagemode attribute but lives in CSS, which makes it easier to change with media queries. WebKit mentions other modes such as pan-x or pan-y as possible future additions.

6. requestVolumetricScene() – break out of the window

On visionOS, a portal’s contents can be lifted out of the browser window into the user’s space as a Connected Volumetric Scene. It must be triggered by a user action:

<button id="launch">View in your space</button>

<script>
  document.querySelector('#launch').addEventListener('click', () => {
    document.querySelector('.world').requestVolumetricScene();
  });
</script>

The page stays linked to the scene, so you can still add, remove or move objects after launch.

Progressive enhancement: build it safely

Since only one browser on one platform supports this today, wrap spatial features so other users get a clean fallback:

/* Default: a simple 2D layout */
.world {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 1rem;
}

@supports (spatial: portal) {
  .world {
    display: block;
    spatial: portal;
    portal-action: orbit;
  }
}

And guard the JavaScript API:

const world = document.querySelector('.world');
const button = document.querySelector('#launch');

if (typeof world.requestVolumetricScene === 'function') {
  button.hidden = false;
  button.addEventListener('click', () => world.requestVolumetricScene());
} else {
  button.hidden = true;
}

Whether @supports reports the property correctly in the preview isn’t documented in WebKit’s post, so test it in the simulator; the JavaScript feature check is the more reliable guard.

Why this approach matters

WebKit’s argument is that spatial content should be designed with the same tools as the rest of the web. Because spatial CSS is just CSS, your scene can respond to media queries (aspect ratio, colour scheme, reduced motion), animate with transitions, and stay declarative instead of requiring a heavy JavaScript 3D engine for simple arrangements. WebKit also stresses that spatial standards should work wherever browsers run, not only on headsets.

Limitations to keep in mind

  • It’s a developer preview on visionOS 27.3 only, behind a feature flag.
  • The specification is a proposal; names and behaviour may change.
  • Other browser engines haven’t committed to it, so treat it as experimentation rather than production work.

WebKit is actively asking for feedback via bugs.webkit.org and its social channels, which makes now a good time to try it and share what works and what doesn’t.

Key takeaways

  • Spatial CSS is a proposed API for composing 3D <model> content with CSS, previewed in Safari on visionOS 27.3.
  • The preview includes spatial: portal, 3D transform, position-anchor, @environment-map, portal-action: orbit and requestVolumetricScene().
  • Enable it via the CSS Portals feature flag and build with progressive enhancement.
  • It’s experimental, so experiment, give feedback and keep a 2D fallback.

Read WebKit’s full post, Introducing spatial CSS: A developer preview, for the demo and specification links.