PcoWSkbVqDnWTu_dm2ix
The Developer Hub is now deprecated and information on this page may no longer be accurate. To see our new and improved documentation, please click here. You can read more about the future of documentation here.
Collapse Sidebar
  1. API Reference
  2. UserInputService

UserInputService

Show deprecated
Hide content
  1. apireference
  2. userinputservice

UserInputService

Show deprecated

The UserInputService is a service used to detect and capture the different types of input available on a user’s device.

The primary purpose of this service is to allow for games to cooperate with multiple forms of available input - such as gamepads, touch screens, and keyboards. It allows a LocalScript to perform different actions depending on the device, and in turn, helps developers provide the best experience for the end user.

Some usages of this service include detecting user input when they interact with GUIs, tools, and other game instances. In order to detect user input, the service must look for a service event. For example, the service can detect events such as when the user touches the screen of a mobile device using UserInputService/TouchStarted, or connects a gamepad such as an Xbox controller to their device using UserInputService/GamepadConnected.

Since this service is client-side only, it will only work when used in a LocalScript or a ModuleScript required by a LocalScript. As UserInputService is client-side only, users in the game can only detect their own input - and not the input of others.

See also

  • ContextActionService, a service which allows you to bind functions to multiple user inputs

Properties

bool

AccelerometerEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s device has an accelerometer
Vector2

BottomBarSize

[Hidden] [ReadOnly] [NotReplicated]
bool

GamepadEnabled

[ReadOnly] [NotReplicated]

Describes whether the device being used by a user has an available gamepad
bool

GazeSelectionEnabled

[Hidden] [NotReplicated]
bool

GyroscopeEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s device has a gyroscope
bool

KeyboardEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s device has a keyboard available
bool

LegacyInputEventsEnabled

[Hidden]
bool

ModalEnabled

[Deprecated]

Toggles whether Roblox’s mobile controls are hidden on mobile devices
MouseBehavior

MouseBehavior

Determines whether the user’s mouse can be moved freely or is locked
float

MouseDeltaSensitivity

[NotReplicated]

Scales the delta (change) output of the user’s Mouse
bool

MouseEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s device has a mouse available
bool

MouseIconEnabled

Determines whether the Mouse|Mouse’s icon is visible
Vector2

NavBarSize

[Hidden] [ReadOnly] [NotReplicated]
double

OnScreenKeyboardAnimationDuration

[Hidden] [ReadOnly] [NotReplicated]
Vector2

OnScreenKeyboardPosition

[ReadOnly] [NotReplicated]

Determines the position of the on-screen keyboard
Vector2

OnScreenKeyboardSize

[ReadOnly] [NotReplicated]

Determines the size of the on-screen keyboard
bool

OnScreenKeyboardVisible

[ReadOnly] [NotReplicated]

Describes whether an on-screen keyboard is currently visible on the user’s screen
OverrideMouseIconBehavior

OverrideMouseIconBehavior

[Hidden]
Vector2

RightBarSize

[Hidden] [ReadOnly] [NotReplicated]
Vector2

StatusBarSize

[Hidden] [ReadOnly] [NotReplicated]
bool

TouchEnabled

[ReadOnly] [NotReplicated]

Describes whether the user’s current device has a touch-screen available
CFrame

UserHeadCFrame

[ReadOnly] [NotReplicated] [Deprecated]

Describes the orientation and position of a user’s head, if they are actively using a virtual reality headset
bool

VREnabled

[ReadOnly] [NotReplicated]

Indicates whether the user is using a virtual reality headset

Inherited from Instance: Show Hide

bool

Archivable

Determines if an Instance can be cloned using /Instance/Clone or saved to file.
string

ClassName

[ReadOnly] [NotReplicated]

A read-only string representing the class this Instance belongs to
int

DataCost

[Hidden] [ReadOnly] [NotReplicated] [Deprecated]

The cost of saving the instance using data persistence.
string

Name

A non-unique identifier of the Instance
Instance

Parent

[NotReplicated]

Determines the hierarchical parent of the Instance
bool

RobloxLocked

[Hidden]

A deprecated property that used to protect CoreGui objects
int64

SourceAssetId

[Hidden] [NotReplicated]
bool

