Skip to content

controller-teleport

The controller-teleport component enables instant teleportation in VR by pointing at a destination and pressing a controller button. This provides a comfortable locomotion method that minimizes motion sickness for many users.

Example

Below is an example of a basic teleportation setup:

Props

PropertyTypeDefaultDescription
handstring"right"Which controller to use for teleporting ("left" or "right")
buttonstring"trigger"Controller button to activate teleport
cameraHeightnumber1Height offset applied after teleporting (in meters)
interactionClassstring"interactive"CSS class that defines teleportable surfaces

Controller Buttons

The following buttons can be configured for teleportation:

Button ValueDescription
"trigger"Main trigger button (index finger)
"grip"Side grip button (middle finger)
"a" / "b"Primary buttons on right controller
"x" / "y"Primary buttons on left controller

Usage Tips

Making Surfaces Teleportable

For teleportation to work, surfaces must be detectable by the controller's raycaster. Make sure surfaces have the "interactive" class or vr-interactive component:

html
<a-plane position="0 0 0" rotation="-90 0 0" width="20" height="20" class="interactive"></a-plane>

If you want to use a different class name for teleportable surfaces, you can specify it using the interactionClass property:

html
<a-entity controller-teleport="hand: right; interactionClass: teleportable"></a-entity>
<a-plane position="0 0 0" rotation="-90 0 0" width="20" height="20" class="teleportable"></a-plane>

Listening for Teleport Events

You can listen for teleport events to trigger actions when the user teleports:

js
document.querySelector('[controller-teleport]').addEventListener('teleported', ()=>{
    // Perform actions based on the interaction
});

Combining with Other Movement Options

For maximum accessibility, combine teleportation with smooth locomotion using the controller-movement component:

html
<a-entity id="rig" position="0 1.6 0" controllers>
  <a-camera></a-camera>
  <!-- Smooth movement with left hand -->
  <a-entity controller-movement="mainHand: left"></a-entity>
  <!-- Teleportation with right hand -->
  <a-entity controller-teleport="hand: right"></a-entity>
</a-entity>

This allows users to choose their preferred movement method based on comfort preferences.