48 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

UserInputService

Inherits from: Instance → Object

UserInputService is primarily used to detect the input types available on a user's device, as well as detect input events. It allows you to perform different actions depending on the device and, in turn, provide the best experience for the end user.

As this service is intended for client-side usage only, its properties, methods, and events can only be used in a LocalScript, a ModuleScript required by a LocalScript, or a Script with RunContext set to RunContext.Client.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service, NotReplicated

Properties

Name	Type / Returns	Description
UserInputService.AccelerometerEnabled	boolean	Describes whether the user's device has an accelerometer.
UserInputService.GamepadEnabled	boolean	Describes whether the user's device has an available gamepad.
UserInputService.GyroscopeEnabled	boolean	Describes whether the user's device has a gyroscope.
UserInputService.KeyboardEnabled	boolean	Describes whether the user's device has a keyboard available.
UserInputService.ModalEnabled	boolean	Toggles whether Roblox's mobile controls are hidden on mobile devices.
UserInputService.MouseBehavior	MouseBehavior	Determines whether the user's mouse can be moved freely or is locked.
UserInputService.MouseDeltaSensitivity	float	Scales the delta (change) output of the user's `Mouse`.
UserInputService.MouseEnabled	boolean	Describes whether the user's device has a mouse available.
UserInputService.MouseIcon	ContentId	The content ID of the image for the user's mouse icon.
UserInputService.MouseIconContent	Content	The content ID of the image for the user's mouse icon. Only supports asset URIs.
UserInputService.MouseIconEnabled	boolean	Determines whether the mouse icon is visible.
UserInputService.OnScreenKeyboardPosition	Vector2	Determines the position of the on-screen keyboard.
UserInputService.OnScreenKeyboardSize	Vector2	Determines the size of the on-screen keyboard.
UserInputService.OnScreenKeyboardVisible	boolean	Describes whether an on-screen keyboard is currently visible on the user's screen.
UserInputService.PreferredInput	PreferredInput	Queries the primary input type a player is using, based on anticipated user behavior.
UserInputService.TouchEnabled	boolean	Describes whether the user's device has a touch screen available.
UserInputService.TouchScreenEnabled	boolean	Describes whether the user's device has a touch screen, reflecting the device's true hardware capability.
UserInputService.UserHeadCFrame	CFrame	Describes the orientation and position of a user's head, if they are actively using a virtual reality headset.
UserInputService.VREnabled	boolean	Indicates whether the user is using a virtual reality headset.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

UserInputService.AccelerometerEnabled

This property describes whether the user's device has an accelerometer, a component found in most mobile devices that measures acceleration (change in speed).

If the device has an enabled accelerometer, you can get its current acceleration by using the GetDeviceAcceleration() method or track when the device's acceleration changes through the DeviceAccelerationChanged event.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-DeviceGravityChanged).

UserInputService.GamepadEnabled

This property describes whether the user's device has an available gamepad. If true, you can use gamepad‑related methods such as GetConnectedGamepads().

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

UserInputService.GyroscopeEnabled

This property describes whether the user's device has a gyroscope, a component found in most mobile devices that detects orientation and rotational speed.

If the device has a gyroscope, you can incorporate it into your experience using the GetDeviceRotation() method or track when the device's rotation changes through the DeviceRotationChanged event.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

UserInputService.KeyboardEnabled

This property describes whether the user's device has a keyboard available. If true, you can use key‑related methods such as IsKeyDown() or GetKeysPressed().

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

UserInputService.ModalEnabled

Deprecated. This item has been superseded by GuiService.TouchControlsEnabled which should be used in all new work.

The ModalEnabled property determines whether character controls are hidden on TouchEnabled devices. By default, this property is false and controls are visible.

This property will only work when used in a LocalScript running for the player whose character controls are to be hidden.

Even if mobile controls are hidden for a player on a touch‑enabled device, other events such as InputBegan and TouchSwipe can still be used to process other forms of input.

Field	Value
type	boolean
tags	["Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Behavior
serialization	{"can_load":false,"can_save":false}
capabilities	["Input"]

UserInputService.MouseBehavior

This property sets how the user's mouse behaves based on the MouseBehavior enum. It can be set to three values:

MouseBehavior.Default — The mouse moves freely around the user's screen.
MouseBehavior.LockCenter — The mouse is locked and cannot move from the center of the user's screen.
MouseBehavior.LockCurrentPosition — The mouse is locked and cannot move from its current position on the user's screen at the time of locking.

The value of this property does not affect the sensitivity of events tracking mouse movement. For example, GetMouseDelta returns the same Vector2 screen position in pixels regardless of whether the mouse is locked or able to move freely around the user's screen. As a result, default scripts like those controlling the camera are not impacted by this property.

This property is overridden if a GuiButton with Modal enabled is Visible unless the player's right mouse button is down.

Note that if the mouse is locked, InputChanged will still fire when the player moves the mouse and will pass in the delta that the mouse attempted to move by. Additionally, if the player is kicked from the experience, the mouse will be forcefully unlocked.

Field	Value
type	MouseBehavior
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Input"]

UserInputService.MouseDeltaSensitivity

This property determines the sensitivity of the user's Mouse. It can be used to adjust the sensitivity of events tracking mouse movement, such as GetMouseDelta().

This property does not affect the movement of the mouse icon, nor the camera sensitivity that the user has selected for their client.

This property has a maximum value of 10 and a minimum value of 0. When sensitivity is 0, events that track the mouse's movement will still fire but all parameters and properties indicating the change in mouse position will return 0.

Field	Value
type	float
tags	["NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":false}
capabilities	["Input"]

UserInputService.MouseEnabled

This property describes whether the user's device has a mouse available. If true, you can use mouse‑related methods such as GetMouseLocation().

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

UserInputService.MouseIcon

This property determines the content ID of the image for the user's mouse icon. If blank, a default arrow pointer is used. While the cursor hovers over certain UI objects such as an ImageButton, TextButton, TextBox, or ProximityPrompt, this image will be overridden and temporarily ignored.

To hide the cursor entirely, do not use a transparent image; instead, set MouseIconEnabled to false.

Field	Value
type	ContentId
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-MouseIcon).

