xr

Full documentation content.

<page path="/getting-started/introduction" title="Introduction"><![CDATA[URL: https://pmndrs.github.io/xr/getting-started/introduction
Description: 🤳 XR for react-three-fiber


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

## What does it look like?

| A simple scene with a mesh that toggles its material color between `"red"` and `"blue"` when clicked through touching or pointing. | ![recording of interacting with the code below](./basic-example.gif) |
|-|-|

```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>
  </>
}
```

### Turn any @react-three/fiber app into an XR experience

1. `const store = createXRStore()` create a xr store
2. `store.enterAR()` call enter AR when clicking on a button
3. `<XR>...</XR>` wrap your content with the XR component

... or read this guide for [converting a react-three/fiber app to XR](../getting-started/convert-to-xr.md).

## Tutorials

- 💾 [Store](../tutorials/store.md)
- 👆 [Interactions](../tutorials/interactions.md)
- 👌 [Handles](../handles/introduction.md)
- 🧊 [Object Detection](../tutorials/object-detection.md)
- ✴ [Origin](../tutorials/origin.md)
- 🪄 [Teleport](../tutorials/teleport.md)
- 🕹️ [Gamepad](../tutorials/gamepad.md)
- ➕ [Secondary Input Sources](../tutorials/secondary-input-sources.md)
- 📺 [Layers](../tutorials/layers.md)
- 🎮 [Custom Controller/Hands/...](../tutorials/custom-inputs.md)
- ⚓️ [Anchors](../tutorials/anchors.md)
- 📱 [Dom Overlay](../tutorials/dom-overlay.md)
- 🎯 [Hit Test](../tutorials/hit-test.md)
- ⛨ [Guards](../tutorials/guards.md)
- 🖼️ [Render Targets](../advanced/render-targets.md)

## External Tutorials

- 🥇 [**WebXR First Steps React** by Meta Quest](https://github.com/meta-quest/webxr-first-steps-react)

## Roadmap

- 🤳 XR Gestures
- 🕺 Tracked Body

## Migration guides

- from [@react-three/xr v5](../migration/from-react-three-xr-5.md)
- from [natuerlich](../migration/from-natuerlich.md)

## Sponsors

This project is supported by a few companies and individuals building cutting-edge 3D Web & XR experiences. Check them out!

![Sponsors Overview](https://bbohlender.github.io/sponsors/screenshot.png)
]]></page>
<page path="/getting-started/convert-to-xr" title="Convert to XR"><![CDATA[URL: https://pmndrs.github.io/xr/getting-started/convert-to-xr
Description: How to convert an existing react-three-fiber app into an interactive immersive experience.


In case your app is already an R3F app build with natuerlich or @react-three/xr v5. Check out the migration guides for [natuerlich](../migration/from-natuerlich.md) and [@react-three/xr v5](../migration/from-react-three-xr-5.md).

The first step is to install the latest version of react-three/xr.

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

Next, we import the `createXRStore` and create a xr store.

```tsx
import { createXRStore, XR } from '@react-three/xr'

const store = createXRStore()
```

Using the `store`, we can set up a way for the user to enter the XR experience. For this example, we will just add 2 HTML buttons above your canvas.

```tsx
<>
    <button onClick={() => store.enterVR()}>Enter VR</button>
    <button onClick={() => store.enterAR()}>Enter AR</button>
    <Canvas>
 ...your scene
    </Canvas>
</>
```

Lastly, use the `store` to setup the `XR` component to wrap your scene. 

```tsx
<>
    <button onClick={() => store.enterVR()}>Enter VR</button>
    <button onClick={() => store.enterAR()}>Enter AR</button>
    <Canvas>
        <XR store={store}>
 ...your scene
        </XR>
    </Canvas>
</>
```

**Your application is now useable with an AR or VR headset.**

If something did not work as expected, check out the [FAQ](../getting-started/faq.md), create an [issue on github](https://github.com/pmndrs/react-xr/issues), or message us on [Discord](https://discord.gg/poimandres).

With this basic XR setup, you can start expanding the features of your XR application. The following questions might help you in integrating those features. 

> How do I move around in my scene?

**↳ Checkout out the tutorial about [XROrigin](../tutorials/origin.md) or [Teleportation](../tutorials/teleport.md).**

> How can I customize the way my hands/controllers/... feel, look, or interact with the scene?

**↳ Check out the tutorial about [Custom Hands/Controllers/...](../tutorials/custom-inputs.md).**

> How do interactions work in XR, and how can I build more advanced interactions?

**↳ Check out the tutorial about [Interactions](../tutorials/interactions.md)**

> How can I leverage the mixed reality features of my headset, such as Plane Detection?

**↳ Check out the tutorial about [Object Detection](../tutorials/object-detection.md)**

> What else can I do? I need inspiration.

**↳ Check out the [examples](./examples.md).**

]]></page>
<page path="/getting-started/development-setup" title="Development Setup"><![CDATA[URL: https://pmndrs.github.io/xr/getting-started/development-setup
Description: Setup your development environment for building XR experiences.


Building WebXR experiences has all the advantages of building for the web, with a lot of tool chains, debugging tools, and resources available. 
Because there are so many tools available, it is often hard to choose a development setup. Therefore, we would like to recommend you a development setup for developing with `react-three/xr`.

## 1. Build tool: [vite](https://vitejs.dev/)

Vite is easy to set up and has all the features we need. We recommend using the packages `@vitejs/plugin-react` to enable hot module reloading and `@vitejs/plugin-basic-ssl` to enable `https`, which is required for any WebXR experience.

A basic `vite.config.ts` would look like this:

```ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import basicSsl from '@vitejs/plugin-basic-ssl'

export default defineConfig({
  plugins: [react(), basicSsl()],
})
```

Now with vite and ssl setup, we can host out application by starting executing `vite --host`. The `--host` argument makes sure that the server is exposed to your local network, so you can access the app from your headset or smartphone. When starting the server, vite also shows you your local IP. Now type in this IP including the port number into your smartphone's or headset's browser (e.g. `https://192.168.0.43:5173`).

## 2. emulator: [iwer/devui](https://github.com/meta-quest/immersive-web-emulation-runtime/blob/main/devui/README.md)

Developing WebXR experiences often requires testing WebXR-specific features, which either require an actual device or an emulator. An emulator allows testing without a specific device and without continuously switching a headset on and off.

`react-three/xr` includes the [iwer/devui](https://github.com/meta-quest/immersive-web-emulation-runtime/blob/main/devui/README.md) emulator out of the box, which is in its 0.x status and very much experimental in its current stage. The emulator builds on [IWER by Meta Quest](https://github.com/meta-quest/immersive-web-emulation-runtime/) and adds a easy to use overlay on top of your application. The emulator is automatically injected if the `emulate` config has `inject` set to `true`, or if the app is served on `localhost` and if no WebXR support is detected. In case the emulator was not injected automatically, the user can inject it by pressing `Window/Command + Alt/Option + E`. After the emulator is injected, the user can press the button to enter the XR experience provided by the application.

![iwer/devui](./emulator.gif)

The existing [Immersive Web Emulator](https://chromewebstore.google.com/detail/immersive-web-emulator/cgffilbpcibhmcfbgggfhfolhkfbhmik) is a extension that provides similar emulation but its current version (1.x) is not supported because it does not comply to the WebXR spec. Starting with IWE 2.0, [iwer/devui](https://github.com/meta-quest/immersive-web-emulation-runtime/blob/main/devui/README.md) will be integrated into IWE, making it compatible with react-three/xr. If you have IWE 1.x installed and active, please turn them off, as it will prevent activiting the integrated [iwer/devui](https://github.com/meta-quest/immersive-web-emulation-runtime/blob/main/devui/README.md). 

Another supported alternative is the Apple Vision Pro Simulator.

## 3. ADB

Sometimes, a WebXR experience works flawlessly in the emulator but fails on the actual device. In this case we recommend using Android Device Bridge (ADB) to debug your experience from another device. For example, to remotely debug a WebXR experience on a Meta Quest 3, the Meta Quest 3 must be in developer mode, and remote debugging must be enabled. Then, the Meta Quest 3 must be connected to a PC via a USB cable with ADB installed. With this setup, the Chrome browser can now be used to access `chrome://inspect` to inspect specific tabs on the device remotely.

If you are using the Apple Vision Pro, there are similar features to remotely debug a WebXR experience on the Apple Vision Pro from a Safari browser on another device. 
]]></page>
<page path="/getting-started/examples" title="Examples"><![CDATA[URL: https://pmndrs.github.io/xr/getting-started/examples
Description: Examples made with @react-three/xr


<Grid cols={3}>
  <li>
    [![Screenshot from Room demo](./room-demo.gif)](https://pmndrs.github.io/xr/examples/room-with-shadows/)
  </li>
  <li>
    [![Screenshot from Stage demo](./stage-demo.gif)](https://pmndrs.github.io/xr/examples/stage/)
  </li>
  <li>
    [![Screenshot from Ragdoll demo](./ragdoll-demo.gif)](https://pmndrs.github.io/xr/examples/rag-doll/)
  </li>
  <li>
    [![Screenshot from Watch demo](./watch-demo.gif)](https://pmndrs.github.io/xr/examples/watch/)
  </li>
  <li>
    [![Screenshot from Minecraft demo](./minecraft-demo.gif)](https://pmndrs.github.io/xr/examples/minecraft/)
  </li>
  <li>
    [![Screenshot from Pingpong demo](./pingpong-demo.gif)](https://pmndrs.github.io/xr/examples/pingpong/)
  </li>
  <li>
    [![Screenshot from Layers demo](./layers.gif)](https://pmndrs.github.io/xr/examples/layers/)
  </li>
  <li>
    [![Screenshot from Secondary Input Sources demo](./secondary-input-sources.gif)](https://pmndrs.github.io/xr/examples/secondary-input-sources/)
  </li>
  <li>
    [![Screenshot from the React-three-handle Editor demo](./editor.gif)](https://pmndrs.github.io/xr/examples/editor/)
  </li>
  <li>
    [![Screenshot from the hit testing demo](./hit-testing.gif)](https://pmndrs.github.io/xr/examples/hit-testing/)
    by [Sung Powley](https://bsky.app/profile/sung-powley.bsky.social) 
  </li>
  <li>
    [![Screenshot from the uikit + handle demo](./uikit.gif)](https://pmndrs.github.io/xr/examples/uikit/)
  </li>
  <li>
    [![Screenshot from the portal demo](./portal.gif)](https://pmndrs.github.io/xr/examples/portal/)
  </li>
</Grid>
]]></page>
<page path="/getting-started/showcases" title="Showcases"><![CDATA[URL: https://pmndrs.github.io/xr/getting-started/showcases
Description: Public products build with @react-three/xr



<Grid cols={2}>
  <li>
    ![volu.dev](./showcases/volu-dev.gif)
    [Spatial development hub](https://volu.dev)
  </li>
</Grid>

Are we missing your public product? Please message us via [Twitter](https://x.com/BelaBohlender) or [Discord](https://discord.gg/poimandres).]]></page>
<page path="/getting-started/faq" title="FAQ"><![CDATA[URL: https://pmndrs.github.io/xr/getting-started/faq
Description: Frequently asked questions about react-three/xr.


## How can I read the camera position or rotation in XR?

The current global camera transformation can be accessed through `getWorldPosition` or `getWorldQuaternionn` This works inside of XR, as well as, outside of XR.

```tsx
useFrame((state) => console.log(state.camera.getWorldPosition(new Vector3())))
```

## How can I change the camera position in XR?

In contrast to non-immersive 3D applications, the camera transformation in MR/VR/AR applications should never be directly controlled by the developer since the user's head movement must control the camera's transformation. Therefore, pmndrs/xr provides the XROrigin component, which allows to control where the session's origin is placed inside the 3D scene. The session origin is at the users' feet once they recenter their session. This allows to implicitly control the camera position but prevents the user from getting motion sick when their movement is not reflected in the camera's movement.

##

## Having problems accessing the camera position or rotation.

Check if you have OrbitControls, CameraControls from `@react-three/drei`, or other controls in your scene and make sure to place an `<IfInSessionMode deny={['immersive-ar', 'immersive-vr']}>` guard around them when in XR or replace them with `OrbitHandles` or `MapHandles` from `@react-three/handle`. This prevents overwriting the camera transformation which is controlled through WebXR when inside an immersive session and allows to access the correct transformation.

```tsx
import { OrbitHandles } from '@react-three/handle'
import { noEvents, PointerEvents } from '@react-three/xr'

<Canvas events={noEvents}>
  <PointerEvents />
  <OrbitHandles />
</Canvas>
```

## I cannot enter the XR session!

1. **Missing Https**  
   If you are trying to enter the AR or VR modus and nothing is happening, make sure that you are accessing the website using `https://`.
   In case you are using vite, we recommend using the `@vitejs/plugin-basic-ssl` to try out your vite application on your device while developing.

2. **Missing XR component**  
   If you made sure that the website is accessed using `https://` and still nothing happens when executing `enterAR` or `enterVR`, it is likely that the `<XR>` component is missing. Be sure to add the `<XR>` component directly into the `<Canvas>` and make sure both the `<Canvas>` and the `<XR>` component are present when the button is pressed.

3. **Entering while loading content**  
   If you cannot enter the VR or AR experience, there might be assets in your scene that are loading.
   Make sure to place a suspense boundary around your scene. With this setup, the `<XR>` component stays mounted while your scene loads.

```tsx
<Canvas>
  <XR>
    <Suspense>... your scene</Suspense>
  </XR>
</Canvas>
```

## How can I exit an XR session?

```ts
store.getState().session?.end()
```

## Is WebGPU supported?

WebGPU is finding its way to more and more devices. However, AR and VR devices do not yet implement WebGPU for WebXR, which requires the [WebXR-WebGPU-Binding](https://github.com/immersive-web/WebXR-WebGPU-Binding/blob/main/explainer.md). Therefore, WebGPU is not yet usable for WebXR in general.

## How can I put HTML in my XR scene?

If you are targeting only handheld AR experiences (e.g., for smartphones), you can use dom overlay. Here's a [tutorial for using XRDomOverlays](../tutorials/dom-overlay.md) in your `react-three/xr` experience.

For non-handheld VR and AR experiences, you can use [react-three/uikit](https://github.com/pmndrs/uikit), which renders user interfaces directly inside the 3D scene and is aligned with HTML and CSS concepts.

## Does it work on iOS?

WebXR for VR experiences is supported on Safari for Apple Vision Pro.
WebXR is not supported on iOS Safari yet. The alternative is to use products such as [Variant Launch](https://launch.variant3d.com/), which allow to build WebXR experiences for iOS.

## XRSpace

If you are placing `<XRSpace>` components outside of the `<XROrigin>` while changing the transformation of the `<XROrigin>` (e.g. by setting `<XROrigin position={[0,1,0]} />`), the elements rendered inside of the `<XRSpace>` will not be transformed with the origin. If the transformations of the origin should be applied to the `<XRSpace>`, make sure to place those components inside the `<XROrigin>`. Not placing `<XRSpace>` components into the `<XROrigin>` can be useful in scenarios where you want to move the `<XROrigin>` independently from the `<XRSpace>`. For instance, building a virtual elevator where your actual room is duplicated into the x-axis so that you can use the elevator to travel between multiple instances of your room.

## `onClick` does not play video or allow file uploading (in certain browsers)

As a performance optimization the react-three/xr event system batches html user events per frame. This only applies if you are using `PointerEvents`, `forwardHtmlEvents`, or `forwardObjectEvents`. This can cause issue when executing functions that require a user action. For instance, uploading a file through a input element in a safari can only be triggered manually when immediately caused by a user input. For these use cases, please disable the event batching performance optimization through the options by setting `batchEvents` to `false`.
]]></page>
<page path="/tutorials/store" title="Store"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/store
Description: What is the XR Store for?


The xr store is the central part of all `@react-three/xr` experiences and allows to configure those experiences using a large set of options, control the experience using various functions, and provide access to the current state of the xr experience.

## Options

When creating a xr store, there are a lot of options that can be used for configuration.

For instance, we can use these options to disable the default controller on the left hand.

```ts
createXRStore({
  controller: { left: false },
})
```

The following tables show all the available options.

| **Property**                 | **Description**                                                                                                                                                                                                                                                                                                                                                                                | **Default Value**                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `controller`                 | Configures the `<DefaultXRController/>` or allows providing a custom implementation. You can set this for each handedness (e.g., left or right hand) individually. Setting this to `false` prevents the controllers from being used.                                                                                                                                                           | `true`                                                                           |
| `transientPointer`           | Configures the `<DefaultXRTransientPointer/>` or allows providing a custom implementation. This can be set individually for each handedness. Setting this to `false` prevents transient pointers from being used.                                                                                                                                                                              | N/A                                                                              |
| `hand`                       | Configures the `<DefaultXRHand/>` or allows providing a custom implementation. You can set this individually for each handedness. Setting this to `false` prevents hand tracking from being used.                                                                                                                                                                                              | N/A                                                                              |
| `gaze`                       | Configures the `<DefaultXRGaze/>` or allows providing a custom gaze implementation. Setting this to `false` prevents gaze-based interaction from being used.                                                                                                                                                                                                                                   | `true`                                                                           |
| `screenInput`                | Configures the `<DefaultXRScreenInput/>` or allows providing a custom screen input implementation. Setting this to `false` prevents screen input from being used.                                                                                                                                                                                                                              | `true`                                                                           |
| `emulate`                    | Emulates a specific device (e.g., "metaQuest3") using [IWER](https://github.com/meta-quest/immersive-web-emulation-runtime/) if WebXR is not supported and running on `"localhost"` or pressing `Window/Command + Alt/Option + E`. It can also be set to `false` to disable emulation.                                                                                                         | `"metaQuest3"`                                                                   |
| `frameRate`                  | Sets the session's framerate, with options such as `"high"` for smoother performance.                                                                                                                                                                                                                                                                                                          | `"high"`                                                                         |
| `foveation`                  | Sets the WebXR foveation level between `0` (no foveation) and `1` (maximum foveation). If `undefined`, the device/browser's default foveation setting is used.                                                                                                                                                                                                                                 | `undefined`                                                                      |
| `frameBufferScaling`         | Adjusts the framebuffer scaling of the session. If undefined, the device/browser's default scaling is used (typically `1`).                                                                                                                                                                                                                                                                    | `undefined`                                                                      |
| `enterGrantedSession`        | Automatically enters session modes when granted by the system without manually requesting a session. It can be an array of session modes or a boolean value to enable/disable this feature.                                                                                                                                                                                                    | `true`                                                                           |
| `baseAssetPath`              | Specifies the path to load the controller and hand models, and controller profiles from a CDN or local source.                                                                                                                                                                                                                                                                                 | `'https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/'` |
| `defaultControllerProfileId` | Specifies the fallback profile ID for the controller if no matching profile is found. It is useful for ensuring basic functionality when a specific controller profile isn't available.                                                                                                                                                                                                        | `'generic-trigger'`                                                              |
| `defaultXRHandProfileId`     | Specifies the fallback profile ID for hand tracking if no matching profile is found. It ensures basic hand-tracking functionality.                                                                                                                                                                                                                                                             | `'generic-hand'`                                                                 |
| `originReferenceSpace`       | Defines the reference space type for the origin, such as `'local-floor'` or `'bounded-floor'`. Determines how the user's position is tracked in the XR environment.                                                                                                                                                                                                                            | N/A                                                                              |
| `bounded`                    | Enables or disables the session bounds. `false` means unbounded (only available in AR). `true` means bounded (allows to reference the bounding space). `undefined` means bounded but no access to bounding space.                                                                                                                                                                              | `undefined`                                                                      |
| `anchors`                    | Enables or disables anchors, which are fixed points in the XR environment that can be used to attach virtual objects.                                                                                                                                                                                                                                                                          | `true`                                                                           |
| `handTracking`               | Enables or turns off hand-tracking in the session, allowing users to interact with the XR environment using their hands.                                                                                                                                                                                                                                                                       | `true` (`false` for Apple Vision Pro)                                              |
| `layers`                     | Enables or turns off the use of layers in the session, which can enhance rendering performance by stacking visual content.                                                                                                                                                                                                                                                                     | `true`                                                                           |
| `meshDetection`              | Enables or turns off mesh detection, allowing the system to recognize and interact with real-world objects by detecting their mesh.                                                                                                                                                                                                                                                            | `true`                                                                           |
| `planeDetection`             | Enables or turns off plane detection, allowing the system to recognize flat surfaces like floors and tables.                                                                                                                                                                                                                                                                                   | `true`                                                                           |
| `depthSensing`               | Enables or disables depth sensing in the session, which can enhance realism by occluding virtual objects from real-world objects.                                                                                                                                                                                                                                                              | `false`                                                                          |
| `customSessionInit`          | Overrides the session initialization object with custom settings. Use with caution, as it can significantly alter the behavior of the XR session.                                                                                                                                                                                                                                              | `undefined`                                                                      |
| `hitTest`                    | Enables or turns off hit testing, which allows the system to detect where the user's input (e.g., a tap or gaze) intersects with objects in the XR environment.                                                                                                                                                                                                                                | `true`                                                                           |
| `domOverlay`                 | Enables or turns off DOM overlay in the session or provides a custom DOM element for the overlay, allowing HTML content to be rendered within the XR environment.                                                                                                                                                                                                                              | `true`                                                                           |
| `secondaryInputSources`      | Enables non-primary (secondary input / tracked) sources. For example, when the device supports hands and controllers, the controllers can be used while the hands are tracked as primary input sources. This can allow to use the tracked controllers for other inputs.                                                                                                                        | `false`                                                                          |
| `offerSession`               | If not set to `false`, a session request is automatically send to the browser which can provide a custom ui for the user to start the XR experience. If set to `true` the system will request an `"immersive-ar"` session if supported, else an `"immersive-vr"` session. Alterantively offer session can be directly configured to only enter a `"immersive-vr"` or `"immersive-vr"` session. | `true`                                                                           |

## Functions

The xr store provides a large set of functions to modify and control the xr store. For instance, key functions are the `store.enterAR` and `store.enterVR` functions. The following table gives an overview of the complete set of functions that the xr store provides.

| **Function**                                       | **Description**                                                                                                                                                                                                                            |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `destroy()`                                        | Irreversibly destroys the XR store.                                                                                                                                                                                                        |
| `enterXR(mode)`                                    | Initiates an XR session in the specified mode (such as `immersive-ar` or `immersive-vr`). The function returns a promise that eventually resolves with the XR session or `undefined` if the session fails to start.                        |
| `enterAR()`                                        | Starts an Augmented Reality (AR) session. The function returns a promise that eventually resolves with the AR session or `undefined` if AR is not supported.                                                                               |
| `enterVR()`                                        | Starts a Virtual Reality (VR) session. The function returns a promise that eventually resolves with the VR session or `undefined` if VR is not supported.                                                                                  |
| `onSessionEnd(callback)`                           | Subscribes to the session ending, whether through calling `session.end()` or through hardware/OS triggered termination (e.g. the user removing the headset, the browser closing the session, ...). Returns a function to unsubscribe. Prefer this over `session.addEventListener('end', ...)`, since the session reference can go stale across re-renders. |
| `setHand(implementation, handedness?)`             | Updates the hand tracking configuration or implementation. You can target both hands or specify the handedness (`left` or `right`). This allows customization or updates to the hand implementation or configuration during runtime.       |
| `setController(implementation, handedness?)`       | Updates the controller configuration or implementation. You can target both hands or specify the handedness (`left` or `right`). This enables dynamic updates to the controller setup.                                                     |
| `setGaze(implementation)`                          | Updates the gaze-based interaction configuration or implementation. This function is used to modify the gaze implementation or configuration.                                                                                              |
| `setScreenInput(implementation)`                   | Updates the screen input configuration or implementation. This function modifies how screen inputs are handled within the XR session.                                                                                                      |
| `setTransientPointer(implementation, handedness?)` | Updates the transient pointer configuration or implementation. You can target both hands or specify the handedness.                                                                                                                        |
| `setFrameRate(value)`                              | Sets the framerate of the XR session, adjusting the session's performance and visual smoothness. Higher framerates can improve user experience but may require more processing power.                                                      |
| `requestFrame()`                                   | Returns a promise that resolves with the XR frame on the next render. This function is useful for synchronizing actions or processing data in the next render cycle, especially for tasks that need to be aligned with the rendering loop. |

## State

Alongside a set of functions, the xr store also provides the state of the current experience. For instance, the state of the xr store contains the current `XRSession` inside `state.session`.

The following table provides a list of properties available in the state of the xr store.

| **State Property**     | **Description**                                                                                                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `session`              | Represents the current `XRSession`. This object contains all the details and state information about the active XR session.                                                                                        |
| `originReferenceSpace` | Refers to the `XRReferenceSpace` of the origin in the current session. This space is typically set at the floor level and serves as the reference point for the user's position in the XR environment.             |
| `origin`               | Represents the 3D object that defines the session's origin. If this object is `undefined`, the origin is implicitly set at the world position `(0,0,0)`.                                                           |
| `domOverlayRoot`       | The HTML element used for DOM overlays in handheld AR experiences. This is where any content will be overlayed over the handheld AR session.                                                                       |
| `visibilityState`      | Indicates the session's visibility state, such as `"visible-blurred"` when the user sees an Operating System overlay. This property helps manage how the XR experience adjusts to different visibility conditions. |
| `frameRate`            | Represents the configured framerate for the XR session. Note that the actual framerate might be lower if the system cannot maintain the desired performance level.                                                 |
| `mode`                 | Specifies the current XR session mode, such as `immersive-vr`, `immersive-ar`, or `inline`. If no session is active, this will be `null`.                                                                          |
| `detectedPlanes`       | A read-only array of `XRPlane` objects representing the planes detected in the XR environment. These could include surfaces like floors, walls, and tables.                                                        |
| `detectedMeshes`       | A read-only array of `XRMesh` objects representing the meshes detected in the XR environment. These are typically 3D objects that have been identified and tracked during the session.                             |

## useXR

The `useXR` hook allows to retrieve the state from the xr store. For instance, `const session = useXR(xr => xr.session)` allows us to always get the current session from any component that is placed inside the `<XR>` component.
]]></page>
<page path="/tutorials/interactions" title="Interactions"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/interactions
Description: Build interactions that work across XR and non-XR web applications


On this page, you can learn the basics behind pointer events and interactions in react-three/xr. From experience, we found that many people are interested in more high level interactions, which can be build with the concept of handles. Check out the [handles pages](../handles/introduction.md) to learn more about the concept and the library we built for it.

@react-three/xr uses the same pointer events as @react-three/fiber, which allows building interactions that work on non-XR devices as well as XR devices. So, just like you'd expect from @react-three/fiber and everywhere else in react, interactions are built using

- `onPointerMove`
- `onPointerCancel`
- `onPointerDown`
- `onPointerUp`
- `onPointerEnter`
- `onPointerLeave`
- `onPointerOver`
- `onPointerOut`
- `onClick`
- `onDblClick`
- `onContextMenu`
- `onWheel`

The following example shows how to bind an `onClick` handler to a mesh that gets executed when the mesh is clicked. This interaction will work in non-XR devices as well as in XR devices using @react-three/xr.

```tsx
<mesh onClick={(event) => console.log("I've been clicked", event)}>
  <boxGeometry />
</mesh>
```

The `event` object provided to the onClick handler contains useful information, such as the intersection `point` in world space.

The way pointer events are handled can be configured using the `pointerEvents`, `pointerEventsType`, and `pointerEventsOrder` properties, which are available on all threejs objects.

The `pointerEvents` property corresponds to the `pointerEvents` property of CSS, which allows to completely disable pointer events for an element and its children. However, children can also re-enable pointer events by setting `pointerEvents="auto"`.

The `pointerEventsType` property allows to blacklist or whitelist pointer events for specific pointer types. For instance, setting `pointerEventsType={{ deny: "grab" }}` prevents triggering pointer events from grabbing the object or any of its children.

The `pointerEventsOrder` allows to overwrite the sorting order, similar to how `renderOrder` allows to overwrite the rendering order in threejs. The default pointer events order is `0`. Setting it to a value greater than `0` will ensure it is intersected before anything with a lower pointer events order. Setting `pointerEventsOrder` is helpful for building an interactive x-ray object that is always rendered above anything else and should, therefore, always be interacted with first. For instance, this can be used to build controls that are overlayed over the object that they control.

## Pointer Capture

Another concept that @react-three/fiber leverages from the web is pointer captures. Pointer captures allow to force all consecutive events to be emitted to a specific object, even if that object is not intersected. This is useful for building dragging interactions without a complex global state. Typically, a pointer capture is set using `object.setPointerCapture` in the event handler of `onPointerDown` with the `pointerId` of the pointer that pressed on the object.

.The following example illustrates how pointer events can be built to create a simple dragging implementation (that only works if the mesh is not inside a transformed group).

```tsx
function DraggableCube() {
  const isDraggingRef = useRef(false)
  const meshRef = useRef<Mesh>(null)

  return (
    <mesh
      ref={meshRef}
      onPointerDown={(e) => {
        if (isDraggingRef.current) {
          return
 }
        isDraggingRef.current = true
        meshRef.position.copy(e.point)
 }}
      onPointerMove={(e) => {
        if (!isDraggingRef.current) {
          return
 }
        meshRef.position.copy(e.point)
 }}
      onPointerUp={(e) => (isDraggingRef.current = false)}
    >
      <boxGeometry />
    </mesh>
 )
}
```
]]></page>
<page path="/tutorials/object-detection" title="Object Detection"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/object-detection
Description: Use detected objects such as meshes and planes for rendering, scene understanding, physics, and more


@react-three/xr allows to use the devices mesh and plane detection functionality to detect the meshes and planes in the environment to modify the rendering, allow physics interactions with the environment, and more.

## Detected Planes

The detected planes are accessible through the `useXRPlanes` hook or directly from `useXR(xr => xr.detectPlanes)` and manually go through the returned array. To render the planes in the correct place, the planes' space must provided to the `XRSpace` component. The following example shows how to render the red planes for all detected walls.

```tsx
function RedWalls() {
  const wallPlanes = useXRPlanes('wall')
  return (
    <>
      {wallPlanes.map((plane) => (
        <XRSpace space={plane.planeSpace}>
          <XRPlaneModel plane={plane}>
            <meshBasicMaterial color="red" />
          </XRPlaneModel>
        </XRSpace>
 ))}
    </>
 )
}
```

## Detected Meshes

Mesh detection provides access to the geometry of the environment. Similarly to xr planes, @react-three/fiber allows to retrieve detected meshes using `useXRMeshes` and offers the `XRMeshModel` to render the individual meshes. 
]]></page>
<page path="/tutorials/origin" title="Origin"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/origin
Description: Control the user's transformation by setting the XR session origin


The origin of an XR session is a 3D transformation that represents the position of the feet when the user recenters the session. Therefore, we recommend treating the session origin as the position of the feet. @react-three/xr provides the `XROrigin` component to control this transformation and place it anywhere inside the scene.

## Roller coaster example

Since the `XROrigin` is a react component, it can be placed anywhere, including moving objects. In the following example, we'll create an XR roller coaster.

```tsx
const store = createXRStore({
  controller: false,
})

export function App() {
  return (
    <>
      <button onClick={() => store.enterVR()}>Enter VR</button>
      <Canvas>
        <directionalLight position={[1, 1, 1]} />
        <ambientLight />
        <OrbitControls />
        <XR store={store}>
          <RollerCoaster />
        </XR>
      </Canvas>
    </>
  )
}

function RollerCoaster() {
  const gltf = useGLTF('rollercoaster.glb')

  const mixer = useMemo(() => new AnimationMixer(gltf.scene), [])
  useEffect(() => {
    for (const animation of gltf.animations) {
      mixer.clipAction(animation).play()
    }
  }, [gltf, mixer])
  useFrame((state, delta) => mixer.update(delta))
  return (
    <>
      <primitive object={gltf.scene} />
      {createPortal(
        <group rotation-y={-Math.PI / 2} rotation-x={Math.PI / 2}>
          <XROrigin scale={0.24} position-y={-0.1} />
        </group>,
        gltf.scene.getObjectByName('Sessel')!,
      )}
    </>
  )
}
```

## Resizing example

Transforming the `XROrigin` is not limited to position but can also include rotation and scale. The following example shows how the `XROrigin` can be used to achieve a resizing interaction.

```tsx
const store = createXRStore()

function App() {
  const [miniature, setMinitature] = useState(false)
  return (
    <>
      <button onClick={() => store.enterAR()}>Enter VR</button>
      <Canvas>
        <XR store={store}>
          <Gltf src="model.glb" />
          <XROrigin scale={miniature ? 0.01 : 1} position-y={miniature ? -1 : 0} />
        </XR>
      </Canvas>
    </>
  )
}
```
]]></page>
<page path="/tutorials/teleport" title="Teleportation"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/teleport
Description: Allow users to move through the scene using teleportation


First we need to enable the teleport pointer inside the hands and controllers.

```tsx
const store = createXRStore({
  hand: { teleportPointer: true },
  controller: { teleportPointer: true },
})
```

Secondly, we need to control out own state because that gives us the complete control when teleportation should be mixed with more complex behaviors. Therefore we're using `useState` to store the current position. But we can also use any other local or global state manager.

```tsx
const [position, setPosition] = useState(new Vector3())
```

Next, we need to use the position to control the user's origin.

```tsx
<XROrigin position={position}>
```

Lastly, we need to add a teleport target to our scene. In this case, we're using a simple 10x10 meter green box. We need to bind our `setPosition` function to the `onTeleport` handler of the `TeleportTarget` to update the user's position whenever the user teleports.

```tsx
<TeleportTarget onTeleport={setPosition}>
    <mesh scale={[10, 1, 10]} position={[0, -0.5, 0]}>
        <boxGeometry />
        <meshBasicMaterial color="green" />
    </mesh>
</TeleportTarget>
```

Combined, this example looks like this.

```tsx

const store = createXRStore({
  hand: { teleportPointer: true },
  controller: { teleportPointer: true },
})

export function App() {
  const [position, setPosition] = useState(new Vector3())
  return (
    <>
      <button onClick={() => store.enterVR()}>Enter VR</button>
      <Canvas>
        <XR store={store}>
          <ambientLight />
          <XROrigin position={position} />
          <TeleportTarget onTeleport={setPosition}>
            <mesh scale={[10, 1, 10]} position={[0, -0.5, 0]}>
              <boxGeometry />
              <meshBasicMaterial color="green" />
            </mesh>
          </TeleportTarget>
        </XR>
      </Canvas>
    </>
 )
}
```

![Recording of teleport example](./teleport-example.gif)]]></page>
<page path="/tutorials/gamepad" title="Gamepad"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/gamepad
Description: How to use the XRControllers gamepad?


All XR controllers are part of the state inside the xr store. The existing controllers can be read using the `useXR` hook. Alternatively, a specific xr controller can be retrived using `useXRInputSourceState("controller", "left")`.

The xr controller state contains the gamepad state. Based on the name of one specific component, its state can be polled every frame. The following example shows how to read the thumbstick of the right controller to implement locomotion in combination with the `XROrigin`.

To keep the code snipped focussed on the gamepad API, the locomotion does not happen relative to the users head rotation. This can be added by retrieving the users head position from reading the camera world quaternion and extracting the users rotation on the y axis. (There is also a [useXRControllerLocomotion](../getting-started/all-hooks.md#usexrcontrollerlocomotion) hook available to help avoid implementing locomotion from scratch if that is the end goal).

```tsx
const store = createXRStore()

export function App() {
  return (
    <>
      <button onClick={() => store.enterVR()}>Enter VR</button>
      <Canvas>
        <XR store={store}>
          <ambientLight />
          <Locomotion />
          <mesh scale={[10, 1, 10]} position={[0, -0.5, 0]}>
            <boxGeometry />
            <meshBasicMaterial color="green" />
          </mesh>
        </XR>
      </Canvas>
    </>
  )
}

function Locomotion() {
  const controller = useXRInputSourceState('controller', 'right')
  const ref = useRef<Group>(null)
  useFrame((_, delta) => {
    if (ref.current == null || controller == null) {
      return
    }
    const thumstickState = controller.gamepad['xr-standard-thumbstick']
    if (thumstickState == null) {
      return
    }
    ref.current.position.x += (thumstickState.xAxis ?? 0) * delta
    ref.current.position.z += (thumstickState.yAxis ?? 0) * delta
  })
  return <XROrigin ref={ref} />
}
```
]]></page>
<page path="/tutorials/secondary-input-sources" title="Secondary Input Sources"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/secondary-input-sources
Description: How to use primary and secondary input sources (multiple controllers and hands) simultaneously?


Most standalone XR headsets support hand and controller tracking. While typical XR experiences often support both input methods, they only use the primary inputs, which refers to one input per hand and limits the inputs to `2`. However, the headset often also tracks the secondary input sources. By enabling the `secondaryInputSources` flag when creating an xr store, we can access the secondary input sources and use them to track real-world objects, for example.

```ts
createXRStore({ secondaryInputSources: true })
```

Secondary input sources are exposed to the developer just like primary input sources, with the exception of the `isPrimary` flat, which is false. The following example illustrates how to show the primary input controllers using the default controller components while rendering the secondary input controllers as simple cubes.

```tsx
createXRStore({
  secondaryInputSources: true,
  controller: () => {
    const { isPrimary } = useXRInputSourceStateContext('controller')
    if (isPrimary) {
      return <DefaultXRController />
    }
    return (
      <mesh>
        <boxGeometry />
      </mesh>
    )
  },
})
```
]]></page>
<page path="/tutorials/layers" title="Layers"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/layers
Description: How to use display images, videos, and custom renders at high quality on quad, cylinder, and equirect shapes?


Layers allow to render videos, images, and complete scenes with higher performance and higher quality while preserving battery life and latency for quad, cylinder, and equirect shapes using the WebXR Layer API. Layers are perfect for use cases that display flat, high-quality content, such as videos, images, and user interfaces. The following example illustrates how to create a layer that renders a video.

First, we create a layer at `0, 1.5, -0.5` with a scale of `0.5` that displays a video assigned to `src` and starts that video when clicked.

```tsx
<XRLayer position={[0, 1.5, -0.5]} onClick={() => video.play()} scale={0.5} src={video} />
```

The assigned video is an HTML video element that is loaded from `test.mp4`.

```tsx
const video = useMemo(() => {
  const result = document.createElement('video')
  result.src = 'test.mp4'
  return result
}, [])
```

Combined, the final app looks like this

```tsx
export function App() {
  const video = useMemo(() => {
    const result = document.createElement('video')
    result.src = 'test.mp4'
    return result
  }, [])
  return (
    <Canvas>
      <XR store={store}>
        <XRLayer position={[0, 1.5, -0.5]} onClick={() => video.play()} scale={0.5} src={video} />
      </XR>
    </Canvas>
  )
}
```

Instead of images and videos, Layers can also be used to display dynamically rendered content. The following example illustrates how to render a red cube onto the layer. This scene will be re-rendered every frame, allowing for fully dynamic content.

```tsx
<XRLayer position={[0, 1.5, -0.5]} scale={0.5}>
  <mesh>
    <boxGeometry />
    <meshBasicMaterial color="red" />
  </mesh>
</XRLayer>
```
]]></page>
<page path="/tutorials/custom-inputs" title="Custom Hands/Controllers/..."><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/custom-inputs
Description: Customize interactions and style of inputs such as hands, controllers, and more


@react-three/xr provides a set of default hands, controllers, transient pointers, gazes, and screen input that can be configured and completely exchanged with your own implementation. The following example shows how to configure the ray color of the ray pointer in the users hand.

```tsx
const store = createXRStore({ hand: { rayPointer: { rayModel: { color: 'red' } } } })
```

In some cases, the default hand/controller/... implementations are not enough. The following code sample shows how to provide your own custom hand implementation though the xr store options.

```tsx
const store = createXRStore({ hand: CustomHand })
```

## Custom Hand

Let's build our own hand implementation which renders the normal hand model but only has a touch interaction which works using the middle finger.

First we're getting the state of the hand, creating a reference to the position of the middle finger, and creating a touch pointer.

```tsx
const state = useXRInputSourceStateContext('hand')
const middleFingerRef = useRef<Object3D>(null)
const pointer = useTouchPointer(middleFingerRef, state)
```

Next, we use the `state` to place an `XRSpace` for setting up the `middleFingerRef` and add an `XRHandModel` and `PointerCursorModel` to render the hand and a cursor visualization.

```tsx
<XRSpace ref={middleFingerRef} space={state.inputSource.hand.get('middle-finger-tip')!}/>
<Suspense>
  <XRHandModel />
</Suspense>
<PointerCursorModel pointer={pointer} opacity={defaultTouchPointerOpacity} />
```

<details>
  <summary>Full Code</summary>

```tsx
export function CustomHand() {
  const state = useXRInputSourceStateContext('hand')
  const middleFingerRef = useRef<Object3D>(null)
  const pointer = useTouchPointer(middleFingerRef, state)
  return (
    <>
      <XRSpace ref={middleFingerRef} space={state.inputSource.hand.get('middle-finger-tip')!} />
      <Suspense>
        <XRHandModel />
      </Suspense>
      <PointerCursorModel pointer={pointer} opacity={defaultTouchPointerOpacity} />
    </>
  )
}
```

</details>

This tutorial also applies to building custom controllers, transient pointers, gaze, and screen input implementations.
]]></page>
<page path="/tutorials/anchors" title="Anchors"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/anchors
Description: How to create and manage anchors in your AR experience?


Anchors allow to anchor virtual objects into the physical world in AR experiences. `react-three/xr` offers a multitude of ways to create and manage anchors. A simple solution is `useXRAnchor`, which works similarly to `useState` as it returns the current anchor and a function to request a new anchor as a tuple.

```tsx
const [anchor, requestAnchor] = useXRAnchor()
```

With the `requestAnchor` function, we can request an anchor relative to the `"world"`, a `"space"`, or a `"hitTestResult"`

```tsx
requestAnchor({ relativeTo: "space", space: ... })
```

Once the anchor is created, the `useXRAnchor` hook exposes it as `anchor`. We can now use this `anchor` to put content into it using the `<XRSpace>` component.

```tsx
<XRSpace space={anchor.anchorSpace}>...your content</XRSpace>
```

The following example shows a `Anchor` component that uses the `useXRAnchor` hook and the `XRSpace` component to anchor a Box to the position of the right hand or controller when the respective hand or controller is selected (pinch/trigger).

```tsx
export function Anchor() {
  const [anchor, requestAnchor] = useXRAnchor()
  const controllerState = useXRInputSourceState('controller', 'right')
  const handState = useXRInputSourceState('hand', 'right')
  const inputSource = controllerState?.inputSource ?? handState?.inputSource
  useXRInputSourceEvent(
    inputSource,
    'select',
    async () => {
      if (inputSource == null) {
        return
      }
      requestAnchor({ relativeTo: 'space', space: inputSource.targetRaySpace })
    },
    [requestAnchor, inputSource],
  )
  if (anchor == null) {
    return null
  }
  return (
    <XRSpace space={anchor.anchorSpace}>
      <mesh scale={0.1}>
        <boxGeometry />
      </mesh>
    </XRSpace>
  )
}
```
]]></page>
<page path="/tutorials/dom-overlay" title="Dom Overlay"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/dom-overlay
Description: How to add HTML elements for hand-held AR experiences with Dom overlay?


For hand-held AR experiences, such as those using a Smartphone, WebXR offers the dom overlay capability, allowing developers to use HTML code overlayed over the experience. In case scene 3D overlays or overlays in non-handheld AR/VR experiences are needed, check out [pmndrs/uikit](https://github.com/pmndrs/uikit).

We can add dom overlay content to an experience using the `XRDomOverlay` component, which allows to write html code inside it. This HTML code will be overlayed over the hand-held AR experience.

```tsx
<XRDomOverlay
  style={{ width: '100%', height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center' }}
>
  <div style={{ backgroundColor: 'red', padding: '1rem 2rem' }}>Hello World</div>
</XRDomOverlay>
```

The following shows the complete code for a simple AR experience with a `Hello World` button that can toggle its color when clicked on. 

```tsx
const store = createXRStore()

export function App() {
  const [bool, setBool] = useState(false)
  return (
    <>
      <button onClick={() => store.enterAR()}>Enter AR</button>
      <Canvas>
        <XR store={store}>
          <ambientLight />
          <XRDomOverlay
            style={{ width: '100%', height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center' }}
          >
            <div
              style={{ backgroundColor: bool ? 'red' : 'green', padding: '1rem 2rem' }}
              onClick={() => setBool((b) => !b)}
            >
 Hello World
            </div>
          </XRDomOverlay>
        </XR>
      </Canvas>
    </>
 )
}
```
]]></page>
<page path="/tutorials/hit-test" title="Hit Test"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/hit-test
Description: How to add hit testing capabilities to your AR experiences


Hit testing is a technique that allows developers to check for intersections with real-world surfaces in AR experiences. `@react-three/xr` provides hooks and components for setting up hit testing. This tutorial covers all the hit testing hooks available in React Three XR and demonstrates how to use them effectively.

## Overview of Hit Testing Components

React Three XR provides three hooks for hit testing:

- **`useXRHitTest`** - Provides continuous hit testing with automatic frame updates
- **`useXRHitTestSource`** - Lower-level hook for creating and managing hit test sources
- **`useXRRequestHitTest`** - One-time hit test requests on demand

Additionally, React Three XR provides the `XRHitTest` component, which is a convenience wrapper for using the `useXRHitTest` hook to perform continuous hit testing.

All rays cast by these components originate from the source's position and are cast in the direction that the source object is oriented (quaternion; typically -z).

## useXRHitTest Hook

The `useXRHitTest` hook is the most commonly used hook for hit testing in the library. It automatically performs hit tests every frame and calls your callback function with the results.

**What it does:**

Sets up continuous hit testing that runs every frame, providing real-time intersection data with the real world.

**When to use it:**

Use this when you need continuous tracking of where a ray intersects with real-world surfaces, such as for cursor positioning, object placement previews, or interactive AR elements.

**Parameters:**

- `fn` - Callback function that receives hit test results and a function to retrieve the world matrix
- `relativeTo` - The object, XR space, or reference space to cast rays from. This reference must be static in your scene.
- `trackableType` - Optional parameter specifying what types of surfaces to hit test against

```tsx
const matrixHelper = new Matrix4()
const hitTestPosition = new Vector3()

function ContinuousHitTest() {
  const previewRef = useRef<Mesh>(null)

  useXRHitTest(
    (results, getWorldMatrix) => {
      if (results.length === 0) return

      getWorldMatrix(matrixHelper, results[0])
      hitTestPosition.setFromMatrixPosition(matrixHelper)
    },
    'viewer', // Cast rays from the viewer reference space. This will typically be either the camera or where the user is looking
    'plane' // Only hit test against detected planes
  )

  useFrame(() => {
    if (hitTestPosition && previewRef.current) {
      previewRef.current.position.copy(hitTestPosition)
    }
  })

  return (
      {/* Renders a sphere where the hit test intersects with the plane */}
      <mesh ref={previewRef} position={hitPosition}>
        <sphereGeometry args={[0.05]} />
        <meshBasicMaterial color="red" />
      </mesh>
  )
}
```

## XRHitTest

`XRHitTest` is a component that wraps the `useXRHitTest` hook. This makes it easier to add hit testing anywhere within your component tree.

```tsx
const matrixHelper = new Matrix4()
const hitTestPosition = new Vector3()

const store = createXRStore({
  hand: () => {
    const inputSourceState = useXRInputSourceStateContext()

    return (
      <>
        <DefaultXRHand />
        <XRHitTest
          space={inputSourceState.inputSource.targetRaySpace}
          onResults={(results, getWorldMatrix) => {
            if (results.length === 0) return
            getWorldMatrix(matrixHelper, results[0])
            hitTestPosition.setFromMatrixPosition(matrixHelper)
          }}
        />
      </>
    )
  },
})
```

`XRHitTest` has all of the same functionality as the `useXRHitTest` hook, just that it's built as a component.

## useXRHitTestSource Hook

The `useXRHitTestSource` hook provides lower-level access to hit test sources, giving you more control over when and how hit tests are performed. It is the same as the `useXRHitTest` hook, the only difference being that you have to manually check for hit test results; typically every frame, or every few frames.

**What it does:** 

Does the same thing as the `useXRHitTest` hook, but does not automatically hit test every frame.

**When to use it:**

 In most cases you should use either `useXRHitTest` or `useXRRequestHitTest`, but you can use this hook when you have a static hit test source that you only want to occasionally perform constant hit tests from. Or if you want to recreate the `useXRHitTest` behavior manually.

**Parameters:**

- `relativeTo` - The object, XR space, or reference space to cast rays from
- `trackableType` - Optional parameter specifying what types of surfaces to hit test against

**Returns:**

 A hit test source object that you can use with `frame.getHitTestResults()`

```tsx
function ManualHitTest() {
  const meshRef = useRef<Mesh>(null)
  const hitTestSource = useXRHitTestSource(meshRef)
  const [someCondition, setSomeCondition] = useState(false)
  const [hitResults, setHitResults] = useState<XRHitTestResult[]>([])

  useFrame((_, __, frame: XRFrame | undefined) => {
    // Only perform hit testing when certain conditions are met
    if (frame && hitTestSource && someCondition) {
      const results = frame.getHitTestResults(hitTestSource.source)
      setHitResults(results)
    }
  })

  return (
    <mesh ref={meshRef}>
      {/* Render hit test results. This will put spheres everywhere the hit test succeeds. In a real app don't use index as the key */}
      {hitResults.map((result, index) => {
        const matrix = new Matrix4()
        hitTestSource?.getWorldMatrix(matrix, result)
        const position = new Vector3().setFromMatrixPosition(matrix)
        return (
          <mesh key={index} position={position}>
            <sphereGeometry args={[0.05]} />
            <meshBasicMaterial color="red" />
          </mesh>
        )
      })}
    </mesh>
  )
}
```

## useXRRequestHitTest Hook

The `useXRRequestHitTest` hook provides a function for one-time hit test requests. Useful for event-driven hit testing. Cannot be called in the `useFrame` hook.

**What it does:** 

Returns a function that can perform a single hit test request when called.

**When to use it:** 

Use this for event-driven hit testing, such as when a user taps the screen, clicks a button, or performs a gesture. It's ideal for placing objects or checking intersections at specific moments.

**Returns:** 

A function that takes the same parameters as other hit test hooks and returns a promise with hit test results

```tsx
const matrixHelper = new Matrix4()
function EventDrivenHitTest() {
  const requestHitTest = useXRRequestHitTest()
  const [placedObjects, setPlacedObjects] = useState<Vector3[]>([])

  const handleTap = async () => {
    const hitTestResult = await requestHitTest('viewer', ['plane', 'mesh'])
    const { results, getWorldMatrix } = hitTestResult
    if (results?.length > 0) {
      getWorldMatrix(matrixHelper, results[0])
      const position = new Vector3().setFromMatrixPosition(matrixHelper)
      setPlacedObjects((prev) => [...prev, position])
    }
  }

  return (
    <>
      <IfInSessionMode allow={'immersive-ar'}>
        <XRDomOverlay>
          <button onClick={handleTap}>Place Object</button>
        </XRDomOverlay>
      </IfInSessionMode>

      {/* Render placed objects */}
      {placedObjects.map((position, index) => (
        <mesh key={index} position={position}>
          <sphereGeometry args={[0.1]} />
          <meshBasicMaterial color="blue" />
        </mesh>
      ))}
    </>
  )
}
```

## Trackable Types

All hit testing hooks support specifying trackable types to control what surfaces the hit tests should target:

- `'plane'` - Hit test against detected planes (floors, walls, tables)
- `'point'` - Hit test against feature points in the environment
- `'mesh'` - Hit test against detected meshes (requires mesh detection support)

You can specify a single type or an array of types:

```tsx
// Single type
useXRHitTest(callback, spaceRef, 'plane')

// Multiple types
useXRHitTest(callback, spaceRef, ['plane', 'mesh'])
```

## Practical Example: Object Placement

Here's a complete example combining multiple hooks for a robust object placement system:

```tsx
const matrixHelper = new Matrix4()
const hitTestPositionHelper = new Vector3()

function ObjectPlacement() {
  const [placedObjects, setPlacedObjects] = useState<Vector3[]>([])
  const [previewPosition, setPreviewPosition] = useState<Vector3 | null>(null)
  const controllerRef = useRef<Group>(null)

  // Continuous hit testing for preview
  useXRHitTest(
    (results, getWorldMatrix) => {
      if (results.length > 0) {
        getWorldMatrix(matrixHelper, results[0])
        const position = hitTestPositionHelper.setFromMatrixPosition(matrixHelper)
        setPreviewPosition(position)
      } else {
        setPreviewPosition(null)
      }
    },
    'viewer', // Use viewer space for screen-based hit testing
  )

  const placeObject = async () => {
    if (previewPosition) {
      setPlacedObjects((prev) => [...prev, previewPosition.clone()])
    }
  }

  return (
    <>
      {/* Preview object at hit test position */}
      {previewPosition && (
        <mesh position={previewPosition}>
          <sphereGeometry args={[0.05]} />
          <meshBasicMaterial color="yellow" transparent opacity={0.7} />
        </mesh>
      )}

      {/* Placed objects */}
      {placedObjects.map((position, index) => (
        <mesh key={index} position={position}>
          <sphereGeometry args={[0.05]} />
          <meshBasicMaterial color="green" />
        </mesh>
      ))}

      {/* Placement trigger */}
      <IfInSessionMode allow={'immersive-ar'}>
        <XRDomOverlay>
          <button onClick={placeObject}>Place Object</button>
        </XRDomOverlay>
      </IfInSessionMode>
    </>
  )
}
```

Alternatively, for devices that provide mesh detection -- such as newer Meta Quest devices -- you can also add normal pointer event listeners to an XR Mesh to achieve the same behavior. Check out [this tutorial](./object-detection.md) for more information about mesh detection.
]]></page>
<page path="/tutorials/guards" title="Guards"><![CDATA[URL: https://pmndrs.github.io/xr/tutorials/guards
Description: Render and show parts of your application conditionally using guards


Guards allow to conditionally display or include content. For instance, the `IfInSessionMode` guard allows only displaying a background when the session is not an AR session. The `IfInSessionMode` can receive either a list of `allow` session modes or a list of `deny` session modes.

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

const store = createXRStore()

export function App() {
  return (
    <>
      <button onClick={() => store.enterAR()}>Enter AR</button>
      <Canvas>
        <XR store={store}>
          <IfInSessionMode deny="immersive-ar">
            <color args={['red']} attach="background" />
          </IfInSessionMode>
        </XR>
      </Canvas>
    </>
 )
}
```
]]></page>
<page path="/advanced/performance" title="Performance"><![CDATA[URL: https://pmndrs.github.io/xr/advanced/performance
Description: Important considerations for building performant immersive web applications with react-three/xr


All performance optimizations for non-immersive 3D web applications are also applicable for immersive XR web applications. Relevant guides on the topic of performance for 3D web applications are the [R3F performance guide](https://docs.pmnd.rs/react-three-fiber/advanced/scaling-performance), [R3F performance pitfalls](https://docs.pmnd.rs/react-three-fiber/advanced/pitfalls), and the [Threejs tips and tricks](https://discoverthreejs.com/tips-and-tricks/#performance). In general, it is good to check if your web application's performance is GPU- or CPU-bound to select the correct optimization techniques.

When it comes to immersive XR web applications, there are a few other options to improve GPU performance. We also recommend taking a look at this [WebXR Performance Optimization guide](https://developer.oculus.com/documentation/web/webxr-perf/). 

## Frame Buffer Scaling

The frame buffer scaling factor allows to control the size of the frame buffer your web application draws to. Decreasing this number can improve performance but reduces the resolution. A frame buffer scaling factor of 1.0 sets the frame buffer resolution to the native display resolution.

## Foveation

Foveation allows rendering with a lower resolution at the edges of the eye's viewport to improve GPU performance. If your application is optimized and the performance is still GPU bound, consider increasing the foveation to improve performance.]]></page>
<page path="/advanced/render-targets" title="Render Targets"><![CDATA[URL: https://pmndrs.github.io/xr/advanced/render-targets
Description: How to render offscreen content to a render target while an XR session is active


Rendering to a `WebGLRenderTarget` during an immersive XR session needs one extra step compared to a non-XR render loop. Three.js replaces the active camera and framebuffer while `gl.xr.enabled` and `gl.xr.isPresenting` are active, so an offscreen pass should temporarily disable XR rendering, render into the target, and then restore the previous renderer state.

The important part is to save and restore the render target, viewport, and XR flags around the offscreen render:

```tsx
import { useFrame, useThree } from '@react-three/fiber'
import { useMemo } from 'react'
import { PerspectiveCamera, Scene, Vector4, WebGLRenderTarget } from 'three'

const viewport = new Vector4()

function RenderTargetPass() {
  const { gl } = useThree()

  const target = useMemo(() => new WebGLRenderTarget(1024, 1024), [])
  const scene = useMemo(() => new Scene(), [])
  const camera = useMemo(() => new PerspectiveCamera(50, 1, 0.1, 100), [])

  useFrame(() => {
    const previousTarget = gl.getRenderTarget()
    const previousXrEnabled = gl.xr.enabled
    const previousIsPresenting = gl.xr.isPresenting

    gl.getViewport(viewport)

    gl.xr.enabled = false
    gl.xr.isPresenting = false
    gl.setRenderTarget(target)
    gl.setViewport(0, 0, target.width, target.height)
    gl.render(scene, camera)

    gl.setRenderTarget(previousTarget)
    gl.setViewport(viewport)
    gl.xr.enabled = previousXrEnabled
    gl.xr.isPresenting = previousIsPresenting
  })

  return null
}
```

If you are rendering content for an `XRLayer`, prefer the layer API instead of wiring this manually. `XRLayer` accepts children for dynamic content and uses the same state-preserving offscreen render pattern internally.

```tsx
<XRLayer position={[0, 1.5, -0.5]} scale={0.5}>
  <mesh>
    <boxGeometry />
    <meshBasicMaterial color="red" />
  </mesh>
</XRLayer>
```

Use a manual render target when you need the resulting texture for a material, post-processing pass, portal, minimap, or another non-layer effect. Use `XRLayer` when the goal is to display high-quality flat, cylinder, or equirect content in XR.
]]></page>
<page path="/handles/introduction" title="Handles"><![CDATA[URL: https://pmndrs.github.io/xr/handles/introduction
Description: Easily build 3D interactions using the concept of handles


Handles are everywhere, from scrollbar thumbs to window bars to door handles.

![](./react-three-handle-gif-1.gif)

Handles make it possible to move, rotate, and scale 2D or 3D objects using intuitive gestures. `@react-three/handle` makes it super simple to build these intuitive 3D handles for XR and non-XR devices with only a few lines of code. Let's showcase that while building a 3D door.

![](./annotated-door.jpg)  
_Door model from [witnessk](https://sketchfab.com/witnessk)_

To build our door, we have two components: the door handle and the door body, which the handle should rotate when grabbed. Therefore, the door body is the handle target, on which the transformations from the handle should be applied.

We can build this door by downloading the GLTF model from Sketchfab and transforming the model into its individual parts using [gltfjsx](https://gltf.pmnd.rs/). This separates the door frame, the door body, and the door handle, allowing us to wrap the door handle with the `<Handle>` component and the door body with the `<HandleTarget>` component.

```tsx {6,10,14-15}
export function Door() {
  const { nodes, materials } = useGLTF('/door.glb')
  return (
    <group rotation={[-Math.PI / 2, 0, 0]} scale={100}>
      <group position={[-0.435, -0.101, 0.249]}>
        <HandleTarget>
          <mesh geometry={nodes.Plane001_Glossy_0.geometry} material={materials.Glossy} />
          <mesh geometry={nodes.Plane001_Door_0.geometry} material={materials.Door} />
          <mesh geometry={nodes.Plane003_Door_0.geometry} material={materials.Door} position={[0.852, 0.017, 0.782]} />
          <Handle targetRef="from-context" translate="as-rotate" rotate={{ x: false, y: false, z: [-Math.PI, 0] }}>
            <group position={[0.81, 0.043, 0.803]}>
              <mesh geometry={nodes.Circle002_Glossy_0.geometry} material={materials.Glossy} />
            </group>
          </Handle>
        </HandleTarget>
      </group>
      <mesh geometry={nodes.Plane002_Glossy_0.geometry} material={materials.Glossy} />
      <mesh geometry={nodes.Plane002_Door_0.geometry} material={materials.Door} />
    </group>
  )
}
```

Next, we need to configure the handle to rotate the door when grabbed. We instruct it to use the target from the context using `targetRef="from-context"`, making sure the transformations are applied to the door body. Additionally, we ensure that moving the handle is translated into a rotation using the `translate="as-rotate"` property. Lastly, we disable rotations on all axes except for the `z` axis and limit the rotation between -180° and 0°.

*Learn more about all the available properties for the handle component [here](./handle-component.md).*

The final result looks like this (I added an additional handle around the door handle that allows it to rotate on its own y-axis).

![](./door-handle.gif)

### Editor Example

Handles are made for all kinds of use cases, from games to professional applications, which we emphasized by building the following editor demo that uses over 40 handles for moving the elements on the screen, resizing the virtual screen, and moving the virtual camera. The nice part is that it works on all devices, ranging from mouse-driven PCs to eye-driven mixed-reality headsets (Apple Vision Pro).

![](./editor.gif)

You can check it out [here](https://pmndrs.github.io/xr/examples/editor/) and read the source code (700 LOC) [here](https://github.com/pmndrs/xr/tree/main/examples/editor/app.tsx).

### Screen Handles

A specific type of handle is the screen handle, where not an individual object is the handle, but the whole screen. Therefore, we build screen handles, which allow panning, zooming, and rotating the camera using swipe, drag, and scroll interactions. These are built on the ideas of `OrbitControls` and `MapControls` from Three.js, but respect the event system (e.g., you don't need to disable them when you drag an object) and are automatically forwarded to virtual screens, as shown in the editor demo.

Learn more about the available screen handles [here](./screen-handle-components.md).

### Prebuilt Handles

For many use cases, such as 3D editors, handles often come in specific forms, like the `TransformControls` available in Three.js. These opinionated pre-built handles have proven to be very useful, which is why `@react-three/handle` ships with implementations for `TransformHandles` and `PivotHandles`.

![](./prebuild-handles.gif)

Learn more about the available prebuilt handles [here](./screen-handle-components.md).

## Sponsors

This project is supported by a few companies and individuals building cutting-edge 3D Web & XR experiences. Check them out!

![Sponsors Overview](https://bbohlender.github.io/sponsors/screenshot.png)]]></page>
<page path="/migration/from-react-three-xr-5" title="from @react-three/xr v5"><![CDATA[URL: https://pmndrs.github.io/xr/migration/from-react-three-xr-5
Description: Migrate your application from @react-three/xr v5


The goal of @react-three/xr v6 is to align this library closer to the react-three ecosystem. We, therefore, focussed on supporting the react-three/fiber event handlers. Another focus of v6 is to reduce boilerplate and provide more defaults while also giving developers more access to the lower-level WebXR primitives. In combination, these changes allow developers to build XR experiences that interoperate with the whole react-three ecosystem using only a few lines of code. 

For everybody that is transitioning from v5 to v6, we have created a small compatibility layer that includes `XRButton`, `ARButton`, `VRButton`, `useInteraction`, `useXREvent`, `Interactive`, and `RayGrab`. However, we recommend transitioning away from the compatibility layer as the new recommended way of building with @react-three/xr is more aligned with the whole react-three ecosystem.

For the `Controllers` and `Hands` components there are not correspondances in @react-three/xr v6 since input methods such as controllers, hands, but also transient-pointers are added by default. Users can configure the default implementation of those input methods as described [here](../tutorials/custom-inputs.md). The teleportation feature of @react-three/xr v5 has also slightly changed. The new API is explained [here](../tutorials/teleport.md).]]></page>
<page path="/handles/handle-component" title="Handle Component"><![CDATA[URL: https://pmndrs.github.io/xr/handles/handle-component
Description: The Handle and HandleTarget components and their properties


The `Handle` component is the core component of the `@react-three/handle` library, which is built on the `HandleStore`. This store provides developers with more control over the current state and user interactions.

## Handle Store

The handle store manages the handle's state and translates user interactions into state modifications.

### Exposed Functions

**getState**  
Allows retrieval of the state of the current interaction. If no interaction is currently happening, `getState` returns `undefined`.

**capture**  
Normally, a pointer is captured when the user interacts with an object. The `capture` method allows programmatic initiation of an interaction without requiring user input.

**save**  
Allows saving the current state so that modifications to the handle options do not affect modifications from previous interactions.

**cancel**  
Normally, an interaction is canceled when the user releases the button that started the interaction. The `cancel` function allows programmatic cancellation of the interaction.

## Handle Component

**Example**
```tsx
<Handle translate="as-scale" scale={{ uniform: true }}>
    <mesh>
        <boxGeometry />
    </mesh>
</Handle>
```
*Allows scaling of the cube by dragging it outward from the cube's center.*

### Properties

**handleRef**  
Allows overriding to pass a custom handle object.

**targetRef**  
Allows to pass in a ref to an object that should be the target of the handle. Alternatively `targetRef` can be set to `"from-context"` use the target provided by a surrounding `HandleTarget` component.

**getHandleOptions**  
Allows passing a function that dynamically generates options to override the current handle options.

**bind**  
Allows disabling automatic binding of the event listeners to the provided handle, which can be necessary when capturing pointers manually.

**apply**  
The `apply` function is used to apply a state modification that originates from a user interaction to the state. This property allows overriding the default apply function, giving the developer complete control over how modifications affect the state. For instance, instead of applying the modification directly, the developer can apply it to their own state management solution. The state management solution can then apply the modification to the handle target.

**projectRays**  
Allows to configure whether rays from input devices should be projected onto the interaction space (3D plane or 3D Line).

**alwaysUpdate**  
In situations where the handle target is placed inside a constantly changing group, the `alwaysUpdate` flag ensures that the handle target's transformation is updated every frame to reflect the current state of the handle.

**multitouch**  
By default, handles can be interacted with using multiple input devices. By setting `multitouch` to `false`, only the first input device will be used.

**filter**  
Allows to filter interactions based on the event. Return `false` to ignore the event.

**stopPropagation**  
By default, events that occur on handles are not propagated upwards and therefore do not reach their ancestors. Setting `stopPropagation` to `false` will re-enable event propagation for events that occur on the handle.

**rotate**  
The `rotate` property allows configuring if and how the user can rotate the target. Setting `rotate` to `false` disables rotation. Setting `rotate` to `x` restricts rotation to the x-axis. Setting `rotate` to `{ x: false, y: [0, Math.PI] }` disables rotation on the x-axis and restricts rotation on the y-axis to be between 0 and 180°, while rotation on the z-axis is enabled.

**scale**  
The `scale` property allows configuring if and how the user can scale the target. Setting `scale` to `false` disables scaling. Setting `scale` to `x` restricts scaling to the x-axis. Setting `scale` to `{ x: false, y: [1, 2] }` disables scaling on the x-axis and restricts the scaling factor on the y-axis to be between 1 and 2, while scaling on the z-axis is enabled.

**translate**  
The `translate` property allows configuring if and how the user can translate the target. Setting `translate` to `false` disables translation. Setting `translate` to `x` restricts translation to the x-axis. Setting `translate` to `{ x: false, y: [-1, 1] }` disables translation on the x-axis and restricts translation on the y-axis to be between -1 and 1, while translation on the z-axis is enabled. Furthermore, the `translate` property can be configured to transform translations into rotations and/or scalings using `translate="as-scale"`, allowing the user to scale the target by grabbing and moving the handle.

**ref**  
Allows retrieval of a reference to the internal handle store (`<Handle ref={handleStoreRef}>`).

## Handle Target Component

The `HandleTarget` component allows declaratively specifying a handle target that is hierarchically above the `Handle` component. To prevent accidentally providing a different target to a handle, using the target from the context requires setting `targetRef="from-context"` on the `Handle` component.

**Example**
```tsx
<HandleTarget>
    <group>
        <mesh>
            <boxGeometry />
            <Handle targetRef="from-context">
                <mesh position-x={2}>  
                    <boxGeometry />
                </mesh>
            </Handle>
        </mesh>
    </group>
</HandleTarget>
```]]></page>
<page path="/migration/from-natuerlich" title="from Natuerlich"><![CDATA[URL: https://pmndrs.github.io/xr/migration/from-natuerlich
Description: Migrate your application from natuerlich


@react-three/xr is inspired by natuerlich, and therefore, many things are similar, especially the way interactions are handled. However, a few things have been changed and renamed.

- use `XROrigin` instead of `ImmersiveSessionOrigin`
- use `<Canvas><XR>...</XR></Canvas>` instead of `XRCanvas`
- configure settings such as `foveation` through `createXRStore`
- use `store.enterXR` instead of `useEnterXR`
- use `DragControls` **TBD** instead of `Grabbale`
- don't add hands and controllers yourself, and configure them through the `createXRStore` options. Click [here](../tutorials/custom-inputs.md) for more info regarding controller/hand/... customization.
- use teleport as described [here](../tutorials/teleport.md)
]]></page>
<page path="/handles/prebuild-handles" title="Prebuilt Handles for Editor Use Cases"><![CDATA[URL: https://pmndrs.github.io/xr/handles/prebuild-handles
Description: The Handle and HandleTarget components and their properties


The `Handle` component allows for the orchestration of multiple handles together to achieve interactions typically found in 3D editors, such as the `TransformControls` offered by Three.js. Since these prebuilt handles are commonly used, `@react-three/handles` includes two of them: `TransformHandles` (based on TransformControls from Three.js) and `PivotHandles` (based on PivotControls from @react-three/drei). These prebuilt handles can be used in XR and non-XR environments, are highly configurable for use cases including multi-user editing, can be utilized through virtual screens, and respect the event system of the scene, preventing accidental interactions with multiple objects at once.

Using the `TransformHandles` and `PivotHandles` in React Three Fiber requires disabling the built-in event system and adding the event system of `@react-three/xr`.

```tsx
import { TransformHandles } from '@react-three/handle'
import { noEvents, PointerEvents } from '@react-three/xr'

<Canvas events={noEvents}>
  <PointerEvents />
  <TransformHandles>
    <mesh>
      <boxGeometry />
    </mesh>
  </TransformHandles>
</Canvas>
```

## Transform Handles  
*Alias for `TransformControls`*

![](./transform.gif)

### Properties

**alwaysUpdate**  
In situations where the transform handles are placed inside a constantly changing group, the `alwaysUpdate` flag ensures that the transform handles' transformation is updated every frame to reflect the current state of the handle.

**apply**  
Allows overriding the default apply function, giving the developer complete control over how modifications affect the state. For instance, instead of applying the modification directly, the developer can apply it to their own state management solution. The state management solution can then apply the modification to the handle target.

**stopPropagation**  
Setting `stopPropagation` to `false` will re-enable event propagation for events that occur on the handles.

**space**  
Allows configuring whether the transformations should happen in `"local"` or `"world"` space. This property has no effect when the `mode` property is set to `scale`, as scaling must occur on the local axis.

**mode**  
Allows configuring whether the transformation should be `"translate"`, `"rotate"`, or `"scale"`, which also changes the visualization of the transform handles.

**x**  
Allows configuring the transformation on the x-axis. Setting `x` to `false` disables transformations on the x-axis and also hides the respective user interface.

**y**  
Allows configuring the transformation on the y-axis. Setting `y` to `false` disables transformations on the y-axis and also hides the respective user interface.

**z**  
Allows configuring the transformation on the z-axis. Setting `z` to `false` disables transformations on the z-axis and also hides the respective user interface.

**e**  
The `e` axis represents the axis for rotating the transform handles in screen space, which is only available when `mode` is set to `rotation`. Setting `e` to `false` disables rotation in screen space and also hides the respective user interface.

**enabled**  
Setting `enabled` to `false` momentarily disables the transform handles.

**fixed**  
By default, the transform handles have a fixed size independent of their distance from the camera, which means they scale up when they move away from the camera. Setting `fixed` to `false` will make them appear smaller when further away from the camera.

**size**  
The `size` property allows configuring the size of the transform handles, which has no effect on their contents.

## Pivot Handles  
*Alias for `PivotControls`*

In contrast to the transform handles, the pivot handles only operate in local space but allow rotation, scaling, and translation transformations simultaneously.

![](./pivot.gif)

### Properties

**scale**  
The `scale` property allows configuring if and how the user can scale the pivot handles. Setting `scale` to `false` disables scaling. Setting `scale` to `x` restricts scaling to the x-axis and only shows the user interface elements for scaling on the x-axis. Similarly, setting `scale` to `{ x: false }` hides the user interface elements for scaling on the x-axis and only allows scaling on the y- and z-axes. When scaling is allowed on all axes, a uniform scale handle is shown in addition to the per-axis handles. Scale limits such as `{ x: [0.5, 2] }` are also respected by the uniform scale handle.

**translation**  
The `translation` property allows configuring if and how the user can translate the pivot handles. Setting `translation` to `false` disables translation. Setting `translation` to `x` restricts translation to the x-axis and only shows the user interface elements for translation on the x-axis. Similarly, setting `translation` to `{ x: false }` hides the user interface elements for translation on the x-axis and only allows translation on the y- and z-axes.

**rotation**  
The `rotation` property allows configuring if and how the user can rotate the pivot handles. Setting `rotation` to `false` disables rotation. Setting `rotation` to `x` restricts rotation to the x-axis and only shows the user interface elements for rotating on the x-axis. Similarly, setting `rotation` to `{ x: false }` hides the user interface elements for rotating on the x-axis and only allows rotation on the y- and z-axes.

**alwaysUpdate**  
In situations where the pivot handles are placed inside a constantly changing group, the `alwaysUpdate` flag ensures that the pivot handles' transformation is updated every frame to reflect the current state of the handle.

**apply**  
Allows overriding the default apply function, giving the developer complete control over how modifications affect the state. For instance, instead of applying the modification directly, the developer can apply it to their own state management solution. The state management solution can then apply the modification to the handle target.

**stopPropagation**  
Setting `stopPropagation` to `false` will re-enable event propagation for events that occur on the handles.

**enabled**  
Setting `enabled` to `false` momentarily disables the pivot handles.

**fixed**  
By default, the pivot handles have a fixed size independent of their distance from the camera, which means they scale up when they move away from the camera. Setting `fixed` to `false` will make them appear smaller when further away from the camera.

**size**  
The `size` property allows configuring the size of the pivot handles, which has no effect on their contents.]]></page>
<page path="/api/deprecated_button.arbutton" title="ARButton"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_button.arbutton


> [!CAUTION]
> Deprecated: use `<button onClick={() => store.enterAR()}>` instead

> `const` **ARButton**: `ForwardRefExoticComponent`\<`Omit`\<`Omit`\<`object` & `Omit`\<`ButtonHTMLAttributes`\<`HTMLButtonElement`\>, `"children"` \| `"onError"`\> & `RefAttributes`\<`HTMLButtonElement`\>, `"ref"`\>, `"mode"`\> & `RefAttributes`\<`HTMLButtonElement`\>\>

]]></page>
<page path="/handles/screen-handle-components" title="Screen Handles"><![CDATA[URL: https://pmndrs.github.io/xr/handles/screen-handle-components
Description: Orbit and Map Handles as replacements for Orbit and Map controls


Screen handles are available for screen-based devices like smartphones and PCs and allow users to move the camera by dragging, swiping, and scrolling on the screen. Three.js directly offers `OrbitControls` and `MapControls`, which are built for this purpose, and we are building on top of their success. The main difference is that the `OrbitHandles` and `MapHandles` we provide use the event system of the scene, which means that interactions with objects in the scene prevent dragging the camera. Furthermore, the event system can forward the screen inputs on a virtual screen to a virtual camera inside a virtual scene, which is showcased in the [editor example](https://pmndrs.github.io/xr/examples/editor/).

Using the `OrbitHandles` and `MapHandles` in React Three Fiber requires disabling the built-in event system and adding the event system of `@react-three/xr`.

```tsx
import { OrbitHandles } from '@react-three/handle'
import { noEvents, PointerEvents } from '@react-three/xr'

<Canvas events={noEvents}>
  <PointerEvents />
  <OrbitHandles />
</Canvas>
```

## Orbit Handles  
*alias for `OrbitControls`*

Orbit handles allow the user to orbit around a center, which can be moved by panning with a right click or two fingers touching the screen.

### Properties

**store**  
The screen camera store contains the current state of the camera, including the position of the origin, the yaw and pitch of the camera, and the distance of the camera to the origin. By passing an external store to the Orbit Handles, you can take control of the current state of the camera from multiple sources.

**apply**  
The apply function applies the modifications to the screen camera state that occurred based on user interactions to the screen camera store. Overriding this function allows you to manually modify the screen camera store and prevent or restrict certain modifications, such as the maximum pitch angle.

**enabled**  
Allows you to disable the orbit handles momentarily by setting enabled to `false`.  

**damping**  
Allows you to configure how much the camera movement should be smoothed. Set to `true` for the default damping and `false` to disable damping.  

**camera**  
Allows you to configure the camera on which the transformation should be applied. Not setting the camera will apply the transformations to the default camera of the scene.

**rotate**  
Allows you to configure the rotation speed and a filter function to disable rotation on certain input devices. Setting rotate to `false` will disable rotation entirely.

**zoom**  
Allows you to configure the zoom speed and a filter function to disable zooming on certain input devices. Setting zoom to `false` will disable zooming entirely.

**pan**  
Allows you to configure the pan speed and a filter function to disable panning on certain input devices. Setting pan to `false` will disable panning entirely.

## Map Handles  
*alias for `MapControls`*

Map handles have the same properties and functionality as the orbit handles but move the camera's transform origin only in the X and Z plane, which is perfect for building applications with a flat map.]]></page>
<page path="/api/pointer.combinedpointer" title="CombinedPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.combinedpointer


> **CombinedPointer**(`props`): `Element`

Component for combining multiple Pointers into one so that only one pointer is active at a time

## props
---

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode`

## Returns
---
`Element`
]]></page>
<page path="/api/xr.createxrstore" title="createXRStore"><![CDATA[URL: https://pmndrs.github.io/xr/api/xr.createxrstore


> **createXRStore**(`options?`): `XRStore`\<`XRElementImplementation`\>

Starting point for each XR application.
Allows to configure the session's features and defaults such as what controllers are rendered and how they can interact with the scene

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**options?**</span>

`XRStoreOptions`

## Returns
---
`XRStore`\<`XRElementImplementation`\>

A new XR store
]]></page>
<page path="/api/default.defaultxrcontroller" title="DefaultXRController"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrcontroller


> **DefaultXRController**(`props`): `Element`

Default controller implementation with grab and ray pointers

## props
---

`DefaultXRControllerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**model**</span>

Options for configuring the controller apperance

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**grabPointer**</span>

Options for configuring the grab pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rayPointer**</span>

Options for configuring the ray pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**teleportPointer**</span>

Options for configuring the teleport pointer


## Returns
---
`Element`
]]></page>
<page path="/api/default.defaultxrcontrollergrabpointer" title="DefaultXRControllerGrabPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrcontrollergrabpointer


> `const` **DefaultXRControllerGrabPointer**: (`props`) => `ReactNode`

Grab pointer for the XRController

## props
---

`DefaultXRInputSourceGrabPointerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between `pointerdown` and `pointerup` to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a `dblclick` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers context menu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**makeDefault**</span>

Used the set the default pointer inside a combined pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**cursorModel**</span>

Properties for configuring how the cursor should look

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**radius**</span>

The size of the intersection sphere

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**customSort**</span>

Overrides the default sort function to use for sorting the intersection results


## Returns
---
`ReactNode`
]]></page>
<page path="/api/default.defaultxrgaze" title="DefaultXRGaze"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrgaze


> **DefaultXRGaze**(`props`): `Element`

Default gaze implementation with ray pointer

## props
---

`DefaultXRGazeOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between `pointerdown` and `pointerup` to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a `dblclick` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers context menu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**minDistance**</span>

Minimal distance to trigger interactions

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**linePoints**</span>

The points thay make up the shape of the ray if undefined the ray goes in a straight line

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**direction**</span>

The direction of the ray

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**cursorModel**</span>

Properties for configuring how the cursor should look


## Returns
---
`Element`
]]></page>
<page path="/api/default.defaultxrhand" title="DefaultXRHand"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrhand


> **DefaultXRHand**(`props`): `Element`

Default hand implementation with touch, grab and ray pointers

## props
---

`DefaultXRHandOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**model**</span>

Options for configuring the hand appearance

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**grabPointer**</span>

Options for configuring the grab pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rayPointer**</span>

Options for configuring the ray pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**touchPointer**</span>

Options for configuring the touch pointer


## Returns
---
`Element`
]]></page>
<page path="/api/default.defaultxrhandgrabpointer" title="DefaultXRHandGrabPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrhandgrabpointer


> `const` **DefaultXRHandGrabPointer**: (`props`) => `ReactNode`

Grab pointer for the XRHand

## props
---

`DefaultXRInputSourceGrabPointerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between `pointerdown` and `pointerup` to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a `dblclick` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers context menu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**makeDefault**</span>

Used the set the default pointer inside a combined pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**cursorModel**</span>

Properties for configuring how the cursor should look

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**radius**</span>

The size of the intersection sphere

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**customSort**</span>

Overrides the default sort function to use for sorting the intersection results


## Returns
---
`ReactNode`
]]></page>
<page path="/api/default.defaultxrhandtouchpointer" title="DefaultXRHandTouchPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrhandtouchpointer


> **DefaultXRHandTouchPointer**(`props`): `Element`

Touch pointer for the XRHand

## props
---

`DefaultXRHandTouchPointerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between `pointerdown` and `pointerup` to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a `dblclick` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers context menu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**makeDefault**</span>

Used the set the default pointer inside a combined pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**cursorModel**</span>

Properties for configuring how the cursor should look

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**hoverRadius**</span>

The size of the intersection sphere

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**downRadius**</span>

The distance to the touch center to trigger a `pointerdown` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**button**</span>

The id of the button that is triggered when touching


## Returns
---
`Element`
]]></page>
<page path="/api/default.defaultxrinputsourceraypointer" title="DefaultXRInputSourceRayPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrinputsourceraypointer


> **DefaultXRInputSourceRayPointer**(`props`): `Element`

Ray pointer for the XRInputSource

## props
---

`DefaultXRInputSourceRayPointerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between pointerdown and pointerup to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a dblclick event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers contextmenu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**makeDefault**</span>

Used the set the default pointer inside a combined pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**radius**</span>

The size of the intersection sphere

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**minDistance**</span>

Minimal distance to trigger interactions

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**linePoints**</span>

The points thay make up the shape of the ray if undefined the ray goes in a straight line

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**direction**</span>

The direction of the ray

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rayModel**</span>

Properties for configuring how the ray should look

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**cursorModel**</span>

Properties for configuring how the cursor should look


## Returns
---
`Element`
]]></page>
<page path="/api/default.defaultxrinputsourceteleportpointer" title="DefaultXRInputSourceTeleportPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrinputsourceteleportpointer


> **DefaultXRInputSourceTeleportPointer**(`props`): `Element`

Telport pointer for the XRInputSource.
Emits a downward bend ray that only interesects with meshes marked as teleportable

## props
---

`DefaultXRInputSourceTeleportPointerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between `pointerdown` and `pointerup` to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a `dblclick` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers context menu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**makeDefault**</span>

Used the set the default pointer inside a combined pointer

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**radius**</span>

