React Three XR

https://pmndrs.github.io/xr/docs
Admin
React Three XR is a WebXR library that extends React Three Fiber, enabling developers to build...
Tokens:21,875
Snippets:240
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Resizing XR Origin Example

Source: https://pmndrs.github.io/xr/docs/tutorials/origin

This example illustrates how to manipulate the XROrigin's scale and position to achieve a resizing interaction within an XR session. It shows a basic setup for entering AR and rendering a model.

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

```

--------------------------------

### Install @react-three/xr

Source: https://pmndrs.github.io/xr/docs/getting-started/convert-to-xr

Install the latest version of the library to begin integration.

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

--------------------------------

### Install @react-three/xr

Source: https://pmndrs.github.io/xr/docs

Install the necessary packages for @react-three/xr.

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

--------------------------------

### Basic XR Scene Implementation

Source: https://pmndrs.github.io/xr/docs/getting-started/introduction

A minimal example showing how to initialize an XR store and wrap a scene with the XR component to enable AR interaction.

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

--------------------------------

### Complete Teleportation Example

Source: https://pmndrs.github.io/xr/docs/tutorials/teleport

A full implementation combining store configuration, state management, and scene components.

```jsx

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

--------------------------------

### Anchor Component Example

Source: https://pmndrs.github.io/xr/docs/tutorials/anchors

This example demonstrates an `Anchor` component that uses `useXRAnchor` and `XRSpace` to attach a Box to the right hand or controller when selected. It requires `useXRInputSourceState` and `useXRInputSourceEvent` hooks.

```javascript
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>
  )
}
```

--------------------------------

### Configure XR Store Options

Source: https://pmndrs.github.io/xr/docs/tutorials/store

Example of initializing the XR store with specific controller settings to disable the left-hand controller.

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

--------------------------------

### Roller Coaster XR Origin Example

Source: https://pmndrs.github.io/xr/docs/tutorials/origin

This example demonstrates how to use XROrigin within a moving object to create an XR roller coaster experience. It includes setting up the XR store, Canvas, and handling GLTF animations.

```javascript
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')!,
      )}
    </>
  )
}

```

--------------------------------

### Setup XRHitTest with onResults Callback

Source: https://pmndrs.github.io/xr/docs/api/hit-test.xrhittest

Use XRHitTest to set up hit testing in your scene. Provide the target ray space and a callback function that receives hit test results and a function to get the world matrix.

```jsx
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)
          }}
        />
      </>
    )
  },
})
```

--------------------------------

### Implement a simple dragging interaction

Source: https://pmndrs.github.io/xr/docs/tutorials/interactions

This example demonstrates how to create a basic dragging functionality using pointer events and pointer captures. It requires the mesh not to be inside a transformed group.

```jsx
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>
 )
}

```

--------------------------------

### Using TransformHandles and PivotHandles

Source: https://pmndrs.github.io/xr/docs/handles/prebuild-handles

Demonstrates how to integrate TransformHandles and PivotHandles into a React Three Fiber Canvas, including the necessary event system setup for XR compatibility.

```APIDOC
## Using TransformHandles and PivotHandles

To use `TransformHandles` and `PivotHandles` in React Three Fiber, you need to disable the default event system and integrate the event system from `@react-three/xr`.

### Method

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

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

--------------------------------

### Implement Locomotion with Right Controller Thumbstick

Source: https://pmndrs.github.io/xr/docs/tutorials/gamepad

Reads the thumbstick state from the right XR controller and uses it to control the position of an XROrigin component. This example requires the `useXRInputSourceState` hook and `useFrame` for continuous updates. Ensure the 'xr-standard-thumbstick' component is available on the controller.

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

```

--------------------------------

### Bind onClick handler to a mesh

Source: https://pmndrs.github.io/xr/docs/tutorials/interactions

This example shows how to attach an onClick handler to a mesh. This interaction works on both non-XR and XR devices.

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

```

--------------------------------

### Get Hand State and Create Touch Pointer

Source: https://pmndrs.github.io/xr/docs/tutorials/custom-inputs

Access the hand's XR input state, reference the middle finger's position, and create a touch pointer for interaction.

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

--------------------------------

### Initialize an HTML video element

Source: https://pmndrs.github.io/xr/docs/tutorials/layers

Uses useMemo to create and configure an HTML video element for use within the XR scene.

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

--------------------------------

### Initialize XR Store

Source: https://pmndrs.github.io/xr/docs/getting-started/convert-to-xr

Import and instantiate the XR store required for managing immersive sessions.

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

const store = createXRStore()
```