UserInputService.MouseIconContent

To hide the cursor entirely, do not use a transparent image; instead, set MouseIconEnabled to false.

Field	Value
type	Content
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-MouseIcon).

UserInputService.MouseIconEnabled

This property determines whether the mouse icon is visible. To detect when this property changes, you must listen to when the MouseEnabled property changes.

Field	Value
type	boolean
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Input"]

UserInputService.OnScreenKeyboardPosition

This property describes the position of the on-screen keyboard in pixels. The keyboard's position is Vector2.new(0, 0) when it is not visible.

Field	Value
type	Vector2
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}
capabilities	["Input"]

UserInputService.OnScreenKeyboardSize

This property describes the size of the on-screen keyboard in pixels. The keyboard's size is Vector2.new(0, 0) when it is not visible.

Field	Value
type	Vector2
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}
capabilities	["Input"]

UserInputService.OnScreenKeyboardVisible

This property describes whether an on-screen keyboard is currently visible on the user's screen.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}
capabilities	["Input"]

UserInputService.PreferredInput

This read-only property lets you query the primary input type a player is likely using, based on anticipated user behavior, to ensure UI elements like on‑screen buttons and menus work elegantly across devices. For example, a touch‑enabled device assumes touch is the default input and that touch buttons may appear for actions, but if a player connects an additional bluetooth keyboard/mouse or gamepad, you can assume they want to switch to that as the primary input type and possibly use touch as a backup input for on‑screen UI.

The value of PreferredInput changes based on built‑in device inputs and the player's most recent interaction with a connected gamepad or keyboard/mouse. Examples include:

Real-World Scenario	`PreferredInput`
Player is using a phone with no other connected input devices; no possibility of an input type change.	`Enum.PreferredInput\|Touch`
Player is using a mobile device with a bluetooth keyboard & mouse connected, but no gamepad is connected.	`Enum.PreferredInput\|KeyboardAndMouse`
Player is using a tablet with a bluetooth gamepad connected, but no keyboard or mouse is connected.	`Enum.PreferredInput\|Gamepad`
Player is using an Xbox or PlayStation with a bluetooth keyboard & mouse connected and has most recently interacted with the keyboard or mouse.	`Enum.PreferredInput\|KeyboardAndMouse`
Player is on a Windows or Mac PC with a gamepad connected and has most recently interacted with the gamepad.	`Enum.PreferredInput\|Gamepad`

Field	Value
type	PreferredInput
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-PreferredInput).

UserInputService.TouchEnabled

This property describes whether the user's device has a touch screen available. If true, you can use touch‑related events such as TouchStarted and TouchMoved.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

UserInputService.TouchScreenEnabled

Read-only. Whether the user's device has a touch screen. Defaults to false; the engine sets it to true on devices with a physical touch screen.

Unlike TouchEnabled, which reports false on some touch-capable desktop hardware (such as a Windows laptop with a touch screen) to avoid switching those devices to mobile-style controls, TouchScreenEnabled reflects the device's true touch capability.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"RobloxScriptSecurity","write":"RobloxScriptSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

UserInputService.UserHeadCFrame

Deprecated. This item has been superseded by UserInputService:GetUserCFrame() which should be used in all new work.

The UserHeadCFrame used to describe the orientation and position of a user's head, if they are actively using a virtual reality headset.

Field	Value
type	CFrame
tags	["ReadOnly","NotReplicated","Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":false}
capabilities	["Input"]

UserInputService.VREnabled

Deprecated. This property has been superseded by VRService.VREnabled which should be used in all new work.

This property describes whether the user is using a virtual reality (VR) device. If true, you can use VR‑related properties, methods, and events in VRService.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":false,"can_save":true}
capabilities	["Input"]

Methods

Name	Type / Returns	Description
UserInputService:CreateVirtualInput	Object	Creates a `VirtualInput` object for simulating mouse, keyboard, and pointer input.
UserInputService:GamepadSupports	boolean	Returns whether the given `UserInputType` gamepad supports a button corresponding with the given `KeyCode`.
UserInputService:GetConnectedGamepads	Array	Returns an array of `UserInputType` gamepads currently connected.
UserInputService:GetDeviceAcceleration	InputObject	Returns an `InputObject` that describes the device's current acceleration.
UserInputService:GetDeviceGravity	InputObject	Returns an `InputObject` describing the device's current gravity vector.
UserInputService:GetDeviceRotation	Tuple	Returns an `InputObject` and a `CFrame` describing the device's current rotation vector.
UserInputService:GetFocusedTextBox	TextBox	Returns the `TextBox` the client is currently focused on.
UserInputService:GetGamepadConnected	boolean	Returns whether a gamepad with the given `UserInputType` is connected.
UserInputService:GetGamepadState	List	Returns an array of `InputObjects` for all available inputs on the given gamepad, representing each input's last input state.
UserInputService:GetImageForKeyCode	ContentId	Returns an image for the requested `KeyCode`.
UserInputService:GetKeysPressed	List	Returns an array of `InputObjects` associated with the `keys` currently being pressed down.
UserInputService:GetLastInputType	UserInputType	Returns the `UserInputType` associated with the user's most recent input.
UserInputService:GetMouseButtonsPressed	List	Returns an array of `InputObjects` associated with the mouse buttons currently being held down.
UserInputService:GetMouseDelta	Vector2	Returns the change, in pixels, of the position of the player's `Mouse` in the last rendered frame. Only works if the mouse is locked.
UserInputService:GetMouseLocation	Vector2	Returns the current screen location of the player's `Mouse` relative to the top-left corner of the screen.
UserInputService:GetNavigationGamepads	Array	Returns an array of gamepads connected and enabled for `GuiObject` navigation in descending order of priority.
UserInputService:GetStringForKeyCode	string	Returns a string representing a key the user should press in order to input a given `KeyCode`, optionally in an abbreviated format.
UserInputService:GetSupportedGamepadKeyCodes	Array	Returns an array of `KeyCodes` that the gamepad associated with the given `UserInputType` supports.
UserInputService:GetUserCFrame	CFrame	Returns a `CFrame` describing the position and orientation of a specified virtual reality device.
UserInputService:IsGamepadButtonDown	boolean	Determines whether a particular button is pressed on a gamepad.
UserInputService:IsKeyDown	boolean	Returns whether the given `key` is currently held down.
UserInputService:IsMouseButtonPressed	boolean	Returns whether the given mouse button is currently held down.
UserInputService:IsNavigationGamepad	boolean	Returns `true` if the specified gamepad is allowed to control navigation and selection `GuiObjects`.
UserInputService:RecenterUserHeadCFrame	()	Recenters the `CFrame` of the VR headset to the current orientation of the headset worn by the user.
UserInputService:SetNavigationGamepad	()	Sets whether or not the specified gamepad can move the `GuiObject` navigator.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