The size of the intersection sphere

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**minDistance**</span>

Minimal distance to trigger interactions

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**direction**</span>

The direction of the ray

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rayModel**</span>

Properties for configuring how the ray should look

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**cursorModel**</span>

Properties for configuring how the cursor should look


## Returns
---
`Element`
]]></page>
<page path="/api/default.defaultxrscreeninput" title="DefaultXRScreenInput"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrscreeninput


> **DefaultXRScreenInput**(`props`): `Element`

Default screen-input implementation with ray pointer

## props
---

`RayPointerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between `pointerdown` and `pointerup` to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a `dblclick` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers context menu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**minDistance**</span>

Minimal distance to trigger interactions

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**linePoints**</span>

The points thay make up the shape of the ray if undefined the ray goes in a straight line

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**direction**</span>

The direction of the ray


## Returns
---
`Element`
]]></page>
<page path="/api/default.defaultxrtransientpointer" title="DefaultXRTransientPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/default.defaultxrtransientpointer


> **DefaultXRTransientPointer**(`props`): `Element`

Default transient-pointer implementation with ray pointer

## props
---

`DefaultXRTransientPointerOptions`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**clickThresholdMs**</span>

Time in milliseconds between `pointerdown` and `pointerup` to trigger a click event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**dblClickThresholdMs**</span>

Time in milliseconds between the first click and the second click to trigger a `dblclick` event

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**contextMenuButton**</span>

The button that triggers context menu events

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**minDistance**</span>

Minimal distance to trigger interactions

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**linePoints**</span>

The points thay make up the shape of the ray if undefined the ray goes in a straight line

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**direction**</span>

The direction of the ray

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**cursorModel**</span>

Properties for configuring how the cursor should look


## Returns
---
`Element`
]]></page>
<page path="/api/guard_facing-camera.iffacingcamera" title="IfFacingCamera"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_facing-camera.iffacingcamera


> **IfFacingCamera**(`props`): `Element`

Guard that only **renders** its children into the scene if the camera is facing the object.
Calculation is based on the provided angle and direction.

## props
---

`FacingCameraProps`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children**</span>

`ReactNode` The ReactNode elements to conditionally render.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**direction**</span>

[Vector3](https://threejs.org/docs/#api/en/math/Vector3) Direction vector to check against the camera's facing direction.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**angle**</span>

`number` The angle in radians to determine visibility. Defaults to `Math.PI / 2` (90 degrees).


## Returns
---
`Element`
]]></page>
<page path="/api/guard_session-mode.ifinsessionmode" title="IfInSessionMode"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_session-mode.ifinsessionmode


> **IfInSessionMode**(`props`): `null` \| `Element`

Guard that only **renders** its children to the scene based on the current session mode.
If neither `allow` nor `deny` are provided, the elements will be rendered based on whether or not any mode is currently being used.

## props
---

`InSessionModeProps`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode` The ReactNode elements to conditionally render.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**allow?**</span>