--------------------------------

### Enable Secondary Input Sources

Source: https://pmndrs.github.io/xr/docs/tutorials/secondary-input-sources

Initialize the XR store with the secondaryInputSources flag set to true to enable tracking of additional input sources.

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

--------------------------------

### Conditional Rendering with IfInSessionMode Guard

Source: https://pmndrs.github.io/xr/docs/tutorials/guards

Use `IfInSessionMode` to conditionally render content. This example denies rendering the background in 'immersive-ar' mode, effectively showing it only when not in AR.

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

--------------------------------

### createXRStore Options

Source: https://pmndrs.github.io/xr/docs/tutorials/store

This section details the available options for configuring the `createXRStore` function.

```APIDOC
## createXRStore Options

### Description
Configuration options for the `createXRStore` function.

### Parameters
#### Request Body
- **controller** (object | boolean) - Optional - 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. Default: `true`
- **transientPointer** (object | boolean) - Optional - 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. Default: N/A
- **hand** (object | boolean) - Optional - 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. Default: N/A
- **gaze** (object | boolean) - Optional - Configures the `<DefaultXRGaze/>` or allows providing a custom gaze implementation. Setting this to `false` prevents gaze-based interaction from being used. Default: `true`
- **screenInput** (object | boolean) - Optional - Configures the `<DefaultXRScreenInput/>` or allows providing a custom screen input implementation. Setting this to `false` prevents screen input from being used. Default: `true`
- **emulate** (string | boolean) - Optional - Emulates a specific device (e.g., "metaQuest3") using IWER 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. Default: `"metaQuest3"`
- **frameRate** (string) - Optional - Sets the session's framerate, with options such as `"high"` for smoother performance. Default: `"high"`
- **foveation** (number) - Optional - Sets the WebXR foveation level between `0` (no foveation) and `1` (maximum foveation). If `undefined`, the device/browser's default foveation setting is used. Default: `undefined`
- **frameBufferScaling** (number) - Optional - Adjusts the framebuffer scaling of the session. If undefined, the device/browser's default scaling is used (typically `1`). Default: `undefined`
- **enterGrantedSession** (boolean | array) - Optional - 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. Default: `true`
- **baseAssetPath** (string) - Optional - Specifies the path to load the controller and hand models, and controller profiles from a CDN or local source. Default: `'https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/'`
- **defaultControllerProfileId** (string) - Optional - 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. Default: `'generic-trigger'`
- **defaultXRHandProfileId** (string) - Optional - Specifies the fallback profile ID for hand tracking if no matching profile is found. It ensures basic hand-tracking functionality. Default: `'generic-hand'`
- **originReferenceSpace** (string) - Optional - 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. Default: N/A
- **bounded** (boolean) - Optional - 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. Default: `undefined`
- **anchors** (boolean) - Optional - Enables or disables anchors, which are fixed points in the XR environment that can be used to attach virtual objects. Default: `true`
- **handTracking** (boolean) - Optional - Enables or turns off hand-tracking in the session, allowing users to interact with the XR environment using their hands. Default: `true` (`false` for Apple Vision Pro)
- **layers** (boolean) - Optional - Enables or turns off the use of layers in the session, which can enhance rendering performance by stacking visual content. Default: `true`
- **meshDetection** (boolean) - Optional - Enables or turns off mesh detection, allowing the system to recognize and interact with real-world objects by detecting their mesh. Default: `true`
- **planeDetection** (boolean) - Optional - Enables or turns off plane detection, allowing the system to recognize flat surfaces like floors and tables. Default: `true`
- **depthSensing** (boolean) - Optional - Enables or disables depth sensing in the session, which can enhance realism by occluding virtual objects from real-world objects. Default: `false`
- **customSessionInit** (object) - Optional - Overrides the session initialization object with custom settings. Use with caution, as it can significantly alter the behavior of the XR session. Default: `undefined`
- **hitTest** (boolean) - Optional - 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. Default: `true`
- **domOverlay** (boolean | object) - Optional - 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. Default: `true`

### Request Example
```json
{
  "controller": {
    "left": false
  }
}
```

### Response
This endpoint does not return a response body. Configuration is applied internally.
```

--------------------------------

### Add XR Entry Buttons

Source: https://pmndrs.github.io/xr/docs/getting-started/convert-to-xr

