Creating Mobile Buttons

10 min

When designing an optimal cross-platform experience on Roblox, ContextActionService is a convenient service which lets you bind a function to traditional PC input and simultaneously create an on-screen button visible only on mobile devices. It also allows for quick manipulation of what input is tied to which functions, as well as when mobile action buttons are shown or not.

Adding Mobile Buttons

After ContextActionService has been declared in a LocalScript, the ContextActionService/BindAction|BindAction() method can be used to associate specific input with a function. This method takes the following parameters:

Parameter	Type	Description
`actionName`	string	A "key" used by other functions in `ContextActionService` to manipulate the binding.
`functionToBind`	function	The function to call when the specified input is triggered. This function will receive three arguments: A string equal to the action name. A `enum/UserInputState\|UserInputState` which defines the input state when it called the function. The `InputObject` that caused the function call.
`createTouchButton`	boolean	Whether or not you want an on-screen button to be created when the game is running on a mobile device.
`inputTypes`	tuple	The inputs you want to bind to the function, for instance enum values from `enum/KeyCode\|KeyCode`.

			
				Expected Output
			
				Expand
				
			local ContextActionService = game:GetService("ContextActionService")

local function handleAction(actionName, inputState, inputObject)
	if inputState == Enum.UserInputState.Begin then
		print(actionName, inputObject)
	end
end

-- Bind action to function
ContextActionService:BindAction("Interact", handleAction, true, Enum.KeyCode.T, Enum.KeyCode.ButtonR1)
		
				Copy Code
			
				Light Theme

Reserved Keybindings »

When choosing enum/KeyCode values for ContextActionService and UserInputService or detecting Mouse events, note that some bindings are reserved by Roblox and should generally not be assigned to a game’s custom control bindings.

Character / Camera / UI
Key Codes or Events	Action
W / Up	Move forward
S / Down	Move backwards
A / Left	Move left
D / Right	Move right
Space	Jump
`Mouse/Button2Down`	Turn camera
`Mouse/WheelForward` / `Mouse/WheelBackward`	Zoom in/out
I	Zoom in
O	Zoom out
LeftShift/RightShift	Toggle mouselock (player setting if `StarterPlayer/EnableMouseLockOption\|EnableMouseLockOption` is enabled)
Zero / One / Two / Three / Four / Five / Six / Seven / Eight / Nine	Equip or unequip tools
`Mouse/Button1Down`	Use tool
Backspace	Drop tool
Escape	Main menu
Tab	Player list
Slash	Chat
Backquote	Backpack
F11	Fullscreen mode

Miscellaneous
Key Codes	Action
Print (Windows) LeftControl/RightControl + LeftShift/RightShift + 3 (Mac)	Take screenshot
F12	Record video (Windows only)
F10	Increase graphics level
LeftShift/RightShift + F10	Decrease graphics level
F9	Developer Console
LeftControl/RightControl + LeftShift/RightShift + F7 (Windows) LeftControl/RightControl + LeftAlt/RightAlt + F7 (Mac)	Performance Stats
LeftControl/RightControl + F6	Show Microprofiler
LeftControl/RightControl + P	Pause Microprofiler, if showing

Removing Mobile Buttons

If you want to remove a mobile button from the screen, call ContextActionService/UnbindAction|UnbindAction() with the sole argument of the actionName string you passed to ContextActionService/BindAction|BindAction().

			
				Expected Output
			
				Expand
				
			-- Unbind action by name
ContextActionService:UnbindAction("Interact")
		
				Copy Code
			
				Light Theme

Customizing Buttons

ContextActionService provides several functions to customize the buttons that are generated by ContextActionService/BindAction|BindAction().

Button Text

To change the text label for a mobile button, call ContextActionService/SetTitle|SetTitle() with the actionName string and a title:

			
				Expected Output
			
				Expand
				
			-- Set button label to "Talk"
ContextActionService:SetTitle("Interact", "Talk")
		
				Copy Code
			
				Light Theme

Button Image

Mobile buttons can use custom images just like other GUI buttons via the ContextActionService/SetImage|SetImage() method:

			
				Expected Output
			
				Expand
				
			-- Set button image
ContextActionService:SetImage("Interact", "rbxassetid://0123456789")
		
				Copy Code
			
				Light Theme

Button Position

To position a mobile button, use ContextActionService/SetPosition|SetPosition() and specify the desired datatype/UDim2:

			
				Expected Output
			
				Expand
				
			-- Set button position
ContextActionService:SetPosition("Interact", UDim2.new(1, -70, 0, 10))
		
				Copy Code
			
				Light Theme

If you don't set the button's position, it will appear near the mobile jump button in the lower-right section of the screen. Also note that button position is very important on mobile devices because of "thumb zones" as outlined in articles/cross platform development|Cross-Platform Development.

Overriding Inputs

Because screen space on mobile devices is very limited, it’s best practice to use contextual buttons that perform different actions based on what the player can or can’t do. For instance, you may want to display an active “Collect” button when the player is standing near a chest of gold:

			
				Expected Output
			
				Expand
				
			local ContextActionService = game:GetService("ContextActionService")

local function collectTreasure(actionName, inputState, inputObject)
	if inputState == Enum.UserInputState.Begin then
		print("Collect treasure")
	end
end

ContextActionService:BindAction("Interact", collectTreasure, true, Enum.KeyCode.T, Enum.KeyCode.ButtonR1)
ContextActionService:SetPosition("Interact", UDim2.new(1, -70, 0, 10))
-- Set image to blue "Collect" button
ContextActionService:SetImage("Interact", "rbxassetid://0123456789")
		
				Copy Code
			
				Light Theme

At another point in the game, you may wish to change the button to “Talk” when the player is standing near an NPC. Instead of adding a new button in the same place (and removing the old button), you can simply re-bind its action to a new function and change its image:

			
				Expected Output
			
				Expand
				
			ContextActionService:BindAction("Interact", talkToNPC, true, Enum.KeyCode.T, Enum.KeyCode.ButtonR1)
-- Set image to yellow "Talk" button
ContextActionService:SetImage("Interact", "rbxassetid://0011223344")
		
				Copy Code
			
				Light Theme

Tags:

mobile
controls
button

Creating Mobile Buttons

Creating Mobile Buttons

Adding Mobile Buttons

Reserved Keybindings »

Removing Mobile Buttons

Customizing Buttons

Button Text

Button Image

Button Position

Overriding Inputs

Related Articles

Cross-Platform Development

Customizing Game Controls

Intro to Player Input