`XRSessionMode | ReadonlyArray<XRSessionMode | undefined>` The session mode(s) where the children will be rendered. If not provided, the children will be rendered in all modes except the ones in `deny`.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**deny?**</span>

`XRSessionMode | ReadonlyArray<XRSessionMode | undefined>` The session mode(s) where the children will not be rendered.


## Returns
---
`null` \| `Element`
]]></page>
<page path="/api/guard_session-supported.ifsessionmodesupported" title="IfSessionModeSupported"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_session-supported.ifsessionmodesupported


> **IfSessionModeSupported**(`props`): `null` \| `Element`

Guard that only **renders** its children to the scene based on whether the user's device supports a session mode.

## props
---

`SessionModeSupportedProps`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode` The ReactNode elements to conditionally render.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**mode**</span>

`XRSessionMode` The session mode used to determine if the children will be rendered.


## Returns
---
`null` \| `Element`
]]></page>
<page path="/api/guard_focus.ifsessionvisible" title="IfSessionVisible"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_focus.ifsessionvisible


> **IfSessionVisible**(`props`): `null` \| `Element`

Guard that only **renders** its children to the scene based on whether the current session is visible or not.
Typically used to hide/show content when operating system overlays are showing

## props
---

`SessionVisibleProps`

‎
<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode` The ReactNode elements to conditionally show.