UserInputService:CreateVirtualInput

This method creates a VirtualInput object for simulating mouse, keyboard, and pointer input as if it were performed by a real user. It is intended for testing and automation workflows that need to simulate user interaction inside a running experience. Simulated input is restricted to the experience's own UI elements and cannot interact with arbitrary or system-level GUI.

Always check that the returned value is not nil before calling any methods on it.

Returns

Type	Description
Object	A new `VirtualInput` object, or `nil` if the feature is not available.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GamepadSupports

This method returns whether the given UserInputType gamepad supports a button corresponding with the given KeyCode.

Parameters

Name	Type	Default	Description
gamepadNum	UserInputType		The `UserInputType` of the gamepad.
gamepadKeyCode	KeyCode		The `KeyCode` of the button in question.

Returns

Type	Description
boolean	Whether the given gamepad supports a button corresponding with the given `KeyCode`.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetConnectedGamepads

This method returns an array of UserInputType gamepads currently connected. If no gamepads are connected, the array will be empty.

Alternatively to detecting all gamepads, the PreferredInput property can be used to more accurately reflect which input (mouse/keyboard, touch, gamepad, etc.) the player is likely using as the primary input.

Returns

Type	Description
Array	An array of `UserInputTypes` corresponding with the gamepads connected to the user's device.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetDeviceAcceleration

This method returns an InputObject that describes the device's current acceleration. For this to function, the user's device must have an enabled accelerometer as queried through the AccelerometerEnabled property.

To track when the device's acceleration changes, use the DeviceAccelerationChanged event.

Returns

Type	Description
InputObject	An `InputObject` describing the device's current acceleration, with `Position` representing the acceleration force on each local device axis.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-GetDeviceAcceleration).

UserInputService:GetDeviceGravity

This method returns an InputObject describing the device's current gravity vector. The vector is determined by the device's orientation relative to the real-world force of gravity. For example:

Vector3.new(0, 0, -9.81) if the device is perfectly upright (portrait)
Vector3.new(9.81, 0, 0) if the left side of the device is pointing down
Vector3.new(0, -9.81, 0) if the back of the device is pointing down

Gravity is only tracked for devices with an enabled gyroscope as queried through GyroscopeEnabled.

To track when the device's gravity changes, use the DeviceGravityChanged event.

Returns

Type	Description
InputObject	An `InputObject` describing the device's current gravity vector, with `Position` representing the force of gravity on each local device axis.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-GetDeviceGravity).

UserInputService:GetDeviceRotation

This method returns an InputObject and a CFrame describing the device's current rotation vector.

Device rotation is only tracked for devices with an enabled gyroscope as queried through GyroscopeEnabled.

Returns

Type	Description
Tuple	A tuple containing two properties: The delta describing the amount of rotation that last happened, and the `CFrame` of the device's current rotation relative to its default reference frame.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-GetDeviceRotation).

UserInputService:GetFocusedTextBox

This method returns the TextBox the client is currently focused on. A TextBox can be manually selected by the user, or selection can be forced using the TextBox:CaptureFocus() method. If no TextBox is selected, this method will return nil.

Returns

Type	Description
TextBox	The currently focused `TextBox`, or `nil` if no `TextBox` is focused.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetGamepadConnected

This method returns whether a gamepad with the given UserInputType is connected.

Alternatively to detecting a specific gamepad by UserInputType, the PreferredInput property can be used to more accurately reflect which input (mouse/keyboard, touch, gamepad, etc.) the player is likely using as the primary input.

Parameters

Name	Type	Default	Description
gamepadNum	UserInputType		The `UserInputType` of the gamepad in question.

Returns

Type	Description
boolean	Whether a gamepad associated with `UserInputType` is connected.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetGamepadState

This method returns an array of InputObjects for all available inputs on the given UserInputType gamepad, representing each input's last input state.

Parameters

Name	Type	Default	Description
gamepadNum	UserInputType		The `UserInputType` corresponding with the gamepad in question.

Returns

Type	Description
List	An array of `InputObjects` representing the current state of all available inputs for the given gamepad.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetImageForKeyCode

This method takes the requested KeyCode and returns the associated image for the currently connected gamepad device (limited to Xbox, PlayStation, and Windows). This means that if the connected controller is an Xbox One controller, the user sees Xbox assets. Similarly, if the connected device is a PlayStation controller, the user sees PlayStation assets. If you want to use custom assets, see GetStringForKeyCode().

For most use cases, consider using InputActionLabel instead. It is a GuiObject that automatically displays the correct key icon for an InputAction and updates when the player switches input devices or rebinds the action, without any scripting. GetImageForKeyCode() remains useful for advanced or fully custom interfaces where you need direct access to the underlying image asset.