archivable

[Hidden] [NotReplicated] [Deprecated]
string

className

[ReadOnly] [NotReplicated] [Deprecated]

Functions

bool

GamepadSupports ( UserInputType gamepadNum , KeyCode gamepadKeyCode )

Returns whether the given Enum/UserInputType gamepad supports a button corresponding with the given Enum/KeyCode
Array

GetConnectedGamepads ( )

Returns an array of Enum/UserInputType gamepads currently connected
InputObject

GetDeviceAcceleration ( )

Returns an InputObject that describes the device’s current acceleration
InputObject

GetDeviceGravity ( )

Returns an InputObject describing the device’s current gravity vector
Tuple

GetDeviceRotation ( )

Returns an InputObject and a DataType/CFrame,describing the device’s current rotation vector
DeviceType

GetDeviceType ( )

TextBox

GetFocusedTextBox ( )

Returns the currently TextBox the client is currently focused on
bool

GetGamepadConnected ( UserInputType gamepadNum )

Returns whether a gamepad with the given Enum/UserInputType’‘gamepadNum’’ is connected
Array

GetGamepadState ( UserInputType gamepadNum )

Returns an array of InputObject|InputObjects for all available inputs on the given gamepad, representing each input’s last input state
Array

GetKeysPressed ( )

Returns an array of InputObject|InputObjects associated with the Enum/KeyCode|keys currently being pressed down
UserInputType

GetLastInputType ( )

Returns the Enum/UserInputType associated with the user’s most recent input
Array

GetMouseButtonsPressed ( )

Returns an array of InputObject|InputObjects corresponding with the mouse buttons currently being held down
Vector2

GetMouseDelta ( )

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
Vector2

GetMouseLocation ( )

Returns the current screen location of the player’s Mouse relative to the top left corner of the screen
Array

GetNavigationGamepads ( )

Returns an array of Enum/UserInputType|gamepads connected and enabled for GUI navigation in descending order of priority
Platform

GetPlatform ( )

string

GetStringForKeyCode ( KeyCode keyCode )

Returns a string representing a key the user should press in order to input a given KeyCode
Array

GetSupportedGamepadKeyCodes ( UserInputType gamepadNum )

Returns an array of Enum/KeyCode|KeyCodes that the gamepad associated with the given Enum/UserInputType supports
CFrame

GetUserCFrame ( UserCFrame type )

Returns a DataType/CFrame describing the position and orientation of a specified virtual reality device
bool

IsGamepadButtonDown ( UserInputType gamepadNum , KeyCode gamepadKeyCode )

Determines whether a particular button is pressed on a particular gamepad
bool

IsKeyDown ( KeyCode keyCode )

Returns whether the given Enum/KeyCode|key is currently held down
bool

IsMouseButtonPressed ( UserInputType mouseButton )

Returns whether the given Enum/UserInputType|mouse button is currently held down
bool

IsNavigationGamepad ( UserInputType gamepadEnum )

Returns true if the specified Enum/UserInputTypeGamepad is allowed to control the navigation GuiObject|GUIs
void

RecenterUserHeadCFrame ( )

Recenters the DataType/CFrame of the VR headset to the current orientation of the headset worn by the user
void

SendAppUISizes ( Vector2 statusBarSize , Vector2 navBarSize , Vector2 bottomBarSize , Vector2 rightBarSize )

void

SetNavigationGamepad ( UserInputType gamepadEnum , bool enabled )

Sets whether or not the specified Enum/UserInputType|Gamepad can move the GuiObject|GUI navigator

Inherited from Instance: Show Hide

void

ClearAllChildren ( )

This function destroys all of an Instance’s children.
Instance

Clone ( )

Create a copy of an object and all its descendants, ignoring objects that are not Instance/Archivable|Archivable
void

Destroy ( )

Sets the Instance/Parent property to nil, locks the Instance/Parent property, disconnects all connections, and calls Destroy on all children.
Instance

FindFirstAncestor ( string name )

Returns the first ancestor of the Instance whose Instance/Name is equal to the given name.
Instance

FindFirstAncestorOfClass ( string className )

Returns the first ancestor of the Instance whose Instance/ClassName is equal to the given className.
Instance