## Returns
---
`null` \| `Element`
]]></page>
<page path="/api/deprecated_interactive.interactive" title="Interactive"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_interactive.interactive


> [!CAUTION]
> Deprecated: Just use `<group onClick... />`

> `const` **Interactive**: `ForwardRefExoticComponent`\<`object` & `RefAttributes`\<`Group`\<`Object3DEventMap`\>\>\>

]]></page>
<page path="/api/xr.notinxr" title="NotInXR"><![CDATA[URL: https://pmndrs.github.io/xr/api/xr.notinxr


> **NotInXR**(`props`): `Element`

Component for hiding the xr context to all child components. Can be used to create virtual displays and similar allowing the components inside the display to think they are not inside an XR environment, making them behave like when outside XR.

## props
---

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode`

Children to be rendered inside the context.

## Returns
---
`Element`
]]></page>
<page path="/api/pointer.pointercursormodel" title="PointerCursorModel"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.pointercursormodel


> **PointerCursorModel**(`props`): `ReactNode`

Component for rendering a cursor as a pointer

## props
---

`PointerCursorModelOptions` & `object` & `RefAttributes`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**materialClass**</span>

Class of the material to use for the cursor

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointer**</span>

Pointer to use for the cursor

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**renderOrder**</span>

Render order for the cursor


## Returns
---
`ReactNode`
]]></page>
<page path="/api/pointer.pointerraymodel" title="PointerRayModel"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.pointerraymodel


> **PointerRayModel**(`props`): `ReactNode`

Component for rendering a ray for a pointer

## props
---

`PointerRayModelOptions` & `object` & `RefAttributes`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**materialClass**</span>

Material to use for the ray

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointer**</span>

Pointer to use for the ray

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**renderOrder**</span>

Render order for the ray


## Returns
---
`ReactNode`
]]></page>
<page path="/api/deprecated_ray-grab.raygrab" title="RayGrab"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_ray-grab.raygrab


> [!CAUTION]
> Deprecated: use `DragControls` instead

> `const` **RayGrab**: `ForwardRefExoticComponent`\<`Omit`\<`object` & `RefAttributes`\<`Group`\<`Object3DEventMap`\>\>, `"ref"`\> & `RefAttributes`\<`Group`\<`Object3DEventMap`\>\>\>

]]></page>
<page path="/api/guard_facing-camera.showiffacingcamera" title="ShowIfFacingCamera"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_facing-camera.showiffacingcamera


> **ShowIfFacingCamera**(`props`): `Element`

Guard that only **shows** its children by toggling their visibility if the camera is facing the object.
Calculation is based on the provided angle and direction.

## props
---

`FacingCameraProps`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children**</span>

`ReactNode` The ReactNode elements to conditionally show.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**direction**</span>

[Vector3](https://threejs.org/docs/#api/en/math/Vector3) Direction vector to check against the camera's facing direction.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**angle**</span>

`number` The angle in radians to determine visibility. Defaults to `Math.PI / 2` (90 degrees).


## Returns
---
`Element`
]]></page>
<page path="/api/guard_session-mode.showifinsessionmode" title="ShowIfInSessionMode"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_session-mode.showifinsessionmode


> **ShowIfInSessionMode**(`props`): `Element`

Guard that only **shows** its children by toggling their visibility based on the current session mode.
If neither `allow` nor `deny` are provided, the visiblity will be based on whether or not any mode is currently being used.

## props
---

`InSessionModeProps`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode` The ReactNode elements to conditionally show.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**allow?**</span>

`XRSessionMode | ReadonlyArray<XRSessionMode | undefined>` The session mode(s) where the children will be shown. If not provided, the children will be shown in all modes except the ones in `deny`.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**deny?**</span>

`XRSessionMode | ReadonlyArray<XRSessionMode | undefined>` The session mode(s) where the children will be hidden.


## Returns
---
`Element`
]]></page>
<page path="/api/guard_session-supported.showifsessionmodesupported" title="ShowIfSessionModeSupported"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_session-supported.showifsessionmodesupported


