Keyboard support

The Keyboard class defines a Device with a set of key Controls defined by the Key enumeration.

The location of individual keys is agnostic to keyboard layout. This means that, for example, the A key is always the key to the right of the Caps Lock key, regardless of where the currently active keyboard layout places the key that generates an a character, or whether or not the layout doesn't have a key assigned to that character.

To query which (if any) character is generated by a given key, use the key Control's displayName property. The value of this property changes automatically when the OS changes the keyboard layout.

You can look up keys based on the character they produce using Control paths. For example, you can query the key that produces the producing the a character from Keyboard using Keyboard.current["#(a)"].

Note

  • Keyboards usually have hardware limitations on both the number of simultaneous keypresses they report, and the combinations of keys they support. This means that certain simultaneous keypresses may not register correctly. For example, a given keyboard might report a simultaneous press of the "QWERT" keys correctly, but might not report "QWERA" correctly.
  • At the moment, the new Input System doesn't support on-screen keyboards. For now, please Unity's existing API in UnityEngine.TouchScreenKeyboard.
  • At the moment, Unity platform backends generally do not support distinguishing between multiple keyboards. While the Input System supports having many Keyboard devices at any point, platform backends generally only report a single keyboard and route input from all attached keyboards to the one keyboard device.

Controls

To retrieve a key from Keyboard, you can use one of these methods:

  • Use the key's accessor property, such Keyboard.spaceKey.
  • Use Keyboard's indexer and the Key enumeration (for example, keyboard[Key.Space]).

The scripting API reference for the Keyboard class lists all the properties for the individual key Controls.

Two special Controls, anyKey and imeSelected, don't directly map to individual keys. anyKey is a synthetic button Control which reports whether any key on the keyboard is pressed, and imeSelected reports whether or not IME text processing is enabled.

In addition, Keyboard's indexer and the Key has three synthetic controls that represent combinations of modifier keys:

Control Description
shiftKey A button that is pressed if leftShiftKey and/or rightShiftKey is pressed.
ctrlKey A button that is pressed if leftCtrlKey and/or rightCtrlKey is pressed.
altKey A button that is pressed if leftAltKey and/or rightAltKey is pressed.

Text input

As a best practice, you shouldn't manually translate text input from key presses by trying to string together the characters corresponding to the keys. Instead, to listen to text input, hook into Keyboard.onTextInput. This delivers character-by-character input as reported by the platform, including input from on-screen keyboards.

Note that the text input API doesn't allocate GC memory because it doesn't deliver fully composed strings.

IME

Some writing systems, such as some East-Asian scripts, are too complex to represent all characters as individual keys on a keyboard. For these layouts, operating systems implement IMEs (Input Method Editors) to allow composing input strings by other methods, for instance by typing several keys to produce a single character. Unity's UI frameworks for text input support IME without any additional configuration. If you want to build your own UI for text input, the Keyboard class allows you to work with input from IMEs using the following APIs:

  • imeSelected is a virtual input Control that reports whether IME text processing is enabled.

  • SetIMEEnabled() is a method which lets you turn IME processing on or off. Typically, IME processing is useful when the user wants to edit text, but not so much when the user is using the keyboard to control a game.

  • SetIMECursorPosition(). IMEs might open system windows that let users interactively edit the text they want to input. Typically, these open next to the text editing UI. You can use the SetIMECursorPosition() method to tell the OS where that is.

  • onIMECompositionChange is an event you can subscribe to in order to receive all updates to the IME composition string. The composition string is the text input the user is currently editing using an IME. Typically, any UI dealing with text input displays this text (with some visual indication of it being actively edited, usually an underline) at the current text input cursor position.

Keyboard layouts

You can query the name of the current keyboard layout using Keyboard.keyboardLayout. Layout names are platform-specific.

There is no support for setting keyboard layouts from your application.

To monitor keyboard layout changes, hook into InputSystem.onDeviceChange and check for InputDeviceChange.ConfigurationChanged on a Keyboard device.

To find the key control that corresponds to a specific display character sequence, call Keyboard.FindKeyOnCurrentKeyboardLayout.

// Find key that generates a 'q' character according to the current keyboard layout.
Keyboard.current.FindKeyOnCurrentKeyboardLayout("q");