Create HTML buttons to trigger VR or AR sessions using the initialized store.

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

--------------------------------

### Implement Object Placement System

Source: https://pmndrs.github.io/xr/docs/tutorials/hit-test

Use this component to enable continuous hit testing for previewing object placement and a button to place objects at the hit test location. Requires `useState`, `useRef`, and `useXRHitTest` hooks.

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

```

--------------------------------

### Using OrbitHandles and MapHandles in React Three Fiber

Source: https://pmndrs.github.io/xr/docs/handles/screen-handle-components

Integrate OrbitHandles and MapHandles by disabling the default Canvas events and enabling the XR event system. This setup is required for screen-based controls to function correctly.

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

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

--------------------------------

### Enable Teleport Pointers

Source: https://pmndrs.github.io/xr/docs/tutorials/teleport

Configure the XR store to enable teleport pointers for hands and controllers.

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

--------------------------------

### Provide Custom Hand Implementation

Source: https://pmndrs.github.io/xr/docs/tutorials/custom-inputs

Replace the default hand implementation with a custom one by passing it to the XR store options.

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

--------------------------------

### Render Custom Hand with Pointer Cursor

Source: https://pmndrs.github.io/xr/docs/tutorials/custom-inputs

Set up an XRSpace for the middle finger, render the hand model, and display a pointer cursor.

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

--------------------------------

### Basic XR Scene with @react-three/fiber

Source: https://pmndrs.github.io/xr/docs

A simple scene demonstrating XR integration. It includes a button to enter AR and a mesh that changes color on click. Requires @react-three/fiber and @react-three/xr.

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

--------------------------------

### usePointerXRInputSourceEvents Hook

Source: https://pmndrs.github.io/xr/docs/api/pointer.usepointerxrinputsourceevents

This hook is used for binding XR session events, such as 'selectstart', to the provided pointer down/up events. It facilitates interaction within XR environments by connecting standard pointer actions to XR input sources.

```APIDOC
## usePointerXRInputSourceEvents

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

### Parameters
#### Path Parameters
* **pointer** (Pointer) - Required - The pointer object.
* **inputSource** (XRInputSource) - Required - The XR input source.
* **event** (string) - Required - The XR event to bind, e.g., `"squeeze"` or `"select"`.
* **missingEvents** (XRInputSourceEvent[]) - Required - An array of XR input source events that are missing.

### Returns
* * *
`void`
```

--------------------------------

### XRDomOverlay Component

Source: https://pmndrs.github.io/xr/docs/api/dom-overlay.xrdomoverlay

Documentation for the XRDomOverlay component which renders HTML elements as an overlay for handheld AR.

```APIDOC
## XRDomOverlay

### Description
Renders HTML elements as an overlay for handheld AR experiences.

### Parameters
#### Props
- **props** (Omit<HTMLProps<HTMLDivElement>, "ref"> & RefAttributes<HTMLDivElement>) - Required - Props are forwarded to a div element.

### Returns
- **ReactNode** - The rendered overlay component.
```

--------------------------------

### XR Store Configuration Options

Source: https://pmndrs.github.io/xr/docs/tutorials/store

Configuration options for the XR store that can be set to customize the XR experience.

```APIDOC
## XR Store Configuration

### `secondaryInputSources`

- **Type**: boolean
- **Default**: `false`
- **Description**: 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.

### `offerSession`

- **Type**: boolean | string
- **Default**: `true`
- **Description**: 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. Alternatively, `offerSession` can be directly configured to only enter a `"immersive-vr"` or `"immersive-vr"` session.
```

--------------------------------

### Create a 3D Door with Handles

Source: https://pmndrs.github.io/xr/docs/handles/introduction

Uses Handle and HandleTarget components to enable door rotation via a handle. Requires a GLTF model processed with gltfjsx.

```javascript
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>
  )
}
```

--------------------------------

### XR Component

Source: https://pmndrs.github.io/xr/docs/api/xr.xr

The XR component initializes the XR session context by providing an XRStore to its children.

```APIDOC
## XR Component

### Description
Core XR component for connecting the `XRStore` with the scene. Requires an `XRStore` which it will provide to its children.

### Parameters
#### Props
- **children** (ReactNode) - Required - Children to be rendered inside the context.
- **store** (XRStore) - Required - The `XRStore` to be used for the session.