> **ShowIfSessionModeSupported**(`props`): `Element`

Guard that only **shows** its children by toggling their visibility based on whether the user's device supports a session mode.

## props
---

`SessionModeSupportedProps`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode` The ReactNode elements to conditionally show.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**mode**</span>

`XRSessionMode` The session mode used to determine if the children will be shown.


## Returns
---
`Element`
]]></page>
<page path="/api/guard_focus.showifsessionvisible" title="ShowIfSessionVisible"><![CDATA[URL: https://pmndrs.github.io/xr/api/guard_focus.showifsessionvisible


> **ShowIfSessionVisible**(`props`): `Element`

Guard that only **shows** its children by toggling their visibility based on whether the current session is visible or not.
Typically used to hide/show content when operating system overlays are showing

## props
---

`SessionVisibleProps`

‎
<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode` The ReactNode elements to conditionally show.


## Returns
---
`Element`
]]></page>
<page path="/api/teleport.teleporttarget" title="TeleportTarget"><![CDATA[URL: https://pmndrs.github.io/xr/api/teleport.teleporttarget


> **TeleportTarget**(`props`): `Element`

Component that allows to declare its children as teleport targets.

## props
---

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onTeleport?**</span>

(`point`, `event`) => `void`

Function that is called when the teleport target is hit

## Returns
---
`Element`
]]></page>
<page path="/api/xr.unsafe_usexrstore" title="UNSAFE_useXRStore"><![CDATA[URL: https://pmndrs.github.io/xr/api/xr.unsafe_usexrstore


> **UNSAFE\_useXRStore**(): `undefined` \| `XRStore`

Returns the XR store object from a parent [XR](xr.XR.md) component. If no component is found `undefined` is returned.
You most likely should be using [useXRStore](xr.useXRStore.md) instead.

## Returns
---
`undefined` \| `XRStore`
]]></page>
<page path="/api/space.useapplyxrspacematrix" title="useApplyXRSpaceMatrix"><![CDATA[URL: https://pmndrs.github.io/xr/api/space.useapplyxrspacematrix


> **useApplyXRSpaceMatrix**(`ref`, `space`, `onFrame?`): `void`

Hook that applies the transformation of the provided xr space to the provided object reference

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**ref**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**current?**</span>

`null` \| `Group`\<`Object3DEventMap`\>

A react ref object that points to the object that the XRSpaceMatrix should be applied to

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**space**</span>

`undefined` | `XRSpace`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onFrame?**</span>

(`state`, `delta`, `frame`) => `void`

Optional callback that gets executed after the matrix of the reference object was updated

## Returns
---
`void`

## Requires

matrixAutoUpdate to be disabled for the referenced object
]]></page>
<page path="/api/space.usegetxrspacematrix" title="useGetXRSpaceMatrix"><![CDATA[URL: https://pmndrs.github.io/xr/api/space.usegetxrspacematrix


> **useGetXRSpaceMatrix**(`space`): `undefined` \| (`target`, `frame`) => `boolean`

Hook that returns a function to compute a matrix that contains the transformation of the provided xr space

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**space**</span>

`undefined` | `XRSpace`

## Returns
---
`undefined` \| (`target`, `frame`) => `boolean`
]]></page>
<page path="/api/pointer.usegrabpointer" title="useGrabPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.usegrabpointer


> **useGrabPointer**(`spaceRef`, `pointerState`, `currentOptions?`, `pointerType?`): `Pointer`

Hook for creating a grab pointer

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**spaceRef**</span>

`RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerState**</span>

`any`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**currentOptions?**</span>

`object` & `PointerOptions` & `IntersectionOptions` & `object`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerType?**</span>

`string`

## Returns
---
`Pointer`
]]></page>
<page path="/api/hooks.usehover" title="useHover"><![CDATA[URL: https://pmndrs.github.io/xr/api/hooks.usehover


## Call Signature

> **useHover**(`ref`): `boolean`

Used to track the hover state of a 3D object.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**ref**</span>

`RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

The reference to the 3D object.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`boolean`

## Call Signature

> **useHover**(`ref`, `onChange`): `void`

Used to track the hover state of a 3D object.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**ref**</span>

`RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

The reference to the 3D object.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onChange**</span>

(`hover`, `event`) => `void`

`(hover: boolean, event: PointerEvent) => void` Callback for hover state changes.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`void`
]]></page>
<page path="/api/hooks.useinitroomcapture" title="useInitRoomCapture"><![CDATA[URL: https://pmndrs.github.io/xr/api/hooks.useinitroomcapture


> **useInitRoomCapture**(): `undefined` \| () => `Promise`\<`undefined`\>

Initilizes the room capture process.

## Returns
---
`undefined`

() => `Promise`\<`undefined`\>

XRSession is extended to contain the initiateRoomCapture method which,
if supported, will ask the XR Compositor to capture the current room layout.
It is up to the XRCompositor if this will replace or augment the set of tracked planes.
The user agent MAY also ignore this call, for instance if it doesn’t support a manual room
capture more or if it determines that the room is already set up.
The initiateRoomCapture method MUST only be able to be called once per XRSession.

## Returns
---
`Promise`\<`undefined`\>

## See

https://immersive-web.github.io/real-world-geometry/plane-detection.html#plane-set

A function to initiate room capture, or undefined if unavailable.
]]></page>
<page path="/api/deprecated_hooks.useinteraction" title="useInteraction"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.useinteraction


> [!CAUTION]
> Deprecated: Use normal react-three/fiber event listeners instead (e.g. `<mesh onClick={...} />`)

> **useInteraction**(`ref`, `type`, `handler?`): `void`

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**ref**</span>

`RefObject`\<`null` \| `Group`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**type**</span>

`"onBlur"` | `"onSelect"` | `"onHover"` | `"onMove"` | `"onSelectEnd"` | `"onSelectStart"` | `"onSqueeze"` | `"onSqueezeEnd"` | `"onSqueezeStart"`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**handler?**</span>

(`event`) => `void`

## Returns
---
`void`

]]></page>
<page path="/api/pointer.uselinespointer" title="useLinesPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.uselinespointer


> **useLinesPointer**(`spaceRef`, `pointerState`, `currentOptions?`, `pointerType?`): `Pointer`

Hook for creating a ray pointer

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**spaceRef**</span>

`RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerState**</span>

`any`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**currentOptions?**</span>

`object` & `PointerOptions` & `IntersectionOptions` & `object`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerType?**</span>

`string`

## Returns
---
`Pointer`
]]></page>
<page path="/api/controller.useloadxrcontrollerlayout" title="useLoadXRControllerLayout"><![CDATA[URL: https://pmndrs.github.io/xr/api/controller.useloadxrcontrollerlayout


> **useLoadXRControllerLayout**(`profileIds`, `handedness`, `XRControllerLayoutLoaderOptions`): `XRControllerLayout`

For rendering a controller that is not included in WebXR. (e.g controller tutorials/demos)

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**profileIds**</span>

`string`[]

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**handedness**</span>

`XRHandedness`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**XRControllerLayoutLoaderOptions**</span>

`XRControllerLayoutLoaderOptions` = `{}`

## Returns
---
`XRControllerLayout`

`Promise<XRControllerLayout>`
]]></page>
<page path="/api/controller.useloadxrcontrollermodel" title="useLoadXRControllerModel"><![CDATA[URL: https://pmndrs.github.io/xr/api/controller.useloadxrcontrollermodel


> **useLoadXRControllerModel**(`layout`): `Group`\<`Object3DEventMap`\>

Loads the controller model for the given layout. This is a suspendable function, so it can be used with React Suspense.

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**layout**</span>

`XRControllerLayout`

## Returns
---
`Group`\<`Object3DEventMap`\>

`Promise<THREE.Group>`
]]></page>
<page path="/api/pointer.usepointerxrinputsourceevents" title="usePointerXRInputSourceEvents"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.usepointerxrinputsourceevents


> **usePointerXRInputSourceEvents**(`pointer`, `inputSource`, `event`, `missingEvents`): `void`

Hook for binding the xr session events such as `selectstart` to the provided pointer down/up events

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointer**</span>

`Pointer`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**inputSource**</span>

`XRInputSource`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**event**</span>

`"squeeze"` | `"select"`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**missingEvents**</span>

readonly `XRInputSourceEvent`[]

## Returns
---
`void`
]]></page>
<page path="/api/pointer.useraypointer" title="useRayPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.useraypointer


> **useRayPointer**(`spaceRef`, `pointerState`, `currentOptions?`, `pointerType?`): `Pointer`

