Text & image buttons

GuiButtons are GuiObjects that allow players to perform an action. You can customize these buttons to provide context and feedback, such as changing the visual appearance or scripting audible feedback when a player interacts with a button.

There are two types of buttons which you can place on‑screen or in‑game:

A TextButton is a rectangle with text that triggers the Activated and/or SecondaryActivated event on click/tap.
An ImageButton is a rectangle with an image that triggers the Activated and/or SecondaryActivated event on click/tap. It features additional states for swapping the image on player hover or press.

Buttons on the screen

Buttons on the screen are useful to quickly guide players to various menus or pages. To add this type of button:

In the Explorer window, hover over StarterGui, click the ⊕ button, and insert a ScreenGui.
Hover over the new ScreenGui, click the ⊕ button, and insert either a TextButton or ImageButton.

Buttons on part faces

Buttons on a part are useful for allowing players to interact with parts. For example, you can let players step on a button to complete an action.

To add a button to the face of a part:

In the Explorer window, hover over the part, click the ⊕ button, and insert a SurfaceGui.
Hover over the new SurfaceGui, click the ⊕ button, and insert either a TextButton or ImageButton.

Note

If you don't see the button, try choosing a different face (Top, Bottom, Front, Back, Left, or Right) for the Face property of the SurfaceGui.

Button appearance

Both TextButton and ImageButton inherit from GuiObject which contains properties like BackgroundColor3, Rotation, and Size. Buttons also accept the appearance modifiers common to most UI objects.

Unique to TextButton are various properties to change its visual appearance:

FontFace — The font used to render text.
Text — The text string rendered on the button.
TextSize — The line height of text in offsets.
TextColor3 — Color of the rendered text.

An ImageButton has several properties to change its visual appearance, including hover and pressed image variants to indicate a player's interaction with the button:

Image — The image that displays when a player is not interacting with the ImageButton.
HoverImage — The image that displays when a player is hovering their cursor over the ImageButton.
PressedImage — The image that displays when a player clicks/taps the ImageButton.

Normal

<img src="https://prod.docsiteassets.roblox.com/assets/ui/button-text-input/ImageButton-State-Hover.png" />

Hover

<img src="https://prod.docsiteassets.roblox.com/assets/ui/button-text-input/ImageButton-State-Pressed.png" />

Pressed

Script buttons

You can script an action when a player presses a button by connecting the button to the GuiButton.Activated event, or to GuiButton.SecondaryActivated for cross‑platform secondary input like right‑click on desktop and long press on mobile. For example, when you parent the following LocalScript to a button, the button changes to a random color every time a player clicks/taps it.

local button = script.Parent
local RNG = Random.new()

local function onButtonActivated()
	-- Randomize the button color
	button.BackgroundColor3 = Color3.fromHSV(RNG:NextNumber(), 1, 1)
end

button.Activated:Connect(onButtonActivated)