Parameters

Name	Type	Default	Description
keyCode	KeyCode		The `KeyCode` for which to fetch the associated image.

Returns

Type	Description
ContentId	The returned image asset ID.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-GetImageForKeyCode).

UserInputService:GetKeysPressed

This method returns an array of InputObjects associated with the keys currently being pressed down. The array can be iterated through to determine which keys are currently being pressed, using the InputObject.KeyCode names or values.

To check if a specific key is being pressed, use IsKeyDown().

Returns

Type	Description
List	An array of `InputObjects` associated with the keys currently being pressed.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetLastInputType

This method returns the UserInputType associated with the user's most recent input. For example, if the user's previous input had been pressing the A key, the returned UserInputType value would be Keyboard.

For seamless cross-platform compatibility on mixed-input devices, see PreferredInput which more accurately reflects which input (mouse/keyboard, touch, gamepad, etc.) the player is likely using as the primary input. GetLastInputType() remains for advanced workflows or control schemes that rely on detecting and responding to the player's specific most recent UserInputType.

Returns

Type	Description
UserInputType	The `UserInputType` associated with the user's most recent input.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-GetLastInputType).

UserInputService:GetMouseButtonsPressed

This method returns an array of InputObjects associated with the mouse buttons currently being held down. The array can be iterated through to determine which buttons are currently being held, using the InputObject.KeyCode names or values.

Mouse buttons that are tracked by this method include MouseButton1 (left), MouseButton2 (right), and MouseButton3 (middle).

If the user is not pressing any mouse button down when the method is called, it will return an empty array.

Returns

Type	Description
List	An array of `InputObjects` corresponding to the mouse buttons currently being currently held down.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-GetMouseButtonsPressed).

UserInputService:GetMouseDelta

This method returns the change, in pixels, of the position of the player's Mouse in the last rendered frame, only if the mouse has been locked using the MouseBehavior property; otherwise the returned Vector2 values will be 0.

The sensitivity of the mouse, determined in the client's settings and MouseDeltaSensitivity, will influence the result.

Returns

Type	Description
Vector2	Change in movement of the mouse.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-GetMouseDelta).

UserInputService:GetMouseLocation

This method returns a Vector2 representing the current screen location of the player's Mouse in pixels relative to the top‑left corner. This does not account for the ScreenInsets; to get the top‑left and bottom‑right insets, call GuiService:GetGuiInset().

If the location of the mouse pointer is offscreen or the player's device does not have a mouse, the returned value will be undetermined.

Returns

Type	Description
Vector2	A `Vector2` representing the current screen location of the mouse, in pixels.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetNavigationGamepads

This method returns an array of gamepads that are connected and enabled for GuiObject navigation, but does not influence navigation controls. This list is in descending order of priority, meaning it can be iterated over to determine which gamepad should have navigation control.

Returns

Type	Description
Array	An array of `UserInputTypes` that can be used for navigation, in descending order of priority.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetStringForKeyCode

This method returns a string representing a key the user should press in order to input a given KeyCode, keeping in mind their keyboard layout. For key codes that require some modifier to be held, this method returns the key to be pressed in addition to the modifier. See the examples below for further explanation.

For most use cases, consider using InputActionLabel instead. It is a GuiObject that automatically displays the correct key text or icon for an InputAction and updates when the player switches input devices or rebinds the action, without any scripting. GetStringForKeyCode() remains useful for advanced or fully custom interfaces where you need the raw display string.

When using Roblox with a non‑QWERTY keyboard layout, key codes are mapped to equivalent QWERTY positions. For example, pressing A on an AZERTY keyboard results in KeyCode.Q, potentially leading to mismatched information on experience UI elements. This method solves the issue by providing the actual key to be pressed while using non‑QWERTY keyboard layouts.

KeyCode	QWERTY Return	AZERTY Return
`Enum.KeyCode.Q`	`Q`	`A`
`Enum.KeyCode.W`	`W`	`Z`
`Enum.KeyCode.Equals`	`=`	`=`
`Enum.KeyCode.At`	`2` because `@` is typed with `Shift2`	`É`

Abbreviated Format

When format is set to KeyCodeStringFormat.Abbreviated, the method returns shortened key names suitable for compact UI elements, for example "LCtrl" instead of "LeftControl", "Bksp" instead of "Backspace", or "Esc" instead of "Escape". If no abbreviation exists for the given key code, the default string is returned.

Gamepad Usage

GetStringForKeyCode() returns the string mapping for the KeyCode for the most recently connected gamepad. If the connected controller is not supported, the method returns the default string conversion for the requested key code.

The following example shows how you can map custom assets for ButtonA:

local UserInputService = game:GetService("UserInputService")

local imageLabel = script.Parent
local key = Enum.KeyCode.ButtonA

local mappings = {
	ButtonA = "rbxasset://BUTTON_A_ASSET", -- Replace with the desired ButtonA asset
	ButtonCross = "rbxasset://BUTTON_CROSS_ASSET"  -- Replace with the desired ButtonCross asset
}

local mappedKey = UserInputService:GetStringForKeyCode(key)
local image = mappings[mappedKey]

imageLabel.Image = image

Gamepad Mappings

The directional pad key codes do not have any differences based on device. KeyCode.ButtonSelect has slightly different behavior in some cases. Use both PlayStation mappings to ensure users see the correct buttons.

