Library / SDK
pmndrs/xr avatar
pmndrs/xr

xr turns a react-three-fiber app into an immersive one in three steps, and its newest tag is from January 2025

🤳 VR/AR for react-three-fiber

2,626 stars206 forksTypeScriptNOASSERTION

At a glance

What is it?
The xr package, published as @react-three/xr, adds AR and VR to a react-three-fiber application by creating a store, entering AR from a button, and wrapping the scene in an XR component. The repository carries twenty four examples, a mocha and playwright test setup, release candidate and latest tags in its own development dependencies, an agents directory and a skills directory, and a tagged release line that stopped at v6.6.0 in January 2025 while commits continued to September 2026.
Who is it for?
xr suits a team already building with react-three-fiber that wants immersive mode without hand wiring WebXR session code, and the migration guide from version 5 suggests that is exactly the audience.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 31 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pmndrs/xr2,626 ★ · +14
Star history
Repository2026-09-292026-11-15
pmndrs/xr2.6k2.6k

14 Stars in the last 47 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One install line, three steps, one store at module scope

The install is a single command that installs three packages at once:

bash
npm install three @react-three/fiber @react-three/xr@latest

Only the last one carries a tag. `three` and `@react-three/fiber` are unpinned, while the xr package is explicitly asked for at its latest release, which means a fresh install can combine a current engine with an older React three layer or the other way round.

Turning an existing app into an immersive one is described as three steps. Create a store with `createXRStore()`. Call `store.enterAR()` from a button. Wrap the scene content in the `XR` component. There is a separate guide for converting a react-three-fiber application wholesale, which is the route for a codebase that already exists rather than one being started.

The sample shows where the store lives, and the answer is at module scope, outside the component:

tsx
const store = createXRStore()

That is the detail worth copying carefully. A store created inside a component would be a new object on every render, and the session state inside it would not survive one.

The npm package name and the repository name differ. The repository is pmndrs/xr, the published package is `@react-three/xr`, and the documentation lives under the pmndrs docs site rather than in the repository.

The example closes its Canvas and stops there

The sample application is a mesh that changes colour when touched or pointed at, and the whole of it is:

tsx
import { Canvas } from '@react-three/fiber'
import { XR, createXRStore } from '@react-three/xr'
import { useState } from 'react'

const store = createXRStore()