### Returns
- **Element** - The rendered XR context element.
```

--------------------------------

### useXRControllerLocomotion Hook

Source: https://pmndrs.github.io/xr/docs/api/controller-locomotion.usexrcontrollerlocomotion

A hook for handling basic locomotion in VR, allowing for translation and rotation via controller input.

```APIDOC
## useXRControllerLocomotion

### Description
A hook for handling basic locomotion in VR.

### Parameters
- **target** (RefObject<Object3D> | Function) - Required - Either a THREE.Group ref, or a callback function receiving movement input.
- **translationOptions** (XRControllerLocomotionTranslationOptions) - Optional - Options that control the translation of the user. Set to false to disable.
  - **speed** (number) - The speed at which the user moves.
- **rotationOptions** (XRControllerLocomotionRotationOptions) - Optional - Options that control the rotation of the user. Set to false to disable.
  - **deadZone** (number) - How far the joystick must be pushed to trigger a turn.
  - **type** ('smooth' | 'snap') - Controls how rotation using the controller functions.
  - **degrees** (number) - If type is 'snap', this specifies the number of degrees to snap the user's view by.
  - **speed** (number) - If type is 'smooth', this specifies the speed at which the user's view rotates.
- **translationControllerHand** ('left' | 'right') - Optional - Specifies which hand will control the movement.

### Returns
- **void** - This hook does not return a value.
```

--------------------------------

### Recommended Replacement for XRButton

Source: https://pmndrs.github.io/xr/docs/api/deprecated_button.xrbutton

Replace the deprecated XRButton with a standard HTML button that triggers the enterXR() function from the store.

```javascript
import { ButtonHTMLAttributes, RefAttributes } from 'react'
import { Button } from 'react-bootstrap'
import { useXR } from '@react-three/xr'

function App() {
  const { enterXR } = useXR()
  return (
    <Canvas>
      <XR>
        <Button onClick={() => enterXR()}>
          Enter XR
        </Button>
      </XR>
    </Canvas>
  )
}
```

--------------------------------

### Basic HTML Overlay with XRDomOverlay

Source: https://pmndrs.github.io/xr/docs/tutorials/dom-overlay

Use the XRDomOverlay component to embed HTML content directly over a hand-held AR experience. Ensure the component has appropriate styling for visibility.

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

--------------------------------

### Create an XRLayer for video playback

Source: https://pmndrs.github.io/xr/docs/tutorials/layers

Defines a layer positioned in 3D space that triggers video playback on click.

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

--------------------------------

### Interactive AR Experience with Dom Overlay

Source: https://pmndrs.github.io/xr/docs/tutorials/dom-overlay

Integrate a button to enter AR and an interactive HTML element within the XRDomOverlay. The HTML element's background color changes on click, demonstrating state management within the overlay.

```jsx
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>
    </>
 )
```

--------------------------------

### XRButton Component

Source: https://pmndrs.github.io/xr/docs/api/deprecated_button.xrbutton

Details regarding the deprecated XRButton component and its recommended replacement.

```APIDOC
## XRButton

### Description
A deprecated component used to trigger XR sessions. It is recommended to use `<button onClick={() => store.enterXR()}>` instead.

### Type
`ForwardRefExoticComponent<object & Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onError"> & RefAttributes<HTMLButtonElement>>`

### Location
`packages/react/xr/src/deprecated/button.tsx`
```

--------------------------------

### Configure Ray Pointer Color

Source: https://pmndrs.github.io/xr/docs/tutorials/custom-inputs

Use the XR store to configure the color of the ray pointer on the user's hand.

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

--------------------------------

### HandleStore Functions

Source: https://pmndrs.github.io/xr/docs/handles/handle-component

Methods exposed by the HandleStore to programmatically manage interaction states.

```APIDOC
## HandleStore Functions

### Description
The HandleStore manages the internal state of interactions. These functions allow for programmatic control over the lifecycle of an interaction.

### Exposed Functions
- **getState()** - Returns the current interaction state or undefined if no interaction is active.
- **capture()** - Initiates an interaction programmatically without user input.
- **save()** - Saves the current state to isolate modifications.
- **cancel()** - Programmatically cancels the current interaction.
```

--------------------------------

### Configuring Trackable Types

Source: https://pmndrs.github.io/xr/docs/tutorials/hit-test

Demonstrates how to specify single or multiple trackable surface types for hit testing hooks.

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

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

--------------------------------

### Deprecated XRButton Usage

Source: https://pmndrs.github.io/xr/docs/api/deprecated_button.xrbutton

This component is deprecated. Use a standard button with an onClick handler that calls store.enterXR() instead.

```javascript
import { XRButton } from '@react-three/xr'