KeyCode	PlayStation Return Value	Xbox Return Value
`Enum.KeyCode.ButtonA`	`ButtonCross`	`ButtonA`
`Enum.KeyCode.ButtonB`	`ButtonCircle`	`ButtonB`
`Enum.KeyCode.ButtonX`	`ButtonSquare`	`ButtonX`
`Enum.KeyCode.ButtonY`	`ButtonTriangle`	`ButtonY`
`Enum.KeyCode.ButtonL1`	`ButtonL1`	`ButtonLB`
`Enum.KeyCode.ButtonL2`	`ButtonL2`	`ButtonLT`
`Enum.KeyCode.ButtonL3`	`ButtonL3`	`ButtonLS`
`Enum.KeyCode.ButtonR1`	`ButtonR1`	`ButtonRB`
`Enum.KeyCode.ButtonR2`	`ButtonR2`	`ButtonRT`
`Enum.KeyCode.ButtonR3`	`ButtonR3`	`ButtonRS`
`Enum.KeyCode.ButtonStart`	`ButtonOptions`	`ButtonStart`
`Enum.KeyCode.ButtonSelect`	`ButtonTouchpad` and `ButtonShare`	`ButtonSelect`

Legacy System Images

When using a KeyCode that may be better represented as an image, such as for an ImageLabel in a user interface, you can use the following legacy icons. However, it's recommended that you use GetImageForKeyCode() as a more modern, cross‑platform method to retrieve Xbox and PlayStation controller icons.

KeyCode	Asset ID
`Enum.KeyCode.ButtonX`	`rbxasset://textures/ui/Controls/xboxX.png`
`Enum.KeyCode.ButtonY`	`rbxasset://textures/ui/Controls/xboxY.png`
`Enum.KeyCode.ButtonA`	`rbxasset://textures/ui/Controls/xboxA.png`
`Enum.KeyCode.ButtonB`	`rbxasset://textures/ui/Controls/xboxB.png`
`Enum.KeyCode.DPadLeft`	`rbxasset://textures/ui/Controls/dpadLeft.png`
`Enum.KeyCode.DPadRight`	`rbxasset://textures/ui/Controls/dpadRight.png`
`Enum.KeyCode.DPadUp`	`rbxasset://textures/ui/Controls/dpadUp.png`
`Enum.KeyCode.DPadDown`	`rbxasset://textures/ui/Controls/dpadDown.png`
`Enum.KeyCode.ButtonSelect`	`rbxasset://textures/ui/Controls/xboxView.png`
`Enum.KeyCode.ButtonStart`	`rbxasset://textures/ui/Controls/xboxmenu.png`
`Enum.KeyCode.ButtonL1`	`rbxasset://textures/ui/Controls/xboxLB.png`
`Enum.KeyCode.ButtonR1`	`rbxasset://textures/ui/Controls/xboxRB.png`
`Enum.KeyCode.ButtonL2`	`rbxasset://textures/ui/Controls/xboxLT.png`
`Enum.KeyCode.ButtonR2`	`rbxasset://textures/ui/Controls/xboxRT.png`
`Enum.KeyCode.ButtonL3`	`rbxasset://textures/ui/Controls/xboxLS.png`
`Enum.KeyCode.ButtonR3`	`rbxasset://textures/ui/Controls/xboxRS.png`
`Enum.KeyCode.Thumbstick1`	`rbxasset://textures/ui/Controls/xboxLSDirectional.png`
`Enum.KeyCode.Thumbstick2`	`rbxasset://textures/ui/Controls/xboxRSDirectional.png`
`Enum.KeyCode.Backspace`	`rbxasset://textures/ui/Controls/backspace.png`
`Enum.KeyCode.Return`	`rbxasset://textures/ui/Controls/return.png`
`Enum.KeyCode.LeftShift`	`rbxasset://textures/ui/Controls/shift.png`
`Enum.KeyCode.RightShift`	`rbxasset://textures/ui/Controls/shift.png`
`Enum.KeyCode.Tab`	`rbxasset://textures/ui/Controls/tab.png`
`Enum.KeyCode.Quote`	`rbxasset://textures/ui/Controls/apostrophe.png`
`Enum.KeyCode.Comma`	`rbxasset://textures/ui/Controls/comma.png`
`Enum.KeyCode.Backquote`	`rbxasset://textures/ui/Controls/graveaccent.png`
`Enum.KeyCode.Period`	`rbxasset://textures/ui/Controls/period.png`
`Enum.KeyCode.Space`	`rbxasset://textures/ui/Controls/spacebar.png`

Parameters

Name	Type	Default	Description
keyCode	KeyCode		The `KeyCode` to get the display string for.
format	KeyCodeStringFormat	Default	An `KeyCodeStringFormat` value that controls the format of the returned string. Defaults to `KeyCodeStringFormat.Default`. Pass `KeyCodeStringFormat.Abbreviated` to get shortened labels suitable for compact UI such as `"Bksp"`, `"LCtrl"`, or `"Esc"`.

Returns

Type	Description
string	A string representing the key the user should press for the given key code, formatted according to the specified `KeyCodeStringFormat`.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetSupportedGamepadKeyCodes

This method returns an array of KeyCodes that the gamepad associated with the given UserInputType supports. If called on a non‑connected gamepad, returns an empty array.

To determine if a specific KeyCode is supported, use GamepadSupports().

Parameters

Name	Type	Default	Description
gamepadNum	UserInputType		The `UserInputType` of the gamepad.

Returns

Type	Description
Array	An array of `KeyCodes` supported by the given gamepad.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:GetUserCFrame

Deprecated. Use VRService:GetUserCFrame() instead.

The UserInputService:GetUserCFrame() method returns a CFrame describing the position and orientation of a specified UserCFrame virtual reality (VR) device. If the specified device is not connected, the method returns CFrame.new().

For example, the code snippet below prints the CFrame of the user's VR headset.

local UserInputService = game:GetService("UserInputService")
local cframe = UserInputService:GetUserCFrame(Enum.UserCFrame.Head)

print(cframe)

By using the method, players can implement features such as re-positioning the user's in-game character corresponding to the location of a connected VR device. This can be done by changing the CFrame of the user's in-game body parts to match the CFrame of the specified VR device using UserCFrame and CFrame value arguments passed by the event.

UserInputService:IsGamepadButtonDown