export function App() {
  const [red, setRed] = useState(false)
  return (
    <>
      <button onClick={() => store.enterAR()}>Enter AR</button>
      <Canvas>
        <XR store={store}>
          <mesh pointerEventsType={{ deny: 'grab' }} onClick={() => setRed(!red)} position={[0, 1, -1]}>
            <boxGeometry />
            <meshBasicMaterial color={red ? 'red' : 'blue'} />
          </mesh>
        </XR>
      </Canvas>

It opens a fragment with a button and a Canvas, places the store into the XR component, and gives the mesh a click handler. Then it stops, with the Canvas closed and the outer fragment never closed. So the shape is legible and the program is not runnable as printed.

The interesting line is the one on the mesh. `pointerEventsType={{ deny: 'grab' }}` tells the interaction layer not to fire pointer events for a grab gesture on that object, which is what lets a tap or a controller ray reach the click handler instead of being swallowed by a grab. That single prop is the difference between the behaviour described in the caption above the table and a mesh that cannot be touched.

Position is set to zero, one, minus one, which places the box a metre in front of the origin, and the material is a basic one with no lighting, so the colour change is the only thing the sample demonstrates.

Twenty four examples, one of them not React

The examples directory is the real documentation for this package. There are twenty four of them, and their names describe the surface area rather than the demos.

There is a `vanilla` example and a `handle-vanilla` example alongside the React ones, which indicates that the store and the handles can be driven without React in the tree. There are two handle examples, one plain and one vanilla, suggesting the handle system has a standalone path.

Then there is `react-three-xr`, which sits in the same directory as the current examples and matches the name of the previous major version, so it is most likely the migration case rather than a separate feature.

The rest are scenes with a purpose: `avatar`, `demo-controller`, `editor`, `handheld-ar`, `hit-testing`, `layers`, `map-handles`, `minecraft`, `miniature`, `pingpong`, `pointer-events`, `portal`, `rag-doll`, `rollercoaster`, `room-with-shadows`, `secondary-input-sources`, `stage`, `uikit`, `use-gesture` and `watch`.

The tutorials index covers the same ground as a feature list: Store, Interactions, Handles, Options, Object Detection, Origin, Teleport, Gamepad, Secondary Input Sources, Layers, Custom Controller and Hands, Anchors, Dom Overlays, Hit Test and Guards. One tutorial is external rather than first party, a React starter published by Meta Quest.

The root manifest is a workspace, not the published package

The manifest at the repository root is not the manifest of the package you install. It has no name field, no version field and no main entry. It declares an author, Bela Bohlender, an MIT licence, and the module type. Its entire script section is two entries, one that combines documentation and one that runs an eval named for the package.

Its runtime dependencies are a single package, ts-node. Everything else sits in development dependencies, and that list is where the framework lives: react, react-dom, three, @react-three/fiber, @react-three/drei, vite with its React and basic SSL plugins, typescript, playwright, mocha, chai, eslint with four plugins, and prettier.

The published package therefore lives under `packages/`, and the root is a pnpm workspace container, which is also why there is a `pnpm-workspace.yaml` and a `pnpm-lock.yaml` at the root rather than a single package lock.

Two version strategies in that list are worth noticing because they are not the same as each other. `@react-three/fiber` and `@react-three/drei` are requested at the `rc` tag, meaning a release candidate rather than a numbered release. `three` and `@types/three` are requested at `latest`. And `vitexec` is pinned to one exact version while nearly everything else uses a caret range.

A development install is therefore partly tracking whatever the upstream release candidate and latest tags point at, which is a reasonable choice for a package that has to be tested against unreleased engine changes and a poor one for reproducible builds.

Versioning comes from tags, and the tagged line stopped in January 2025

Version numbers are derived from git history rather than typed into the manifest, with a `GitVersion.yml` at the root doing the work. That file is why the root manifest has no version field and why the published number follows the tag rather than an edit.

The three most recent tags are v6.3.0 and v6.4.0, both dated 2024-11-01, and v6.6.0 dated 2025-01-30. Two releases on the same day, then a jump to 6.6 with no 6.5 among them. The repository itself is not archived and its last push is dated 2026-09-28, which is eight months after the newest tag, so the default branch is well ahead of anything the version history describes.

Migration is treated seriously, which is what a jump from 6.4 to 6.6 usually demands. There is one guide for coming from version 5 of the package and a second for coming from a different project entirely, natuerlich. A package that writes a migration guide from a competitor is telling you who it expects to attract.

The roadmap section lists two items, XR Gestures and Tracked Body. Both are gesture level features, which is the honest gap in a package whose interaction tutorials otherwise cover input sources, hit testing and anchors.

Agent instructions and skills are part of the tree

Two directories at the root are not about the library. There is `.agents/`, and there is a `skills/` directory paired with a `skills-lock.json` file at the root. A lock file next to a skills directory implies those skills are pinned to a revision rather than copied by hand, the same way a lock file pins a dependency.

For a package in this space that is a notable choice, since the documented tutorials already cover how to build input handling, and shipping agent instructions means the repository itself is a place an assistant is expected to read from.

The rest of the tooling is more conventional. Linting uses `.eslintrc` with eslint 8 and the classic configuration format, alongside `.prettierrc`. Tests run under mocha with a `.mocharc.json`, and playwright is in the development dependencies, so the browser side is driven by playwright while mocha remains the runner. There is also an eslint plugin published by the same organisation, `@react-three/eslint-plugin`, held at a 0.1 version, which is early enough that the project is both a consumer and a producer of lint rules.

Documentation is built into `docs/` with a combine step in the root scripts, and contributing guidance sits in `CONTRIBUTING.md` at the root.

Editorial conclusion

xr suits a team already building with react-three-fiber that wants immersive mode without hand wiring WebXR session code, and the migration guide from version 5 suggests that is exactly the audience. Check four things first: the install line pins @latest on the xr package only, so the three packages in that line can resolve to different generations; the tagged line stops at v6.6.0 from 2025-01-30 while the repository's last push is dated 2026-09-28, so a tag and the default branch are not the same code; the sample application in the front page ends with the Canvas closed and the outer fragment unclosed, so it is a shape to copy rather than a program to run; and the roadmap still lists XR Gestures and Tracked Body as unfinished. Anyone who needs gesture recognition today has to build it on the interactions and input source tutorials instead.

Frequently asked questions

What is pmndrs/xr?

A package that turns a react-three-fiber application into an interactive immersive experience, published to npm as @react-three/xr. The conversion is three steps: create a store with createXRStore(), call store.enterAR() from a button, and wrap the scene content in the XR component.

How do I install xr for react-three-fiber?

`npm install three @react-three/fiber @react-three/xr@latest`. Only the xr package is asked for at an explicit tag, while three and @react-three/fiber are left unpinned, so the three can resolve to different generations.

Which XR features does xr have tutorials for?

Store, Interactions, Handles, Options, Object Detection, Origin, Teleport, Gamepad, Secondary Input Sources, Layers, Custom Controller and Hands, Anchors, Dom Overlays, Hit Test and Guards. An external React starter from Meta Quest is linked as well.

How do I migrate an existing app to xr?

Two migration guides are published, one from @react-three/xr version 5 and one from natuerlich. The roadmap lists XR Gestures and Tracked Body as items that do not exist yet.

How is the xr version decided, and what is the newest release?

Version numbers come from a GitVersion configuration in the repository rather than from a field in the manifest. The most recent tags are v6.3.0 and v6.4.0 from 2024-11-01 and v6.6.0 from 2025-01-30, while the repository's last push is dated 2026-09-28.

Official sources

  1. Issues
  2. pmndrs/xr on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pmndrs-xr.svg)](https://hysenlabs.com/projects/pmndrs-xr)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pmndrs-xr.svg)](https://hysenlabs.com/projects/pmndrs-xr)

Was this useful?