function App() {
  return (
    <Canvas>
      <XR>
        <XRButton />
      </XR>
    </Canvas>
  )
}
```

--------------------------------

### Full application structure with XRLayer

Source: https://pmndrs.github.io/xr/docs/tutorials/layers

Integrates the video element and XRLayer within the Canvas and XR components.

```jsx
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>
  )
}
```

--------------------------------

### Render Detected Wall Planes

Source: https://pmndrs.github.io/xr/docs/tutorials/object-detection

Uses the useXRPlanes hook to filter for walls and renders them using XRSpace and XRPlaneModel with a red material.

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

--------------------------------

### Manual Hit Testing with useXRHitTestSource

Source: https://pmndrs.github.io/xr/docs/tutorials/hit-test

Provides lower-level control over hit testing by allowing manual checks for results, typically within a frame loop.

```typescript
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>
  )
}
```

--------------------------------

### ShowIfFacingCamera Component

Source: https://pmndrs.github.io/xr/docs/api/guard_facing-camera.showiffacingcamera

Documentation for the ShowIfFacingCamera component which toggles visibility of children based on camera orientation.

```APIDOC
## ShowIfFacingCamera

### Description
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.

### Parameters
#### Props
- **children** (ReactNode) - Required - The ReactNode elements to conditionally show.
- **direction** (Vector3) - Required - Direction vector to check against the camera's facing direction.
- **angle** (number) - Optional - The angle in radians to determine visibility. Defaults to Math.PI / 2 (90 degrees).

### Returns
- **Element** - The rendered React element.
```

--------------------------------

### Manage Teleport Position State

Source: https://pmndrs.github.io/xr/docs/tutorials/teleport

Initialize state to track the user's current position for teleportation.

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

--------------------------------

### useXRSessionVisibilityState Hook

Source: https://pmndrs.github.io/xr/docs/api/hooks.usexrsessionvisibilitystate

The useXRSessionVisibilityState hook retrieves the current visibility state of the XR session.

```APIDOC
## useXRSessionVisibilityState Hook

### Description
Gets the visibility state of the XR session.

### Returns
* `undefined` | `XRVisibilityState` - The visibility state of the XR session.
```

--------------------------------

### useXRRequestHitTest Hook

Source: https://pmndrs.github.io/xr/docs/tutorials/hit-test

Provides a function for one-time, event-driven hit test requests.

```APIDOC
## useXRRequestHitTest Hook

### Description
Provides a function for one-time hit test requests, useful for event-driven scenarios like user taps or button clicks. Cannot be called within the `useFrame` hook.

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

### Request Example
```javascript
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>
      ))}
    </>
  )
}
```
```

--------------------------------

### XRMeshModel Component

Source: https://pmndrs.github.io/xr/docs/api/mesh.xrmeshmodel

Documentation for the XRMeshModel component, which renders a mesh for XR environments.

```APIDOC
## XRMeshModel

### Description
A React component used to render a mesh for the XRMesh based on detected mesh geometry.

### Parameters
#### Props
- **props** (Object) - Required - Accepts the same props as a standard Three.js Mesh, including partial overrides and event handlers.

### Returns
- **ReactNode** - The rendered mesh component.
```

--------------------------------

### ShowIfSessionVisible Component

Source: https://pmndrs.github.io/xr/docs/api/guard_focus.showifsessionvisible

Documentation for the ShowIfSessionVisible component which conditionally renders children based on session visibility.

```APIDOC
## ShowIfSessionVisible

### Description
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.

### Parameters
#### Props
- **children** (ReactNode) - Optional - The ReactNode elements to conditionally show.

### Returns
- **Element** - The rendered React element.
```

--------------------------------

### useXRHitTestSource Hook

Source: https://pmndrs.github.io/xr/docs/tutorials/hit-test

Provides lower-level access to hit test sources for manual control over hit testing frequency.

```APIDOC
## useXRHitTestSource Hook

### Description
Provides lower-level access to hit test sources, giving more control over when and how hit tests are performed. It requires manual checking for hit test results, typically every frame or every few frames.

### Parameters
- **relativeTo** (object | XRSpace | ReferenceSpace) - The object, XR space, or reference space to cast rays from.
- **trackableType** (string | string[]) - Optional. Specifies what types of surfaces to hit test against. Can be a single type or an array of types (e.g., 'plane', ['plane', 'mesh']).