This method returns true if a particular button is pressed on a gamepad, otherwise returns false.

See also InputBinding as a way to hook gamepad and other input interactions to InputActions.

Parameters

Name	Type	Default	Description
gamepadNum	UserInputType		The `UserInputType` of the given gamepad.
gamepadKeyCode	KeyCode		The `KeyCode` of the specified gamepad button.

Returns

Type	Description
boolean	Whether the specified button on the given gamepad is pressed is pressed.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:IsKeyDown

This method returns true if a particular key is pressed on a keyboard, otherwise returns false.

See also InputBinding as a way to hook key and other input interactions to InputActions.

Parameters

Name	Type	Default	Description
keyCode	KeyCode		The `KeyCode` of the key.

Returns

Type	Description
boolean	Whether the specified key is being held down.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:IsMouseButtonPressed

This method returns true if a particular mouse button is pressed, otherwise returns false.

See also InputBinding as a way to hook mouse button and other input interactions to InputActions.

Parameters

Name	Type	Default	Description
mouseButton	UserInputType		The `UserInputType` of the mouse button.

Returns

Type	Description
boolean	Whether the given mouse button is currently held down.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:IsNavigationGamepad

This method returns true if the specified gamepad is allowed to control navigation and selection GuiObjects.

Use SetNavigationGamepad() to set a navigation gamepad, or GetNavigationGamepads() to get a list of all navigation gamepads.

Parameters

Name	Type	Default	Description
gamepadEnum	UserInputType		The `UserInputType` of the specified gamepad.

Returns

Type	Description
boolean	Whether the specified gamepad is a navigation gamepad.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:RecenterUserHeadCFrame

This method recenters the CFrame of the VR headset to the current orientation of the headset worn by the user. This means that the headset's current orientation is set to CFrame.new().

This method behaves identically to the VRService method RecenterUserHeadCFrame().

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

UserInputService:SetNavigationGamepad

This method sets whether the specified gamepad can move the GuiObject navigator.

Use IsNavigationGamepad() to check if a specified gamepad is a set to be a navigation gamepad, or GetNavigationGamepads() to retrieve a list of all navigation gamepads.

Parameters

Name	Type	Default	Description
gamepadEnum	UserInputType		The `UserInputType` of the specified gamepad.
enabled	boolean		Whether the specified gamepad can move the GUI navigator.

Returns

Type	Description
()

Field	Value
security	None
thread safety	Unsafe
capabilities	["Input"]

Events

Name	Type / Returns	Description
UserInputService.DeviceAccelerationChanged		Fires when a user moves a device that has an accelerometer.
UserInputService.DeviceGravityChanged		Fires when the force of gravity changes on a device that has an enabled accelerometer.
UserInputService.DeviceRotationChanged		Fires when a user rotates a device that has a gyroscope.
UserInputService.GamepadConnected		Fires when a gamepad is connected to the client.
UserInputService.GamepadDisconnected		Fires when a gamepad is disconnected from the client.
UserInputService.InputBegan		Fires when a user begins interacting with an input device such as a mouse or gamepad.
UserInputService.InputChanged		Fires when a user changes how they're interacting with an input device such as a mouse or gamepad.
UserInputService.InputEnded		Fires when a user stops interacting with an input device such as a mouse or gamepad.
UserInputService.JumpRequest		Fires whenever the client makes a request for their character to jump.
UserInputService.LastInputTypeChanged		Fires whenever the client's `UserInputType` is changed.
UserInputService.PointerAction		Fires when the user performs a specific pointer action.
UserInputService.TextBoxFocused		Fires when the client focuses on a `TextBox`.
UserInputService.TextBoxFocusReleased		Fires when the client loses focus on a `TextBox`.
UserInputService.TouchDrag		Fires when the user drags on the screen of a `TouchEnabled` device.
UserInputService.TouchEnded		Fires when a user releases their finger from the screen of a `TouchEnabled` device.
UserInputService.TouchLongPress		Fires when a user holds at least one finger for a short amount of time on the screen of a `TouchEnabled` device.
UserInputService.TouchMoved		Fires when a user moves their finger on the screen of a `TouchEnabled` device.
UserInputService.TouchPan		Fires when the user drags at least one finger on the screen of a `TouchEnabled` device.
UserInputService.TouchPinch		Fires when a user performs a pinch gesture on the screen of a `TouchEnabled` device.
UserInputService.TouchRotate		Fires when a user rotates two fingers on the screen of a `TouchEnabled` device.
UserInputService.TouchStarted		Fires when a user places their finger on the screen of a `TouchEnabled` device.
UserInputService.TouchSwipe		Fires on a `TouchEnabled` device when a user places their finger(s) down on the screen, pans across the screen, and lifts their finger(s) off with a certain speed of movement.
UserInputService.TouchTap		Fires when a user taps their finger on the screen of a `TouchEnabled` device.
UserInputService.TouchTapInWorld		Fires when a user taps their finger on the screen of a `TouchEnabled` device and the tap location is in the 3D world.
UserInputService.UserCFrameChanged		Fires when the `CFrame` of a specified Virtual Reality device changes.
UserInputService.WindowFocused		Fires when the window of the Roblox client gains focus on the user's screen.
UserInputService.WindowFocusReleased		Fires when the window of the Roblox client loses focus on the user's screen.

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.

UserInputService.DeviceAccelerationChanged

This event fires when a user moves a device that has an accelerometer, a component found in most mobile devices that measures acceleration (change in speed). To determine whether a user's device has an accelerometer enabled, use AccelerometerEnabled.

This event can be used along with GetDeviceAcceleration() to determine the current movement of a user's device.

Parameters

Name	Type	Default	Description
acceleration	InputObject		An `InputObject`, with a `UserInputType` of `Accelerometer` and `Position` that shows the force of gravity on each local device axis.

Field	Value
security	None
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-DeviceAccelerationChanged).

UserInputService.DeviceGravityChanged