FindFirstAncestorWhichIsA ( string className )

Returns the first ancestor of the Instance for whom Instance/IsA returns true for the given className.
Instance

FindFirstChild ( string name , bool recursive )

Returns the first child of the Instance found with the given name.
Instance

FindFirstChildOfClass ( string className )

Returns the first child of the Instance whose Instance/ClassName|ClassName is equal to the given className.
Instance

FindFirstChildWhichIsA ( string className , bool recursive )

Returns the first child of the Instance for whom Instance/IsA returns true for the given className.
Instance

FindFirstDescendant ( string name )

Returns the first descendant found with the given Instance/Name.
Actor

GetActor ( )

Returns the Actor associated with the Instance, usually the first Actor ancestor
Variant

GetAttribute ( string attribute )

Returns the attribute which has been assigned to the given name
RBXScriptSignal

GetAttributeChangedSignal ( string attribute )

Returns an event that fires when the given attribute changes
Dictionary

GetAttributes ( )

Returns a dictionary of string → variant pairs for each of the Instance|Instance’s attributes
Objects

GetChildren ( )

Returns an array containing all of the Instance’s children.
string

GetDebugId ( int scopeLength )

[NotBrowsable]

Returns a coded string of the Instances DebugId used internally by Roblox.
Array

GetDescendants ( )

[CustomLuaState]

Returns an array containing all of the descendants of the instance
string

GetFullName ( )

Returns a string describing the Instance’s ancestry.
RBXScriptSignal

GetPropertyChangedSignal ( string property )

Get an event that fires when a given property of an object changes.
bool

IsA ( string className )

[CustomLuaState]

Returns true if an Instance’s class matches or inherits from a given class
bool

IsAncestorOf ( Instance descendant )

Returns true if an Instance is an ancestor of the given descendant.
bool

IsDescendantOf ( Instance ancestor )

Returns true if an Instance is a descendant of the given ancestor.
void

Remove ( )

[Deprecated]

Sets the object’s Parent to nil, and does the same for all its descendants.
void

SetAttribute ( string attribute , Variant value )

Sets the attribute with the given name to the given value
Instance

WaitForChild ( string childName , double timeOut )

[CustomLuaState] [CanYield]

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.
Objects

children ( )

[Deprecated]

Returns an array of the object’s children.
Instance

clone ( )

[Deprecated]
void

destroy ( )

[Deprecated]
Instance

findFirstChild ( string name , bool recursive )

[Deprecated]
Objects

getChildren ( )

[Deprecated]
bool

isA ( string className )

[Deprecated] [CustomLuaState]
bool

isDescendantOf ( Instance ancestor )

[Deprecated]
void

remove ( )

[Deprecated]

Events

RBXScriptSignal

DeviceAccelerationChanged ( InputObject acceleration )

Fired when a user moves a device that has an accelerometer. Used to track real-world device movement within a Roblox game
RBXScriptSignal

DeviceGravityChanged ( InputObject gravity )

Fired when the force of gravity changes on a device that has an enabled accelerometer - such as a mobile device
RBXScriptSignal

DeviceRotationChanged ( InputObject rotation , CFrame cframe )

Fired when a user rotates a device that has a gyroscope
RBXScriptSignal

GamepadConnected ( UserInputType gamepadNum )

Fires when a gamepad is connected to the client. Passes the ‘‘gamepadNum’’ of the gamepad that was connected
RBXScriptSignal

GamepadDisconnected ( UserInputType gamepadNum )

Fires when a gamepad is disconnected from the client. Passes the Enum/UserInputType of the gamepad that was disconnected
RBXScriptSignal

InputBegan ( InputObject input , bool gameProcessedEvent )

Fired when a user begins interacting via a Human-Computer Interface device - such as a mouse or gamepad
RBXScriptSignal

InputChanged ( InputObject input , bool gameProcessedEvent )

Fired when a user changes how they’re interacting via a Human-Computer Interface device
RBXScriptSignal

InputEnded ( InputObject input , bool gameProcessedEvent )

Fires when a user stops interacting via a Human-Computer Interface device
RBXScriptSignal

JumpRequest ( )

Fires whenever the client makes a request for their character to jump
RBXScriptSignal

