Unity XR Interaction Toolkit

On this page 8

The Unity XR Interaction Toolkit (often shortened to XRI) is an official, component-based Unity package that provides the building blocks for grabbing, pointing, poking, teleporting and interacting with user interface elements in virtual, augmented and mixed reality applications. In XR development, it sits above the device layer: it consumes tracked poses and input from providers such as OpenXR, ARKit or ARCore and turns them into consistent, hardware-agnostic interactions.

The toolkit matters because interaction code is one of the most repetitive and error-prone parts of any immersive project. Instead of writing custom raycasts, collision tests and grab logic for every headset, teams configure reusable interactor and interactable components, then adjust behavior through inspector settings and events. This shortens prototyping, but it also introduces conventions and limits that developers must understand.

How the interaction model works

The toolkit is built on a three-part model: interactors that act, interactables that are acted upon, and an interaction manager that arbitrates between them. Every frame, the manager asks each interactor which interactables are valid targets, sorts them, and then moves each pairing through defined states.

Those states are hover, select and activate. Hover means an interactor is pointing at or touching an object; select usually means the user pressed grip and is holding it; activate is a secondary action, such as pulling the trigger on a held tool. Each state change raises events such as selectEntered and hoverExited, which designers connect to sounds, haptics or game logic without writing new input code.

ComponentRoleTypical example
Interaction managerArbitrates every interactor and interactableOne per scene, created automatically
InteractorDetects targets and initiates interactionRay, direct, poke, gaze or socket interactor
InteractableResponds to hover, select and activateGrab interactable on a tool or door handle
Interaction groupLets one interactor at a time win priorityHand prefers direct grab over ray
XR OriginMaps tracking space to the sceneCamera offset and controller transforms
Core components and their roles

Input reaches the components through the Unity Input System and its action maps. Because actions such as select or teleport are bound to abstract inputs rather than specific buttons, the same scene can run on different controllers, and with the XR Hands package it can also run on articulated hand tracking.

Interactor types and their uses

Choosing the correct interactor type is the most consequential design decision in an XRI project, because each one implies a different physical metaphor and a different accuracy profile. Most production rigs combine several interactors per hand and use interaction groups to resolve conflicts.

InteractorInteraction metaphorBest suited forMain limitation
Direct interactorTouch and grab within reachPicking up nearby objectsRequires a trigger collider near the hand
Ray interactorLaser pointer at a distanceMenus and distant targetsJitter grows with distance
Near-far interactorBlends near grab and far castingUnified hand or controller inputMore settings to tune
Poke interactorFingertip pressing a surfaceButtons and touch panelsNeeds depth thresholds per control
Gaze interactorHead or eye directionHands-free selectionNeeds dwell time or confirmation
Socket interactorSnap point that holds objectsHolsters, slots and assembly stepsNot driven by the user directly
Interactor types compared

Interactables also come in variants. The XR Grab Interactable offers movement types such as instantaneous, kinematic and velocity tracking, which trade responsiveness against physical correctness. Velocity tracking lets held objects collide with walls but can feel slightly delayed; instantaneous movement feels tight but allows objects to pass through geometry.

Locomotion and user interface support

Beyond object interaction, the toolkit ships locomotion providers that move the XR Origin through the scene. They include teleportation, snap and continuous turning, continuous movement, climbing and grab-based movement, all coordinated so that only one provider moves the rig at a time.

  • Teleportation areas and anchors define where users may land and which direction they will face.
  • Snap turn rotates the view in fixed steps, commonly 30 or 45 degrees, to limit discomfort.
  • Continuous move supports head-relative or hand-relative direction and works with comfort vignettes.
  • Climb providers translate the rig when users grab climbable interactables.

For menus, the XR UI Input Module and tracked device graphic raycaster let ray and poke interactors operate standard Unity UI canvases in world space. This means existing buttons, sliders and scroll views work in XR with little change, although text size, distance and hit areas still need adjustment for headset readability.

The toolkit is an interaction layer, not a runtime. It does not render frames or talk to hardware; it depends on an XR plug-in, most often the OpenXR plug-in, to deliver poses and input. Comparing it with neighboring tools clarifies where it fits in a project stack.

ToolLayerRelationship to XRI
OpenXRCross-vendor runtime standardSupplies the device data XRI consumes
AR FoundationUnity AR abstractionCombines with XRI for AR placement and gestures
Meta XR All-in-One SDKVendor SDK with its own interaction systemAlternative or complement on Meta headsets
MRTK3Mixed reality toolkitBuilds its interactions on top of XRI
WebXRBrowser APISeparate ecosystem outside Unity
Position of XRI among XR tools

The practical choice is usually between portability and vendor-specific polish. XRI favors one codebase across Quest, Pico, Windows Mixed Reality and Android XR devices, while a vendor SDK may expose features such as advanced hand poses or passthrough controls earlier.

Setting up and configuring a project

A typical setup installs the package through the Package Manager, enables a provider in XR Plug-in Management, and imports the Starter Assets sample, which contains preconfigured input actions and a ready XR Origin rig. Teams then replace the sample models and tune interactors rather than building rigs from scratch.

DecisionRecommended choiceReason
XR providerOpenXR plug-in with vendor feature groupsWidest device coverage from one build
Input handlingInput System actions from Starter AssetsTested bindings for common controllers
Hand trackingAdd XR Hands and near-far interactorsSame interactables work with hands and controllers
Grab movement typeVelocity tracking for physics propsPrevents objects passing through walls
Locomotion defaultTeleport plus snap turnMost comfortable for new users
Configuration decisions during setup

Version alignment deserves attention. The toolkit evolved significantly between version 2.x and 3.x, which reorganized namespaces and replaced several older components, so upgrading an existing project can require manual migration of prefabs and scripts.

Limitations and common mistakes

The toolkit removes much boilerplate, but it does not guarantee good interaction design. The most frequent problems come from misconfigured colliders, layers and interaction groups, not from defects in the package itself.

  • Missing interaction layer masks let a ray interactor grab objects meant only for direct touch.
  • Rigidbody settings mismatched with the grab movement type cause jitter or objects lagging behind the hand.
  • Multiple interaction managers in a scene split arbitration and produce inconsistent selection.
  • Overlapping UI and grab targets without priority rules make menus hard to operate.
  • Treating the samples as final assets leaves untuned haptics and comfort settings in shipped products.

Performance is another consideration. Many active interactors performing raycasts or sphere casts every frame add measurable CPU cost on standalone headsets, so developers limit interaction layers and disable unused interactors.

In everyday language

The Unity XR Interaction Toolkit is a ready-made set of virtual hands and rules for apps built in Unity. Instead of teaching the program from zero how to pick up a cup, press a button or walk across a room, developers drop in prepared parts and adjust them.

Think of it like a kit of door handles, light switches and hinges for a house builder. The builder still designs the house, but does not have to forge every handle by hand. The key point is that one kit works across many headsets, so the same app behaves the same way on different devices.

Seen in the real world

A small training company builds a VR safety course for warehouse staff that must run on two different standalone headsets bought by a client. The developers install the toolkit with the OpenXR plug-in, import the Starter Assets rig and add grab interactables to a fire extinguisher, its safety pin and a valve wheel.

They use socket interactors so the pin snaps back into place during resets, a poke interactor for a wall-mounted alarm button, and teleport anchors placed in front of each station. Snap turn is set to 45 degrees for trainees who have never used a headset.

The result is one build that runs on both headsets with identical controls. When the client later asks for hand-tracking support, the team adds the XR Hands package and near-far interactors, and the existing interactables work without being rewritten.