Develop

Grabbing Overview

Updated: Sep 4, 2026

IWSDK supports one-hand, two-hand, and distance grabbing. GrabSystem turns grab components into interaction handles and coordinates them with the pointer stack.

Choose a grab component

Component	Interaction	Scale support
`OneHandGrabbable`	Direct manipulation with one input	No
`TwoHandsGrabbable`	Direct manipulation with two inputs	Yes
`DistanceGrabbable`	Ray-based remote manipulation	Depends on its configuration

Use Interaction types for a detailed comparison.

Enable grabbing

Enable the feature when creating the World.

import {
  OneHandGrabbable,
  RayInteractable,
  SessionMode,
  World,
} from '@iwsdk/core';

const world = await World.create(document.getElementById('scene')!, {
  xr: { sessionMode: SessionMode.ImmersiveVR },
  features: { grabbing: true },
});

const entity = world.createTransformEntity(mesh);
entity.addComponent(RayInteractable);
entity.addComponent(OneHandGrabbable, {
  rotate: true,
  translate: true,
  rotateMin: [-Math.PI / 4, -Math.PI, -Math.PI / 4],
  rotateMax: [Math.PI / 4, Math.PI, Math.PI / 4],
});

RayInteractable makes the entity available to the ray interaction path. Use this tag for new ray-selectable entities.

How grab handles are managed

Entity gains a grab component
        ↓
GrabSystem creates and configures a handle
        ↓
Pointer events start, update, and end manipulation
        ↓
Entity loses the component
        ↓
GrabSystem cancels and removes the handle

One-hand and two-hand direct-grab handles deny ray-pointer events for the handle’s lifetime, from component initialization until the grab component is removed. Distance-grab handles deny grab-pointer events and use the ray path. This prevents direct and remote pointer modes from competing for the same object.

Author grab behavior in a scene

The native IWSDK Scene Editor can place objects and assign registered components. Application code remains the right place for procedural constraints and behavior that is not serialized into the scene.

Grabbing Overview

Choose a grab component

Enable grabbing

How grab handles are managed

Author grab behavior in a scene

Next steps