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.
| Component | Role | Typical example |
|---|---|---|
| Interaction manager | Arbitrates every interactor and interactable | One per scene, created automatically |
| Interactor | Detects targets and initiates interaction | Ray, direct, poke, gaze or socket interactor |
| Interactable | Responds to hover, select and activate | Grab interactable on a tool or door handle |
| Interaction group | Lets one interactor at a time win priority | Hand prefers direct grab over ray |
| XR Origin | Maps tracking space to the scene | Camera offset and controller transforms |
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.
| Interactor | Interaction metaphor | Best suited for | Main limitation |
|---|---|---|---|
| Direct interactor | Touch and grab within reach | Picking up nearby objects | Requires a trigger collider near the hand |
| Ray interactor | Laser pointer at a distance | Menus and distant targets | Jitter grows with distance |
| Near-far interactor | Blends near grab and far casting | Unified hand or controller input | More settings to tune |
| Poke interactor | Fingertip pressing a surface | Buttons and touch panels | Needs depth thresholds per control |
| Gaze interactor | Head or eye direction | Hands-free selection | Needs dwell time or confirmation |
| Socket interactor | Snap point that holds objects | Holsters, slots and assembly steps | Not driven by the user directly |
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.
How it compares with related XR tools
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.
| Tool | Layer | Relationship to XRI |
|---|---|---|
| OpenXR | Cross-vendor runtime standard | Supplies the device data XRI consumes |
| AR Foundation | Unity AR abstraction | Combines with XRI for AR placement and gestures |
| Meta XR All-in-One SDK | Vendor SDK with its own interaction system | Alternative or complement on Meta headsets |
| MRTK3 | Mixed reality toolkit | Builds its interactions on top of XRI |
| WebXR | Browser API | Separate ecosystem outside Unity |
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.
| Decision | Recommended choice | Reason |
|---|---|---|
| XR provider | OpenXR plug-in with vendor feature groups | Widest device coverage from one build |
| Input handling | Input System actions from Starter Assets | Tested bindings for common controllers |
| Hand tracking | Add XR Hands and near-far interactors | Same interactables work with hands and controllers |
| Grab movement type | Velocity tracking for physics props | Prevents objects passing through walls |
| Locomotion default | Teleport plus snap turn | Most comfortable for new users |
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.