Hook for creating a ray pointer

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**spaceRef**</span>

`RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerState**</span>

`any`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**currentOptions?**</span>

`object` & `PointerOptions` & `IntersectionOptions` & `object`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerType?**</span>

`string`

## Returns
---
`Pointer`
]]></page>
<page path="/api/anchor.userequestxranchor" title="useRequestXRAnchor"><![CDATA[URL: https://pmndrs.github.io/xr/api/anchor.userequestxranchor


> **useRequestXRAnchor**(): (...`args`) => `Promise`

Hook that returns a function that allows to request a xr anchor

## Returns
---
> (...`args`): `Promise`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**props**</span>

...\[`XRAnchorOptions`\]

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`Promise`
]]></page>
<page path="/api/hooks.usesessionfeatureenabled" title="useSessionFeatureEnabled"><![CDATA[URL: https://pmndrs.github.io/xr/api/hooks.usesessionfeatureenabled


> [!CAUTION]
> Deprecated: use `useXRSessionFeatureEnabled` instead

> `const` **useSessionFeatureEnabled**: (`feature`) => `boolean` = `useXRSessionFeatureEnabled`

Checks if a specific XR session feature is enabled.

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**feature**</span>

`string`

The XR session feature to check against.

## Returns
---
`boolean`

Whether the feature is enabled.

]]></page>
<page path="/api/hooks.usesessionmodesupported" title="useSessionModeSupported"><![CDATA[URL: https://pmndrs.github.io/xr/api/hooks.usesessionmodesupported


> [!CAUTION]
> Deprecated: use `useXRSessionModeSupported` instead

> `const` **useSessionModeSupported**: (`mode`, `onError?`) => `undefined` \| `boolean` = `useXRSessionModeSupported`

Checks whether a specific XRSessionMode is supported or not

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**mode**</span>

`XRSessionMode`

The `XRSessionMode` to check against.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onError?**</span>

(`error`) => `void`

Callback executed when an error occurs.

## Returns
---
`undefined` \| `boolean`

]]></page>
<page path="/api/pointer.usetouchpointer" title="useTouchPointer"><![CDATA[URL: https://pmndrs.github.io/xr/api/pointer.usetouchpointer


> **useTouchPointer**(`spaceRef`, `pointerState`, `currentOptions?`, `pointerType?`): `Pointer`

Hook for creating a touch pointer

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**spaceRef**</span>

`RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerState**</span>

`any`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**currentOptions?**</span>

`object` & `PointerOptions` & `IntersectionOptions` & `object`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**pointerType?**</span>

`string`

