controller-attach

The controller-attach component attaches entities to VR controllers, allowing you to create controller-mounted UI panels, tools, or visual elements that follow the controller's movements and orientation in 3D space.

Example

Below is an example of attaching a UI panel to the right controller. The preview below uses a stand-in controller so you can see the attachment on desktop; in VR the same code attaches to your real controller — open this page in a VR headset and click the "VR" button.

import "spatial-design-system/components/controllers.js";
import "spatial-design-system/components/controllerAttach.js";

<a-scene>
  <a-entity id="rig" position="0 1.6 0" controllers>
    <a-camera></a-camera>
  </a-entity>
  <!-- UI panel attached to right controller -->
  <a-entity
    geometry="primitive: plane; width: 0.25; height: 0.15"
    material="color: #2196F3; opacity: 0.8"
    controller-attach="hand: right; offset: 0.15 0.1 0; rotation: 0 -30 0;">
    <a-text value="Right Hand" align="center" position="0 0 0.001" 
            scale="0.1 0.1 0.1" color="white"></a-text>
  </a-entity>
</a-scene>

Props

Property	Type	Default	Description
hand	string	"right"	Which controller to attach to ("left" or "right")
offset	vec3	"0 0 0"	Position offset from the controller in meters
rotation	vec3	"0 0 0"	Rotation offset in degrees (x, y, z Euler angles)
faceCamera	boolean	false	Makes the attached object always face the camera

Usage Tips

Ensured visibility

For UI elements that need to be readable from any angle, combine with the billboard component to make the attached UI always face the user:

<a-entity
  geometry="primitive: plane; width: 0.25; height: 0.15"
  material="color: #2196F3; opacity: 0.8"
  controller-attach="hand: right; offset: 0.15 0.05 -0.1;"
  billboard
>
  <a-text value="Always Visible" align="center" position="0 0 0.001" scale="0.1 0.1 0.1"></a-text>
</a-entity>