This event fires when the device's gravity Vector3 changes on a device that has an accelerometer. To determine whether a user's device has an accelerometer enabled, use AccelerometerEnabled.

A device's gravity vector represent the force of gravity on each of the device's X, Y, and Z axes. While gravity never changes, the force it exerts on each axis changes when the device rotates and changes orientation. The force value exerted on each axis is a unit vector ranging from -1 to 1.

If the device has an enabled accelerometer, you can use the GetDeviceGravity() method to get the current force of gravity on the user's device.

Parameters

Name	Type	Default	Description
gravity	InputObject		An `InputObject` with a `Position` property that shows the force of gravity on each local device axis. This position can be used as a direction to determine the direction of gravity relative to the device.

Field	Value
security	None
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-DeviceGravityChanged).

UserInputService.DeviceRotationChanged

This event fires when a user rotates a device that has a gyroscope, a component found in most mobile devices that detects orientation and rotational speed. To check if a user's device has an enabled gyroscope, use GyroscopeEnabled.

To query the current device rotation, use the GetDeviceRotation() method.

Note that this event only fires when the Roblox client window is in focus. Inputs will not be captured when the window is minimized.

Parameters

Name	Type	Default	Description
rotation	InputObject		An `InputObject` providing info about the device's rotation. `Position` represents the new rotation a `Vector3` positional value and `Delta` represents the change in rotation in a `Vector3` positional value.
cframe	CFrame		A `CFrame` representing the device's current orientation.

Field	Value
security	None
capabilities	["Input"]

UserInputService.GamepadConnected

This event fires when a gamepad is connected to the client. You can also use GetConnectedGamepads() to find the correct gamepad to use.

Alternatively, you can detect value changes to the PreferredInput property which more accurately reflects which input (mouse/keyboard, touch, gamepad, etc.) the player is likely using as the primary input.

UserInputService.GamepadDisconnected

This event fires when a gamepad is disconnected from the client.

UserInputService.InputBegan

This event fires when a user begins interacting with an input device such as a mouse or gamepad, such as when they first interact with a gamepad button, although it does not capture mouse wheel movements. Can be used along with InputChanged and InputEnded to track when user input begins, changes, and ends.

See also InputBinding as a way to hook input device interactions to InputActions.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
input	InputObject		An `InputObject` instance containing information about the user's input.
gameProcessedEvent	boolean		Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.InputChanged

This event fires when a user changes how they're interacting with an input device such as a mouse or gamepad. Can be used along with InputBegan and InputEnded to track when user input begins, changes, and ends.