## Returns
---
`Pointer`
]]></page>
<page path="/api/xr.usexr" title="useXR"><![CDATA[URL: https://pmndrs.github.io/xr/api/xr.usexr


> **useXR**\<`T`\>(`selector`, `equalityFn?`): `T`

Hook for reading the state from the xr store

## Type Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**T**</span>

`T` = `Readonly`\<`object` & `WithRecord`\<`XRElementImplementation`\>\>

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**selector**</span>

(`s`) => `T`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**equalityFn?**</span>

(`a`, `b`) => `boolean`

## Returns
---
`T`
]]></page>
<page path="/api/anchor.usexranchor" title="useXRAnchor"><![CDATA[URL: https://pmndrs.github.io/xr/api/anchor.usexranchor


> **useXRAnchor**(): \[`XRAnchor`, (`options`) => `Promise`\<`undefined` \| `XRAnchor`\>\]

hook for requesting and storing a single xr anchor

## Returns
---
\[`XRAnchor`, (`options`) => `Promise`\<`undefined` \| `XRAnchor`\>\]
]]></page>
<page path="/api/controller.usexrcontrollerbuttonevent" title="useXRControllerButtonEvent"><![CDATA[URL: https://pmndrs.github.io/xr/api/controller.usexrcontrollerbuttonevent


> **useXRControllerButtonEvent**(`controller`, `id`, `onChange`): `void`

Hook for subscribing to a button state change event on the controller

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**controller**</span>

the controller to listen for the event

`undefined` | `XRControllerState`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**id**</span>

`XRControllerGamepadComponentId`

of the button

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onChange**</span>

(`state`) => `void`

callback that gets executed when the state of the button changes

## Returns
---
`void`
]]></page>
<page path="/api/controller-locomotion.usexrcontrollerlocomotion" title="useXRControllerLocomotion"><![CDATA[URL: https://pmndrs.github.io/xr/api/controller-locomotion.usexrcontrollerlocomotion


> **useXRControllerLocomotion**(`target`, `translationOptions`, `rotationOptions`, `translationControllerHand`): `void`

A hook for handling basic locomotion in VR

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**target**</span>

Either a `THREE.Group` ref, or a callback function. Recieves movement input (required).

`RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\> | (`velocity`, `rotationVelocityY`, `deltaTime`, `state`, `frame?`) => `void`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**translationOptions**</span>

`XRControllerLocomotionTranslationOptions` = `{}`

Options that control the translation of the user. Set to `false` to disable.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**translationOptions.speed**</span>

The speed at which the user moves.


<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rotationOptions**</span>

`XRControllerLocomotionRotationOptions` = `{}`

Options that control the rotation of the user. Set to `false` to disable.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rotationOptions.deadZone**</span>

How far the joystick must be pushed to trigger a turn.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rotationOptions.type**</span>

Controls how rotation using the controller functions. Can be either 'smooth' or 'snap'.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rotationOptions.degrees**</span>

If `type` is 'snap', this specifies the number of degrees to snap the user's view by.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**rotationOptions.speed**</span>

If `type` is 'smooth', this specifies the speed at which the user's view rotates.


<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**translationControllerHand**</span>

Specifies which hand will control the movement. Can be either 'left' or 'right'.

`"left"` | `"right"`

## Returns
---
`void`
]]></page>
<page path="/api/deprecated_hooks.usexrcontrollerstate" title="useXRControllerState"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.usexrcontrollerstate


> [!CAUTION]
> Deprecated: use `useXRInputSourceState("controller", "left")` instead

## Call Signature

> **useXRControllerState**(`handedness`): `undefined` \| `XRControllerState`

Hook for getting the XRControllerState

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**handedness**</span>

`XRHandedness`

the handedness that the XRControllerState should have

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `XRControllerState`

#
## Call Signature

> **useXRControllerState**(): `XRControllerState`

Hook for getting the XRControllerState

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`XRControllerState`

#]]></page>
<page path="/api/deprecated_hooks.usexrevent" title="useXREvent"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.usexrevent


> [!CAUTION]
> Deprecated: Implement custom listeners instead

> **useXREvent**(`type`, `handler`, `__namedParameters`): `void`

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**type**</span>

`XRInputSourceEventType`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**handler**</span>

(`event`) => `void`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**\_\_namedParameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**handedness?**</span>

`XRHandedness`

## Returns
---
`void`

]]></page>
<page path="/api/deprecated_hooks.usexrgazestate" title="useXRGazeState"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.usexrgazestate


> [!CAUTION]
> Deprecated: use `useXRInputSourceStateContext("gaze")` instead

> **useXRGazeState**(): `XRGazeState`

Hook for getting the gaze state

## Returns
---
`XRGazeState`

]]></page>
<page path="/api/deprecated_hooks.usexrhandstate" title="useXRHandState"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.usexrhandstate


> [!CAUTION]
> Deprecated: use `useXRInputSourceState("hand", "left")` instead

## Call Signature

> **useXRHandState**(`handedness`): `undefined` \| `XRHandState`

Hook for getting the XRHandState

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**handedness**</span>

`XRHandedness`

the handedness that the XRHandState should have

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `XRHandState`

#
## Call Signature

> **useXRHandState**(): `XRHandState`

Hook for getting the XRHandState

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`XRHandState`

#]]></page>
<page path="/api/hit-test.usexrhittest" title="useXRHitTest"><![CDATA[URL: https://pmndrs.github.io/xr/api/hit-test.usexrhittest


> **useXRHitTest**(`fn`, `relativeTo`, `trackableType?`): `void`

Hook for setting up a continous hit test originating from the provided object or XRSpace. The provided object must be statically positioned in the XRSpace.

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**fn**</span>

Callback function that contains the results of the hit test, and a function to retrieve the world matrix

`undefined` | (`results`, `getWorldMatrix`) => `void`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**relativeTo**</span>

The XRSpace, XRReferenceSpace, or Object3D to perform hit-tests from

`XRSpace` | `XRReferenceSpaceType` | `RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**trackableType?**</span>

A string, or array of strings that specify the types of surfaces to hit test against ('point', 'plane', 'mesh')

`XRHitTestTrackableType` | `XRHitTestTrackableType`[]

## Returns
---
`void`

## Example

```ts
const matrixHelper = new Matrix4()
const hitTestPosition = new Vector3()

function ContinuousHitTest() {
  const previewRef = useRef<Mesh>(null)

  useXRHitTest(
    (results, getWorldMatrix) => {
      if (results.length === 0) return

      getWorldMatrix(matrixHelper, results[0])
      hitTestPosition.setFromMatrixPosition(matrixHelper)
    },
    'viewer'
  )

  useFrame(() => {
    if (hitTestPosition && previewRef.current) {
      previewRef.current.position.copy(hitTestPosition)
    }
  })

  return (
      <mesh ref={previewRef} position={hitPosition}>
        <sphereGeometry args={[0.05]} />
        <meshBasicMaterial color="red" />
      </mesh>
  )
}
```

## See

 - [Hit Test Tutorial](https://pmndrs.github.io/xr/docs/tutorials/hit-test)
 - [Hit Test Example](https://pmndrs.github.io/xr/examples/hit-testing/)
]]></page>
<page path="/api/hit-test.usexrhittestsource" title="useXRHitTestSource"><![CDATA[URL: https://pmndrs.github.io/xr/api/hit-test.usexrhittestsource


> **useXRHitTestSource**(`relativeTo`, `trackableType?`): `undefined` \| \{ `getWorldMatrix`: (...`args`) => `boolean`; `source`: `XRHitTestSource`; \}

Hook for creating a hit test source originating from the provided object or XRSpace. The provided object must be statically positioned in the XRSpace.

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**relativeTo**</span>

The XRSpace, XRReferenceSpace, or Object3D to perform hit-tests from

`XRSpace` | `XRReferenceSpaceType` | `RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**trackableType?**</span>

A string, or array of strings that specify the types of surfaces to hit test against ('point', 'plane', 'mesh')

`XRHitTestTrackableType` | `XRHitTestTrackableType`[]

## Returns
---
`undefined` \| \{ `getWorldMatrix`: (...`args`) => `boolean`; `source`: `XRHitTestSource`; \}

## Example

```ts
function ManualHitTest() {
  const meshRef = useRef<Mesh>(null)
  const hitTestSource = useXRHitTestSource('viewer')
  const [someCondition, setSomeCondition] = useState(false)
  const [hitResults, setHitResults] = useState<XRHitTestResult[]>([])

  useFrame((_, __, frame: XRFrame | undefined) => {
    // Only perform hit testing when certain conditions are met
    if (frame && hitTestSource && someCondition) {
      const results = frame.getHitTestResults(hitTestSource.source)
      setHitResults(results)
    }
  })
  return (
    <IfInSessionMode allow={'immersive-ar'}>
      <XRDomOverlay>
        <button onClick={() => setSomeCondition(true)}>Turn on hit testing</button>
      </XRDomOverlay>
    </IfInSessionMode>
  )
}
```

## See

 - [Hit Test Tutorial](https://pmndrs.github.io/xr/docs/tutorials/hit-test)
 - [Hit Test Example](https://pmndrs.github.io/xr/examples/hit-testing/)
]]></page>
<page path="/api/input.usexrinputsourceevent" title="useXRInputSourceEvent"><![CDATA[URL: https://pmndrs.github.io/xr/api/input.usexrinputsourceevent


> **useXRInputSourceEvent**(`inputSource`, `event`, `fn`, `deps`): `void`

Hook for listening to xr input source events

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**inputSource**</span>

The input source to listen to, or 'all' to listen to all input sources

`undefined` | `XRInputSource` | `"all"`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**event**</span>

The event to listen to. ([List of events](https://developer.mozilla.org/en-US/docs/Web/API/XRInputSourceEvent))

`"squeeze"` | `"selectstart"` | `"select"` | `"selectend"` | `"squeezestart"` | `"squeezeend"`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**fn**</span>

(`event`) => `void`

Callback function called when the event is triggered.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**deps**</span>

`any`[]

Retriggers the binding of the event when the dependencies change.

## Returns
---
`void`
]]></page>
<page path="/api/mesh.usexrmeshes" title="useXRMeshes"><![CDATA[URL: https://pmndrs.github.io/xr/api/mesh.usexrmeshes


> **useXRMeshes**(`semanticLabel?`): readonly `XRMesh`[]

Hook for getting all detected meshes with the provided semantic label

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**semanticLabel?**</span>

`string`

## Returns
---
readonly `XRMesh`[]
]]></page>
<page path="/api/mesh.usexrmeshgeometry" title="useXRMeshGeometry"><![CDATA[URL: https://pmndrs.github.io/xr/api/mesh.usexrmeshgeometry


> **useXRMeshGeometry**(`mesh`, `disposeBuffer`): `BufferGeometry`

Hook for getting the geometry from the detected mesh

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**mesh**</span>

`XRMesh`

the detected mesh

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**disposeBuffer**</span>

`boolean` = `true`

allows to disable auto disposing the geometry buffer

## Returns
---
`BufferGeometry`
]]></page>
<page path="/api/plane.usexrplanegeometry" title="useXRPlaneGeometry"><![CDATA[URL: https://pmndrs.github.io/xr/api/plane.usexrplanegeometry


> **useXRPlaneGeometry**(`plane`, `disposeBuffer`): `BufferGeometry`

Hook for getting the geometry from the detected plane

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**plane**</span>

`XRPlane`

the detected plane

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**disposeBuffer**</span>

`boolean` = `true`

allows to disable auto disposing the geometry buffer

## Returns
---
`BufferGeometry`
]]></page>
<page path="/api/plane.usexrplanes" title="useXRPlanes"><![CDATA[URL: https://pmndrs.github.io/xr/api/plane.usexrplanes


> **useXRPlanes**(`semanticLabel?`): readonly `XRPlane`[]

Hook for getting all dected planes with the provided semantic label

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**semanticLabel?**</span>

`string`

## Returns
---
readonly `XRPlane`[]
]]></page>
<page path="/api/deprecated_hooks.usexrreferencespace" title="useXRReferenceSpace"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.usexrreferencespace


> [!CAUTION]
> Deprecated: use `useXRSpace` instead

> `const` **useXRReferenceSpace**: \{(): `XRSpace`; (`type`): `undefined` \| `XRReferenceSpace`; (`type`): `undefined` \| `XRSpace`; \} = `useXRSpace`

## Call Signature

> (): `XRSpace`

Hook for retrieving XR space from the context

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`XRSpace`

## Call Signature

> (`type`): `undefined` \| `XRReferenceSpace`

Hook for retrieving XR space from the context

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**type**</span>

`XRReferenceSpaceType`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `XRReferenceSpace`

## Call Signature

> (`type`): `undefined` \| `XRSpace`

Hook for retrieving XR space from the context

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**type**</span>

`XRSpaceType`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `XRSpace`

]]></page>
<page path="/api/hit-test.usexrrequesthittest" title="useXRRequestHitTest"><![CDATA[URL: https://pmndrs.github.io/xr/api/hit-test.usexrrequesthittest


> **useXRRequestHitTest**(): (`relativeTo`, `trackableType?`) => `undefined` \| `Promise`\<`undefined` \| \{ `getWorldMatrix`: (...`args`) => `boolean`; `results`: `XRHitTestResult`[]; \}\>

Hook that returns a function to request a single hit test. Cannot be called in the useFrame hook.

## Returns
---
> (`relativeTo`, `trackableType?`): `undefined` \| `Promise`\<`undefined` \| \{ `getWorldMatrix`: (...`args`) => `boolean`; `results`: `XRHitTestResult`[]; \}\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**relativeTo**</span>

`XRSpace` | `XRReferenceSpaceType` | `RefObject`\<`null` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**trackableType?**</span>

`XRHitTestTrackableType` | `XRHitTestTrackableType`[]

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `Promise`\<`undefined` \| \{ `getWorldMatrix`: (...`args`) => `boolean`; `results`: `XRHitTestResult`[]; \}\>

## Example

```ts
const matrixHelper = new Matrix4()
function EventDrivenHitTest() {
  const requestHitTest = useXRRequestHitTest()
  const [placedObjects, setPlacedObjects] = useState<Vector3[]>([])

  const handleTap = async () => {
    const hitTestResult = await requestHitTest('viewer', ['plane', 'mesh'])
    const { results, getWorldMatrix } = hitTestResult
    if (results?.length > 0) {
      getWorldMatrix(matrixHelper, results[0])
      const position = new Vector3().setFromMatrixPosition(matrixHelper)
      setPlacedObjects((prev) => [...prev, position])
    }
  }

  return (
    <>
      <IfInSessionMode allow={'immersive-ar'}>
        <XRDomOverlay>
          <button onClick={handleTap}>Place Object</button>
        </XRDomOverlay>
      </IfInSessionMode>

      {placedObjects.map((position, index) => (
        <mesh key={index} position={position}>
          <sphereGeometry args={[0.1]} />
          <meshBasicMaterial color="blue" />
        </mesh>
      ))}
    </>
  )
}
```

## See

 - [Hit Test Tutorial](https://pmndrs.github.io/xr/docs/tutorials/hit-test)
 - [Hit Test Example](https://pmndrs.github.io/xr/examples/hit-testing/)
]]></page>
<page path="/api/deprecated_hooks.usexrscreeninputstate" title="useXRScreenInputState"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.usexrscreeninputstate


> [!CAUTION]
> Deprecated: `useXRInputSourceStateContext("screenInput")` instead

> **useXRScreenInputState**(): `XRScreenInputState`

Hook for getting the screen-input state

## Returns
---
`XRScreenInputState`

]]></page>
<page path="/api/hooks.usexrsessionfeatureenabled" title="useXRSessionFeatureEnabled"><![CDATA[URL: https://pmndrs.github.io/xr/api/hooks.usexrsessionfeatureenabled


> **useXRSessionFeatureEnabled**(`feature`): `boolean`

Checks if a specific XR session feature is enabled.

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**feature**</span>

`string`

The XR session feature to check against.

## Returns
---
`boolean`

Whether the feature is enabled.
]]></page>
<page path="/api/hooks.usexrsessionmodesupported" title="useXRSessionModeSupported"><![CDATA[URL: https://pmndrs.github.io/xr/api/hooks.usexrsessionmodesupported


> **useXRSessionModeSupported**(`mode`, `onError?`): `undefined` \| `boolean`

Checks whether a specific XRSessionMode is supported or not

## Parameters

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**mode**</span>

`XRSessionMode`

The `XRSessionMode` to check against.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onError?**</span>

(`error`) => `void`

Callback executed when an error occurs.

## Returns
---
`undefined` \| `boolean`
]]></page>
<page path="/api/hooks.usexrsessionvisibilitystate" title="useXRSessionVisibilityState"><![CDATA[URL: https://pmndrs.github.io/xr/api/hooks.usexrsessionvisibilitystate


> **useXRSessionVisibilityState**(): `undefined` \| `XRVisibilityState`

Gets the visibility state of the XR session.

## Returns
---
`undefined` \| `XRVisibilityState`

The visibility state of the XR session.
]]></page>
<page path="/api/space.usexrspace" title="useXRSpace"><![CDATA[URL: https://pmndrs.github.io/xr/api/space.usexrspace


## Call Signature

> **useXRSpace**(): `XRSpace`

Hook for retrieving XR space from the context

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`XRSpace`

## Call Signature

> **useXRSpace**(`type`): `undefined` \| `XRReferenceSpace`

Hook for retrieving XR space from the context

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**type**</span>

`XRReferenceSpaceType`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `XRReferenceSpace`

## Call Signature

> **useXRSpace**(`type`): `undefined` \| `XRSpace`

Hook for retrieving XR space from the context

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**type**</span>

`XRSpaceType`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `XRSpace`
]]></page>
<page path="/api/xr.usexrstore" title="useXRStore"><![CDATA[URL: https://pmndrs.github.io/xr/api/xr.usexrstore


> **useXRStore**(): `XRStore`

Hook for getting the xr store from the context

## Returns
---
`XRStore`
]]></page>
<page path="/api/deprecated_hooks.usexrtransientpointerstate" title="useXRTransientPointerState"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_hooks.usexrtransientpointerstate


> [!CAUTION]
> Deprecated: use `useXRInputSourceState("transientPointer", "left")` instead

## Call Signature

> **useXRTransientPointerState**(`handedness`): `undefined` \| `XRTransientPointerState`

Hook for getting the transient-pointer state

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Parameters**</span>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**handedness**</span>

`XRHandedness`

the handedness that the XRHandState should have

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`undefined` \| `XRTransientPointerState`

#
## Call Signature

> **useXRTransientPointerState**(): `XRTransientPointerState`

Hook for getting the transient-pointer state inside the xr store config

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**Returns**</span>

`XRTransientPointerState`

#]]></page>
<page path="/api/deprecated_button.vrbutton" title="VRButton"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_button.vrbutton


> [!CAUTION]
> Deprecated: use `<button onClick={() => store.enterVR()}>` instead

> `const` **VRButton**: `ForwardRefExoticComponent`\<`Omit`\<`Omit`\<`object` & `Omit`\<`ButtonHTMLAttributes`\<`HTMLButtonElement`\>, `"children"` \| `"onError"`\> & `RefAttributes`\<`HTMLButtonElement`\>, `"ref"`\>, `"mode"`\> & `RefAttributes`\<`HTMLButtonElement`\>\>

]]></page>
<page path="/api/xr.xr" title="XR"><![CDATA[URL: https://pmndrs.github.io/xr/api/xr.xr


> **XR**(`props`): `Element`

Core XR component for connecting the `XRStore` with the scene.
Requires an `XRStore` which it will provide to its children.

## props
---

`XRProperties`

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children**</span>

Children to be rendered inside the context.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**store**</span>

The `XRStore` to be used for the session.


## Returns
---
`Element`
]]></page>
<page path="/api/deprecated_button.xrbutton" title="XRButton"><![CDATA[URL: https://pmndrs.github.io/xr/api/deprecated_button.xrbutton


> [!CAUTION]
> Deprecated: use `<button onClick={() => store.enterXR()}>` instead

> `const` **XRButton**: `ForwardRefExoticComponent`\<`object` & `Omit`\<`ButtonHTMLAttributes`\<`HTMLButtonElement`\>, `"children"` \| `"onError"`\> & `RefAttributes`\<`HTMLButtonElement`\>\>

]]></page>
<page path="/api/controller.xrcontrollercomponent" title="XRControllerComponent"><![CDATA[URL: https://pmndrs.github.io/xr/api/controller.xrcontrollercomponent


> **XRControllerComponent**(`props`): `ReactNode`

Component for placing content in the controller anchored at a specific component such as the Thumbstick

## props
---

`object` & `RefAttributes`\<`undefined` \| `Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**id**</span>

`XRControllerGamepadComponentId` Is the id of the component where content should be placed (e.g. `"a-button"`)

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onPress?**</span>

`Function` Is an optional callback to receive when the component is pressed

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onRelease?**</span>

`Function` Is an optional callback to receive when the component is released

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children?**</span>

`ReactNode` Children to be placed inside the componenent (e.g. visualizing a tooltip over the button...)


## Returns
---
`ReactNode`
]]></page>
<page path="/api/controller.xrcontrollermodel" title="XRControllerModel"><![CDATA[URL: https://pmndrs.github.io/xr/api/controller.xrcontrollermodel


> **XRControllerModel**(`props`): `ReactNode`

Component for rendering a 3D model for the XRController

## props
---

`XRControllerModelOptions` & `RefAttributes`\<`Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**colorWrite**</span>

Configures the colorWrite property of the model

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**renderOrder**</span>

Configures the render order model


## Returns
---
`ReactNode`
]]></page>
<page path="/api/dom-overlay.xrdomoverlay" title="XRDomOverlay"><![CDATA[URL: https://pmndrs.github.io/xr/api/dom-overlay.xrdomoverlay


> **XRDomOverlay**(`props`): `ReactNode`

Renders html elements as an overlay for handheld AR experiences

## props
---

`Omit`\<`HTMLProps`\<`HTMLDivElement`\>, `"ref"`\> & `RefAttributes`\<`HTMLDivElement`\>

Props are forwarded to a `div` element

## Returns
---
`ReactNode`
]]></page>
<page path="/api/hand.xrhandjoint" title="XRHandJoint"><![CDATA[URL: https://pmndrs.github.io/xr/api/hand.xrhandjoint


> [!CAUTION]
> Deprecated: use `<XRSpace space="wrist">` instead of `<XRHandJoint joint="wrist">`

> **XRHandJoint**(`props`): `ReactNode`

Component for placing content in the hand anchored at a specific joint such as the index finger tip.

## props
---

`object` & `RefAttributes`\<`Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**joint**</span>

[XRHandJoint](https://developer.mozilla.org/en-US/docs/Web/API/XRHand#hand_joints) Is the name of the joint where content should be placed (e.g. `"wrist"`)

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children**</span>

Components to be placed inside the joint (e.g. For visualizing a tooltip over the index finger tip)


## Returns
---
`ReactNode`

]]></page>
<page path="/api/hand.xrhandmodel" title="XRHandModel"><![CDATA[URL: https://pmndrs.github.io/xr/api/hand.xrhandmodel


> **XRHandModel**(`props`): `ReactNode`

Component for rendering a 3D model for the XRHand

## props
---

`XRHandModelOptions` & `RefAttributes`\<`Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**colorWrite**</span>

Configures color writing

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**renderOrder**</span>

Configures the render order of the model


## Returns
---
`ReactNode`
]]></page>
<page path="/api/hit-test.xrhittest" title="XRHitTest"><![CDATA[URL: https://pmndrs.github.io/xr/api/hit-test.xrhittest


> **XRHitTest**(`props`): `ReactNode`

A convenience wrapper component for the useXRHitTest hook. Used to setup hit testing in the scene.

## props
---

`Omit`\<`Omit`\<`Mutable`\<`Overwrite`\<`Partial`\<`Overwrite`\<`Group`\<`Object3DEventMap`\>, `MathProps`\<`Group`\<...\>\> & `ReactProps`\<`Group`\<...\>\> & `Partial`\<`EventHandlers`\>\>\>, `Omit`\<`InstanceProps`\<`Group`\<`Object3DEventMap`\>, *typeof* `Group`\>, `"object"`\>\>\>, `"children"`\> & `object`, `"ref"`\> & `RefAttributes`\<`Group`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**space**</span>

[XRSpaceType](https://developer.mozilla.org/en-US/docs/Web/API/XRSpace) | [XRReferenceSpaceType](https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpace#reference_space_types)

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**onResults**</span>

Callback function that is called with the results of the hit test


## Returns
---
`ReactNode`

## Example

```ts
const matrixHelper = new Matrix4()
const hitTestPosition = new Vector3()

const store = createXRStore({
  hand: () => {
    const inputSourceState = useXRInputSourceStateContext()

    return (
      <>
        <DefaultXRHand />
        <XRHitTest
          space={inputSourceState.inputSource.targetRaySpace}
          onResults={(results, getWorldMatrix) => {
            if (results.length === 0) return
            getWorldMatrix(matrixHelper, results[0])
            hitTestPosition.setFromMatrixPosition(matrixHelper)
          }}
        />
      </>
    )
  },
})
```

## See

 - [Hit Test Tutorial](https://pmndrs.github.io/xr/docs/tutorials/hit-test)
 - [Hit Test Example](https://pmndrs.github.io/xr/examples/hit-testing/)
]]></page>
<page path="/api/layer.xrlayer" title="XRLayer"><![CDATA[URL: https://pmndrs.github.io/xr/api/layer.xrlayer


> `const` **XRLayer**: `ForwardRefExoticComponent`\<`Omit`\<`XRLayerProperties`, `"ref"`\> & `RefAttributes`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>\>\>

Component for rendering high quality quad, cylinder, or equirect layers inside supported sessions. Also includes a fallback for non-supported sessions.

## Param

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**src**</span>

Property for displaying images and videos onto the layer. For rendering dynamic content to the layer, leave the `src` empty and put the dynamic (3D) content into the children, so that the layer acts as a render target.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**shape**</span>

Property to configure the shape of the layer ("quad", "cylinder", "equirect").

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**layout**</span>

Property to configure the layout of the display content for stereo content ("default", "mono", "stereo-left-right", "stereo-top-bottom").

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**centralAngle**</span>

Property to configure the central angle in case the layer shape is a "cylinder".

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**centralHorizontalAngle**</span>

Property to configure the central horizontal angle in case the layer shape is "equirect".

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**upperVerticalAngle**</span>

Property to configure the upper vertical angle in case the layer shape is "equirect".

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**lowerVerticalAngle**</span>

Property to configure the lower vertical angle in case the layer shape is "equirect".

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**chromaticAberrationCorrection**</span>

Property to configure whether chromatic abberration should be corrected by the layer.

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**quality**</span>

Property to configure for what type of content the layer should be optimized ("default", "text-optimized", "graphics-optimized").

]]></page>
<page path="/api/mesh.xrmeshmodel" title="XRMeshModel"><![CDATA[URL: https://pmndrs.github.io/xr/api/mesh.xrmeshmodel


> **XRMeshModel**(`props`): `ReactNode`

Component for rendering a mesh for the XRMesh based on the detected mesh geometry

## props
---

`Omit`\<`Mutable`\<`Overwrite`\<`Partial`\<`Overwrite`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>, `MathProps`\<`Mesh`\<`BufferGeometry`\<...\>, ... \| ..., `Object3DEventMap`\>\> & `ReactProps`\<`Mesh`\<`BufferGeometry`\<...\>, ... \| ..., `Object3DEventMap`\>\> & `Partial`\<`EventHandlers`\>\>\>, `Omit`\<`InstanceProps`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>, *typeof* `Mesh`\>, `"object"`\>\>\> & `object`, `"ref"`\> & `RefAttributes`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>\>

Accepts the same props as a ThreeJs [Mesh](https://threejs.org/docs/#api/en/objects/Mesh)

## Returns
---
`ReactNode`
]]></page>
<page path="/api/origin.xrorigin" title="XROrigin"><![CDATA[URL: https://pmndrs.github.io/xr/api/origin.xrorigin


> **XROrigin**(`props`): `ReactNode`

Component for setting the origin of the player (their feet)

## props
---

`Omit`\<`XROriginProps`, `"ref"`\> & `RefAttributes`\<`Group`\<`Object3DEventMap`\>\>

Accepts the same props as a ThreeJs [Group](https://threejs.org/docs/#api/en/objects/Group)

## Returns
---
`ReactNode`
]]></page>
<page path="/api/plane.xrplanemodel" title="XRPlaneModel"><![CDATA[URL: https://pmndrs.github.io/xr/api/plane.xrplanemodel


> **XRPlaneModel**(`props`): `ReactNode`

Component for rendering a mesh for the XRPlane based on the detected plane geometry

## props
---

`Omit`\<`Mutable`\<`Overwrite`\<`Partial`\<`Overwrite`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>, `MathProps`\<`Mesh`\<`BufferGeometry`\<...\>, ... \| ..., `Object3DEventMap`\>\> & `ReactProps`\<`Mesh`\<`BufferGeometry`\<...\>, ... \| ..., `Object3DEventMap`\>\> & `Partial`\<`EventHandlers`\>\>\>, `Omit`\<`InstanceProps`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>, *typeof* `Mesh`\>, `"object"`\>\>\> & `object`, `"ref"`\> & `RefAttributes`\<`Mesh`\<`BufferGeometry`\<`NormalBufferAttributes`\>, `Material` \| `Material`[], `Object3DEventMap`\>\>

Accepts the same props as a ThreeJs [Mesh](https://threejs.org/docs/#api/en/objects/Mesh)

## Returns
---
`ReactNode`
]]></page>
<page path="/api/space.xrspace" title="XRSpace"><![CDATA[URL: https://pmndrs.github.io/xr/api/space.xrspace


> **XRSpace**(`props`): `ReactNode`

Component that puts its children in the provided XRSpace (or reference space type)

## props
---

`object` & `RefAttributes`\<`Object3D`\<`Object3DEventMap`\>\>

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**space**</span>

[XRSpaceType](https://developer.mozilla.org/en-US/docs/Web/API/XRSpace) | [XRSpaceType](https://pmndrs.github.io/xr/docs/api/space.XRSpaceType)

<span style={{fontSize: 24, color: "rgb(var(--color-primary))"}}>**children**</span>

[ReactNode](https://reactjs.org/docs/introducing-jsx.html#react-jsx)


## Returns
---
`ReactNode`
]]></page>
<page path="/api/space.xrspacetype" title="XRSpaceType"><![CDATA[URL: https://pmndrs.github.io/xr/api/space.xrspacetype


> **XRSpaceType** = `XRReferenceSpaceType` \| `XRInputSourceSpaceType` \| `XRHandJointSpaceType` \| `XRBodyJointSpaceType`

A combined type of all XRSpace types

## See

 - [XRReferenceSpaceType](https://developer.mozilla.org/en-US/docs/Web/API/XRReferenceSpaceType)
 - [XRHandJointSpaceType](https://immersive-web.github.io/webxr-hand-input/#xrhand-interface)
]]></page>