You can use the Input System package to control any in-game UI created with the Unity UI package. The integration between the Input System and the UI system is handled by the
NOTE: The Input System package does not currently support IMGUI or UIElements.
InputSystemUIInputModule component acts as a drop-in replacement for the
StandaloneInputModule component that the Unity UI package.
InputSystemUIInputModule provides the same functionality as
StandaloneInputModule, but it uses the Input System instead of the legacy Input Manager to drive UI input.
If you have a
StandaloneInputModule component on a GameObject, and the Input System is installed, Unity shows a button in the Inspector offering to automatically replace it with a
InputSystemUIInputModule for you. The
InputSystemUIInputModule is pre-configured to use default Input Actions to drive the UI, but you can override that configuration to suit your needs.
You can use the following properties to configure
||The initial delay (in seconds) between generating an initial
||The interval (in seconds) between generating repeat navigation events when the Move Action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.|
By default, this references a built-in Asset named DefaultInputActions, which contains common default Actions for driving UI. If you want to set up your own Actions, create a custom Input Action Asset and assign it here. When you assign a new Asset reference to this field in the Inspector, the Editor attempts to automatically map Actions to UI inputs based on common naming conventions.
||By default, when the pointer is clicked and does not hit any
||How to deal with multiple pointers feeding input into the UI. See pointer-type input.|
You can use the following properties to map Actions from the chosen Actions Asset to UI input Actions. In the Inspector, these appear as foldout lists that contain all the Actions in the Asset:
||An Action that delivers a 2D screen position. Use as a cursor for pointing at UI elements to implement mouse-style UI interactions. See pointer-type input.|
||An Action that maps to the primary cursor button used to interact with UI. See pointer-type input.|
||An Action that maps to the middle cursor button used to interact with UI. See pointer-type input.|
||An Action that maps to the secondary cursor button used to interact with UI. See pointer-type input.|
||An Action that delivers gesture input to allow scrolling in the UI. See pointer-type input.|
||An Action that delivers a 2D vector used to select the currently active UI selectable. This allows a gamepad or arrow-key style navigation of the UI. See navigation-type input.|
||An Action to engage with or "click" the currently selected UI selectable. See navigation-type input.|
||An Action to exit any interaction with the currently selected UI selectable. See navigation-type input.|
||An Action that delivers a 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with
||An Action that delivers a
How the bindings work
The UI input module can deal with three different types of input:
- pointer-type input,
- navigation-type input, and
- tracked-type input.
For each of these types of input, input is sourced and combined from a specific set of Actions as detailed below.
To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from
NOTE: The UI input module does not have an association between pointers and cursors. In general, the UI is oblivious to whether a cursor exists for a particular pointer. However, for mouse and pen input, the UI input module will respect
Cusor.lockStateand pin the pointer position at
(-1,-1)whenever the cursor is locked.
Multiple pointer devices may feed input into a single UI input module. Also, in the case of
Touchscreen, a single device can have the ability to have multiple concurrent pointers (each finger contact is one pointer).
From the perspective of
InputDevice that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each
Touchscreen devices, each separate
TouchControl that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique
pointerId which generally corresponds to the
deviceId of the pointer. However, for touch, this will be a combination of
ExtendedPointerEventData.touchId to find the ID for a touch event.
You can influence how the input module deals with concurrent input from multiple pointers using the
Pointer Behavior setting.
If concurrent input is received on a
Note that when input is received from touch or tracked devices, the single unified pointer for mice and pens is removed including
This is the default behavior.
||All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input. This means, for example, that regardless how many devices feed input into
||The UI input module will not unify any pointer input. Any device, including touch and tracked devices that feed input pointer-type actions, will be its own pointer (or multiple pointers for touch input).
Note: This might mean that there will be an arbitrary number of pointers in the UI, and several objects might be pointed at concurrently.
NOTE: If you bind a device to a pointer-type action such as
Left Clickwithout also binding it to
Point, the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind
Left Clickto the
Pointto the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse.
For pointer-type input (as well as for [tracked-type input](#tracked-type input)),
InputSystemUIInputModule will send
ExtendedPointerEventData instances which are an extended version of the base
PointerEventData. These events contain additional data such as the device and pointer type which the event has been generated from.
Navigation-type input controls the current selection based on motion read from the
move action. Additionally, input from
submit will trigger
ISubmitHandler on the currently selected object and
Cancel will trigger
ICancelHandler on it.
Inputs received on these actions are independent of each other. Thus, an arbitrary set of devices can be bound to these actions and feed input in arbitrary order.
Navigation input is non-positional, that is, unlike with pointer-type input, there is no screen position associcated with these actions. Rather, navigation actions always operate on the current selection.
Input from tracked devices such as XR controllers and HMDs essentially behaves like pointer-type input. The main difference is that the world-space device position and orientation sourced from
trackedDeviceOrientation is translated into a screen-space position via raycasting.
For this raycasting to work, you need to add
TrackedDeviceRaycaster to the
GameObject that has the UI's
Canvas component. This
GameObject will usually have a
GraphicRaycaster component which, however, only works for 2D screen-space raycasting. You can put
GraphicRaycaster and both can be enabled at the same time without advserse effect.
The Input System can also handle multiple separate UI instances on the screen controlled separately from different input Bindings. This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. To allow this, you need to replace the
EventSystem component from Unity with the Input System's
EventSystem component, you can have multiple
MultiplayerEventSystems active in the Scene at the same time. That way, you can have multiple players, each with their own
MultiplayerEventSystem components, and each player can have their own set of Actions driving their own UI instance. If you are using the
PlayerInput component, you can also set up
PlayerInput to automatically configure the player's
InputSystemUIInputModule to use the player's Actions. See the documentation on
PlayerInput to learn how.
The properties of the
MultiplayerEventSystem component are identical with those from the Event System. Additionally, the
MultiplayerEventSystem component adds a
playerRoot property, which you can set to a GameObject that contains all the UI selectables this event system should handle in its hierarchy. Mouse input that this event system processes then ignores any UI selectables which are not on any GameObject in the Hierarchy under