### Returns
- A hit test source object that can be used with `frame.getHitTestResults()`.

### Request Example
```javascript
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>
  )
}
```
```

--------------------------------

### Handle Component Properties

Source: https://pmndrs.github.io/xr/docs/handles/handle-component

Configuration properties for the Handle component to control interaction behavior and target manipulation.

```APIDOC
## Handle Component Properties

### Description
The Handle component is the core interface for enabling user interactions on 3D objects. It supports translation, rotation, and scaling with fine-grained control over constraints and event handling.

### Properties
- **handleRef** (Ref) - Optional - Overrides the internal handle object.
- **targetRef** (Ref | "from-context") - Optional - The object to be manipulated. Defaults to context if provided by HandleTarget.
- **getHandleOptions** (Function) - Optional - Dynamically generates options to override current handle settings.
- **bind** (Boolean) - Optional - Disables automatic event listener binding.
- **apply** (Function) - Optional - Overrides the default state modification logic.
- **projectRays** (Boolean) - Optional - Configures if input rays are projected onto the interaction space.
- **alwaysUpdate** (Boolean) - Optional - Forces transformation updates every frame.
- **multitouch** (Boolean) - Optional - Enables or disables multi-input device interaction.
- **filter** (Function) - Optional - Filters interactions based on events; return false to ignore.
- **stopPropagation** (Boolean) - Optional - Controls event propagation to ancestors.
- **rotate** (Boolean | String | Object) - Optional - Configures rotation constraints.
- **scale** (Boolean | String | Object) - Optional - Configures scaling constraints.
- **translate** (Boolean | String | Object) - Optional - Configures translation constraints or transformation modes (e.g., "as-scale").
- **ref** (Ref) - Optional - Retrieves the internal HandleStore reference.
```

--------------------------------

### Configure Vite for React and SSL

Source: https://pmndrs.github.io/xr/docs/getting-started/development-setup

This configuration enables hot module reloading with React and HTTPS, which is a requirement for WebXR.

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

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

--------------------------------

### Ensure XR Component Presence

Source: https://pmndrs.github.io/xr/docs/getting-started/faq

When entering AR or VR, ensure the `<XR>` component is directly within the `<Canvas>`. This is crucial for the XR session to initiate correctly.

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

--------------------------------

### Anchor Content with XRSpace

Source: https://pmndrs.github.io/xr/docs/tutorials/anchors

Once an anchor is created, use the `XRSpace` component to position content within that anchor's coordinate system.

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

--------------------------------

### Implement Continuous Hit Testing with useXRHitTest

Source: https://pmndrs.github.io/xr/docs/tutorials/hit-test

Performs real-time intersection checks every frame. Requires a callback function to process results and a reference space for ray casting.

```typescript
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>
  )
}
```

--------------------------------

### XRSpace Component

Source: https://pmndrs.github.io/xr/docs/api/space.useapplyxrspacematrix

Details about the XRSpace component, its props, and return type.

```APIDOC
## XRSpace Component

### Description
Component that puts its children in the provided XRSpace (or reference space type).

### Props
* `space` (XRSpaceType | XRSpaceType) - The XR space type to use.
* `children` (ReactNode) - The content to be rendered within the XRSpace.

### Returns
* `ReactNode` - The rendered children within the XRSpace.
```

--------------------------------

### Basic Handle Component Usage

Source: https://pmndrs.github.io/xr/docs/handles/handle-component

Use the Handle component to enable scaling of a mesh by dragging it from its center. Configure scaling behavior with the 'scale' property.

```jsx
<Handle translate="as-scale" scale={{ uniform: true }}>
    <mesh>
        <boxGeometry />
    </mesh>
</Handle>
```

--------------------------------

### useXRAnchor Hook

Source: https://pmndrs.github.io/xr/docs/api/anchor.usexranchor

The `useXRAnchor` hook is used to request and store a single XR anchor. It returns the XRAnchor object and a function to initiate the request.

```APIDOC
## useXRAnchor Hook

### Description
This hook is designed for requesting and storing a single XR anchor within your application. It simplifies the process of interacting with XR anchor functionalities.

### Returns
- `XRAnchor`: The XR anchor object if successfully retrieved.
- `(options) => Promise<undefined | XRAnchor>`: A function that takes optional options and returns a Promise resolving to `undefined` or the `XRAnchor` object upon completion of the request.
```
Tokens:
Raw