Build Your Own Web

Build this website with blocks

Try another way to build: snap together HTML, CSS and behavior blocks, change their fields, and watch your website update. Start with this lesson’s project or try a code example below.

Lesson 10 · Optional extension · 45–60 minutes

Extend into WebXR

WebXR lets a web page ask the browser for a headset. When one is there, your gallery becomes a room you can stand in. When one is not — which will be the case for most people reading this — the same page is still a working 3D gallery you drive with your mouse and some buttons.

You are not blocked without a headset. The desktop gallery is the deliverable for this lesson. VR is a bonus that happens to be available on some machines. Nothing below asks you to buy hardware.

What you are building

A small room holding three exhibit panels, one for each of your projects. It runs inside your existing site, on the page you already publish, using the same HTML and JavaScript you have been writing all course.

Two rules hold the whole lesson together:

  • The 3D view is an enhancement. The flat page underneath it must carry the same information.
  • Anything the 3D view can do, a plain button or a plain list must also be able to do.

Deeper XR concepts — AR, MR, tracking, controllers, and the design questions around them — are covered in Extended Reality.

What WebXR is, and what it is not

WebXR is a browser API. Your JavaScript asks navigator.xr whether an immersive session is possible, and if the user agrees, the browser hands your renderer a pair of eye views and the position of the headset. Your page keeps running the whole time. There is no separate app, no install, and no store.

What it is not is a replacement for your website. A headset is a device some visitors have; a screen is a device nearly all of them have. If your projects only exist inside the 3D room, most of your audience cannot see them at all. Build the flat version first, then let the 3D version show the same content in another form. This is the same "enhancement, not replacement" idea you used when you made the site work without JavaScript.

Three practical limits are worth knowing before you start:

The gallery

This is the working example. Drag nothing and install nothing: use the buttons. The status line tells you exactly what this device and browser can do.

Project gallery

Your browser cannot draw this 3D scene. The exhibit list below has the same information.

The two VR buttons stay disabled until the page has confirmed a headset session is actually available. That is the honest state, not a fault.

Exhibit list

Every exhibit in the room appears here in text. This list is the accessible version of the gallery, and it works with no 3D at all.

  • Orbit study — the exhibit on the left. A sphere above a green panel, standing for a simulation project: something that moves on its own once you press start, like a planet on a path or a bouncing particle.
  • Geometry game — the exhibit in the middle. A cube above an orange panel, standing for a project the visitor plays: rules, input, and a score or a goal.
  • Light experiment — the exhibit on the right. A ring above a violet panel, standing for a visual experiment: colour, shading, and how a surface reacts to the direction it faces.

The three shapes are drawn with a normal material, so their colours come from which way each face is pointing rather than from a light in the room. Turning your view changes the colours you see on the same object.

Check: you see a dark room with three coloured panels and three shapes in front of them. "Look left" and "Look right" swing the view, "Center the view" puts it back, and the status line ends in a sentence about this device — either that VR is supported, or a specific reason it is not.

Repair: if the canvas is blank and the status line reports that 3D graphics are unavailable, WebGL is switched off or unsupported in this browser — the exhibit list still holds all the content, which is exactly why it is there. If the status line never changes from "Checking this device", open the console: a module that fails to load is the usual cause, and the path ../assets/js/lessons/webxr-gallery.mjs must be exact, including its case. If "Enter VR" stays disabled with a headset connected, read the status text before anything else — it distinguishes an insecure page, a browser with no WebXR, and a device with no immersive session available.

How the page asks for VR

The whole VR negotiation is four short moves. Read this and then read the real file, assets/js/lessons/webxr-gallery.mjs, next to it.

1. Turn XR on in the renderer, so it knows to render two eye views when a session starts:

renderer.xr.enabled = true;
renderer.xr.setReferenceSpaceType('local');

2. Ask, do not assume. Check the secure context first, then whether the browser exposes the API at all, then whether this particular session type is supported. Each failure gets its own message, because "it didn't work" is not a repairable sentence:

if (!window.isSecureContext) { /* HTTPS or localhost required */ }
if (!navigator.xr) { /* browser has no WebXR at all */ }
const supported = await navigator.xr.isSessionSupported('immersive-vr');
enter.disabled = !supported;

3. Start the session from a click, and hand it to the renderer:

session = await navigator.xr.requestSession('immersive-vr');
await renderer.xr.setSession(session);

4. Always draw through the XR loop. A normal requestAnimationFrame loop does not run at headset frame rate. setAnimationLoop does, and it keeps working on the desktop when no session is active:

renderer.setAnimationLoop(() => {
  if (!renderer.xr.isPresenting) syncSize();
  renderer.render(scene, camera);
});

Notice what happens when step 3 fails: the code catches the error, re-enables the button, and writes the error name into the status line. Every failure path in that file ends with a working desktop gallery. That is the pattern to copy — the enhancement can fail, but the page cannot.

Comfort and safety in a headset

If you do have hardware, this section is not optional advice. Discomfort in VR is a real physical response, not a lack of toughness.

Before you put it on

  • Clear the play area: no chairs, tables, pets, or younger siblings within arm's reach, and nothing overhead.
  • Stay seated for a gallery like this one. Sitting removes most of the risk of walking into something.
  • Have another person nearby the first few times.
  • Know how to leave before you enter: the headset's system button, and the Exit VR button on the page.

While you are in

  • Take a break every fifteen to twenty minutes, whether or not you feel you need one.
  • Stop at the first sign of nausea, dizziness, sweating, or eye strain. It gets worse quickly and takes a while to pass.
  • Take the headset off to talk to someone. You cannot see them.

Rules for what you build

Do not move the camera for the user. Motion the body did not ask for is the single largest cause of sickness in VR. In this gallery the view only changes when a button is pressed, and it snaps rather than sliding.

Keep the frame rate steady. Stutter is uncomfortable in a way it never is on a monitor. Fewer objects and simpler materials are worth more than detail.

Never trap the user. There is always a visible way out, and your exit path must work even if your own code has failed.

No flashing. Rapid flashing can trigger seizures, and a headset fills the whole field of view.

Say what a visitor is walking into. Put a line on the flat page: what the scene contains, whether it moves, and roughly how long it lasts.

3D is not accessible by itself

A canvas is one element containing pixels. A screen reader cannot describe a shape in it, a keyboard cannot tab to an object inside it, and someone who cannot use a mouse cannot orbit it. If the gallery were the only place your projects existed, you would have made your site less usable than it was before.

Three things carry the load instead, and all three are ordinary HTML:

  1. The exhibit list. Real text, in the document, naming every exhibit and describing it. It must stay in agreement with the scene — if you add a fourth exhibit to the 3D room, you add a fourth item to the list in the same commit.
  2. The buttons. "Look left", "Look right", and "Center the view" are keyboard-reachable and screen-reader-readable. They give a second route to everything the mouse can do, and "Center the view" is the recovery move when someone is lost.
  3. The status line. It is marked aria-live="polite", so its message is announced when it changes instead of silently appearing. It also uses words, not colour, to report state — a red border alone would tell a colour-blind visitor nothing.

Test it the way you tested the rest of your site: unplug the mouse, tab through the lab, and confirm you can read every exhibit and reach every control. Then zoom to 200% and check the list still reads properly.

Make it your own

  1. Copy the lab markup and the module into your own project folder, keeping the element ids the script looks for: gallery-canvas, gallery-status, gallery-enter, gallery-exit, gallery-center, and the data-gallery-look buttons.
  2. Replace the three exhibit titles with your own project names — in the script's exhibit array and in the HTML list. Out-of-date text under a 3D scene is worse than no text.
  3. Change the panel colours and the shapes so each exhibit is distinguishable by shape as well as colour.
  4. Add a normal link under each list item that opens the real project page. The gallery advertises the work; the flat page delivers it.
  5. Publish over HTTPS using the publishing lesson, then test on the real URL. The secure-context rule means the local file will never fully exercise the VR path.

When you show this to someone, show the flat page first and the room second. If the flat page already answers "what did you make?", the 3D version is what it should be: a bonus.

Checkpoints