LastInputTypeChanged ( UserInputType lastInputType )

Fires when the client’s Enum/UserInputType is changed
RBXScriptSignal

PointerAction ( float wheel , Vector2 pan , float pinch , bool gameProcessedEvent )

Fires when the user performs a specific pointer action (wheel, pinch, pan).
RBXScriptSignal

StatusBarTapped ( Vector2 position )

RBXScriptSignal

TextBoxFocusReleased ( TextBox textboxReleased )

Fired when the client loses focus on a TextBox
RBXScriptSignal

TextBoxFocused ( TextBox textboxFocused )

Fired when the client focuses on a TextBox
RBXScriptSignal

TouchEnded ( InputObject touch , bool gameProcessedEvent )

Fired when a user releases their finger from the screen on a TouchEnabled device - such as the screen of a mobile device
RBXScriptSignal

TouchLongPress ( Array touchPositions , UserInputState state , bool gameProcessedEvent )

Fired when a user holds at least one finger for a short amount of time on the same screen position on a TouchEnabled device - such as the screen of a mobile device
RBXScriptSignal

TouchMoved ( InputObject touch , bool gameProcessedEvent )

Fired when a user moves their finger on a TouchEnabled device - such as the screen of an Apple iPad or iPhone or a Google Android phone
RBXScriptSignal

TouchPan ( Array touchPositions , Vector2 totalTranslation , Vector2 velocity , UserInputState state , bool gameProcessedEvent )

Fired when a user drags at least one finger on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of an mobile device
RBXScriptSignal

TouchPinch ( Array touchPositions , float scale , float velocity , UserInputState state , bool gameProcessedEvent )

Fired when a user pinches their fingers on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device
RBXScriptSignal

TouchRotate ( Array touchPositions , float rotation , float velocity , UserInputState state , bool gameProcessedEvent )

Fires when a user rotates two fingers on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device
RBXScriptSignal

TouchStarted ( InputObject touch , bool gameProcessedEvent )

Fired when a user places their finger on a TouchEnabled device - such as the screen of an Apple iPad or iPhone or a Google Android phone
RBXScriptSignal

TouchSwipe ( SwipeDirection swipeDirection , int numberOfTouches , bool gameProcessedEvent )

Fired when a user swipes their fingers on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device
RBXScriptSignal

TouchTap ( Array touchPositions , bool gameProcessedEvent )

Fired when a user taps their finger on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device
RBXScriptSignal

TouchTapInWorld ( Vector2 position , bool processedByUI )

Fires when a user taps the game world on a UserInputService/TouchEnabled|TouchEnabled device - such as the screen of a mobile device
RBXScriptSignal

UserCFrameChanged ( UserCFrame type , CFrame value )

Fires when the DataType/CFrame of a specified Virtual Reality device changes
RBXScriptSignal

WindowFocusReleased ( )

Fires when the window of the Roblox client loses focus on the user’s screen
RBXScriptSignal

WindowFocused ( )

Fires when the window of the Roblox client gains focus on the user’s screen

Inherited from Instance: Show Hide

RBXScriptSignal

AncestryChanged ( Instance child , Instance parent )

Fires when the Instance/Parent property of the object or one of its ancestors is changed.
RBXScriptSignal

AttributeChanged ( string attribute )

Fires whenever an attribute is changed on the Instance
RBXScriptSignal

Changed ( string property )

Fired immediately after a property of an object changes.
RBXScriptSignal

ChildAdded ( Instance child )

Fires after an object is parented to this Instance.
RBXScriptSignal

ChildRemoved ( Instance child )

Fires after a child is removed from this Instance.
RBXScriptSignal

DescendantAdded ( Instance descendant )

Fires after a descendant is added to the Instance
RBXScriptSignal

DescendantRemoving ( Instance descendant )

Fires immediately before a descendant of the Instance is removed.
RBXScriptSignal

Destroying ( )

Fires immediately before the instance is destroyed via Instance/Destroy.
RBXScriptSignal

childAdded ( Instance child )

[Deprecated]

Code Samples

UserInputService

The following example demonstrates one of many usage examples of handling a UserInputService event.

Copy Code Light Theme
PlayerMouse VehicleSeat