See also InputBinding as a way to hook input device interactions to InputActions.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
input	InputObject		An `InputObject` instance containing information about the user's input.
gameProcessedEvent	boolean		Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`. To ignore events that are automatically handled by Roblox like scrolling in a `ScrollingFrame`, check that `gameProcessedEvent` is `false`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.InputEnded

This event fires when a user stops interacting with an input device such as a mouse or gamepad, such as when they release a gamepad button. Can be used along with InputBegan and InputChanged to track when user input begins, changes, and ends.

See also InputBinding as a way to hook input device interactions to InputActions.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
input	InputObject		An `InputObject` instance containing information about the user input.
gameProcessedEvent	boolean		Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.JumpRequest

This event fires when there is a jump request from the client, for example when the client presses the spacebar or jump button on mobile. Default behavior is to set the player's Humanoid.Jump property to true which makes the player's character jump.

Since this event fires multiple times for a single jump request, using a debounce is recommended. This event does not fire if Player.Character is set to nil.

Field	Value
security	None
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-JumpRequest).

UserInputService.LastInputTypeChanged

This event fires whenever the client's UserInputType is changed.

To get the value of the last input type, regardless of whether it has changed, use the GetLastInputType() method.

Parameters

Name	Type	Default	Description
lastInputType	UserInputType		A `UserInputType` indicating the last input type.

Field	Value
security	None
capabilities	["Input"]

UserInputService.PointerAction

This event fires when the user performs a specific pointer action (wheel, pan, pitch).

Parameters

Name	Type	Description
wheel	float	The mouse scroll wheel delta. Positive values indicate scrolling up and negative values indicate scrolling down.
pan	Vector2	A `Vector2` representing the trackpad pan movement delta in pixels. Touch pan is handled separately via `UserInputService.TouchPan`.
pinch	float	The pinch-to-zoom gesture delta from a trackpad. Touch pinch is handled separately via `UserInputService.TouchPinch`.
gameProcessedEvent	boolean	Indicates whether the engine internally observed this input and acted on it.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TextBoxFocused

This event fires when the client gains focus on a TextBox, typically when a user clicks/taps it to begin inputting text. Also fires if the TextBox is focused using TextBox:CaptureFocus(). Can be used alongside TextBoxFocusReleased to track when a TextBox loses focus.

Parameters

Name	Type	Default	Description
textboxFocused	TextBox		The `TextBox` that gained focus.

Field	Value
security	None
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-TextBoxFocused).

UserInputService.TextBoxFocusReleased

This event fires when the client loses focus on a TextBox, typically when a user stops text entry by pressing Enter or clicking/touching elsewhere on the screen. Can be used alongside TextBoxFocused to track when a TextBox gains focus.

Parameters

Name	Type	Default	Description
textboxReleased	TextBox		The `TextBox` that lost focus.

Field	Value
security	None
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-TextBoxFocused).

UserInputService.TouchDrag

This event fires when the user drags on the screen of a TouchEnabled device. Use this event to detect the start of a deliberate directional gesture (for example, sliding an element left or right to reveal contextual actions) before the user commits to a direction; for detecting a completed swipe or fling gesture, use TouchSwipe instead.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Description
dragDirection	SwipeDirection	The predominant drag direction for the event (`Up`, `Down`, `Left`, or `Right`).
numberOfTouches	int	Currently only supports one touch for a value of `1`.
gameProcessedEvent	boolean	Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchEnded

This event fires when a user releases their finger from the screen of a TouchEnabled device. Can be paired with TouchStarted to determine when a user starts and stops touching the screen.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
touch	InputObject		An `InputObject` instance containing information about the user's input. This is the same object throughout the lifetime of the touch, so comparing `InputObjects` when they are touch objects is valid to determine if it's the same finger.
gameProcessedEvent	boolean		Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchLongPress

This event fires when a user holds at least one finger for a short amount of time on the screen of a TouchEnabled device.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Description
touchPositions	Array	An array of `Vector2` objects indicating the position of the fingers involved in the gesture.
state	UserInputState	The `UserInputState` of the gesture.
gameProcessedEvent	boolean	Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchMoved

This event fires when a user moves their finger on the screen of a TouchEnabled device, useful for tracking whether a user is moving their finger on the screen and where they're moving it. Can be paired with TouchStarted and TouchEnded to determine when a user starts touching the screen, how their finger moves while touching it, and when the they stop touching the screen.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
touch	InputObject		An `InputObject` instance containing information about the user's input. Note that its `Position` is a `Vector3` but only includes X and Y coordinates (Z is always `0`).
gameProcessedEvent	boolean		Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchPan

This event fires when the user drags at least one finger on the screen of a TouchEnabled device.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Description
touchPositions	Array	An array of `Vector2s` indicating the positions of the touches involved in the gesture.
totalTranslation	Vector2	The size of the pan gesture from start to end, in pixels.
velocity	Vector2	The speed of the pan gesture in pixels per second.
state	UserInputState	The `UserInputState` of the gesture.
gameProcessedEvent	boolean	Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchPinch

This event fires when a user performs a pinch gesture on the screen of a TouchEnabled device.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Description
touchPositions	Array	An array of `Vector2s` indicating the screen position, in pixels, of the fingers involved in the pinch gesture.
scale	float	The magnitude of the pinch from start to finish (in pixels) divided by the starting pinch positions.
velocity	float	The speed of the pinch gesture in pixels per second.
state	UserInputState	The `UserInputState` of the gesture.
gameProcessedEvent	boolean	Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchRotate

This event fires when a user rotates two fingers on the screen of a TouchEnabled device.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Description
touchPositions	Array	An array of `Vector2s` indicating the positions of the fingers involved in the gesture.
rotation	float	The number of degree the gesture has rotated since the start of the gesture.
velocity	float	The change in rotation (in degrees) divided by the duration of the change (in seconds).
state	UserInputState	The `UserInputState` of the gesture.
gameProcessedEvent	boolean	Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchStarted

This event fires when a user places their finger on the screen of a TouchEnabled device. Can be paired with TouchEnded to determine when a user starts and stops touching the screen.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
touch	InputObject		An `InputObject` instance, which contains information about the user's input. This is the same object throughout the lifetime of the touch, so comparing `InputObjects` when they are touch objects is valid to determine if it's the same finger.
gameProcessedEvent	boolean		Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchSwipe

This event fires on a TouchEnabled device when a user places their finger(s) down on the screen, pans across the screen, and lifts their finger(s) off with a certain speed of movement.

For more precise tracking of touch input movement, use TouchMoved.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Description
swipeDirection	SwipeDirection	An `SwipeDirection` indicating the direction the user swiped.
numberOfTouches	int	Number of touches involved in the swipe gesture.
gameProcessedEvent	boolean	Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchTap

This event fires when a user taps their finger on the screen of a TouchEnabled device, regardless of whether the user taps in the 3D world or on a GuiObject element. If you're looking for an event that only fires when the user taps in the 3D world, use TouchTapInWorld.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
touchPositions	Array		An array of `Vector2` objects indicating the position of the fingers involved in the tap gesture.
gameProcessedEvent	boolean		Indicates whether the engine internally observed this input and acted on it. Generally this refers to UI processing, so if a button was touched or clicked from this input, `gameProcessedEvent` will be `true`.

Field	Value
security	None
capabilities	["Input"]

UserInputService.TouchTapInWorld

This event fires when a user taps their finger on the screen of a TouchEnabled device and the tap location is in the 3D world rather than on a GuiObject element.

Note that this event only fires when the Roblox client window is in focus. It will not fire when the window is minimized.

Parameters

Name	Type	Default	Description
position	Vector2		A `Vector2` indicating the position of the tap.
processedByUI	boolean		Whether the user tapped a UI element.

Field	Value
security	None
capabilities	["Input"]

UserInputService.UserCFrameChanged

Deprecated. Use VRService.UserCFrameChanged instead.

The UserCFrameChanged event fires when the CFrame of a VR device changes.

This event can be used to track the movement of a connected VR device.

Using the event, you can implement features such as moving the user's in-game character limbs as the user moves their VR device. This can be done by changing the CFrame of the user's in-game limbs to match the CFrame changes of the VR device using the UserCFrame enum and CFrame value arguments passed by the event.

To retrieve the CFrame of a connected VR device, use UserInputService:GetUserCFrame().

As the event fires locally, it can only be used in a LocalScript.

UserInputService.WindowFocused

This event fires when the window of the Roblox client gains focus, typically when it is maximized or actively opened by the user. Can be used alongside WindowFocusReleased to track when the client loses focus on a user's screen.

Field	Value
security	None
capabilities	["Input"]

UserInputService.WindowFocusReleased

This event fires when the window of the Roblox client loses focus, typically when it is minimized by the user. Can be used alongside WindowFocused to track when the client gains focus on a user's screen.

Field	Value
security	None
capabilities	["Input"]

Code samples: View on Creator Hub (UserInputService-Window-Focus-Client, UserInputService-Window-Focus-Server).

Name	Type	Default	Description
type	UserCFrame		A `UserCFrame` value indicating which body part moved.
value	CFrame		A `CFrame` value indicating the updated CFrame of the body part that moved.