@threlte/xr

useTeleport

Provides a function to teleport the player to a reference frame.

<script>
  import { useTeleport } from '@threlte/xr'

  const teleport = useTeleport()
  const vec3 = new THREE.Vector3()

  vec3.set(5, 0, 5)

  teleport(vec3)
</script>

This function can be used within useTask for smooth movement.

useTask((delta) => {
  vec3.z += delta
  teleport(vec3)
})

Interaction with <XROrigin>

When useTeleport is called inside <XROrigin>, the origin group is translated directly — the user’s feet land at the target position, and their room-scale offset from the origin is preserved.

Without an <XROrigin>, the underlying XRReferenceSpace is mutated to compensate for the viewer’s current position so the feet land at the target regardless of where the user has walked in their physical space.