Buttons

When designing buttons, TextButton and ImageButton objects allow a user to perform an action. You can customize these objects to provide context and prompts for what you want a user to do. For example, you can provide users visual feedback by changing the appearance of an ImageButton when a user clicks it.

Because these objects are GuiObjects, you can customize properties such as BackgroundColor3, BorderMode, Transparency, and Rotation to fit the aesthetics of your experience.

There are two types of buttons you can use on a screen or surface of a part:

• TextButton - A TextButton is a rectangle with text that performs a set action when clicked. This action determines the GuiButton.Activated property with scripting.

• ImageButton - An ImageButton is a rectangle with an image that performs a set action when clicked. This object is useful for a character selection screen or intuitive quick-action buttons, such as a button with a cart icon that opens a marketplace.

  

Creating Buttons on the Screen

Buttons on a screen are useful to quickly guide users to various menus or pages.

To add a button to the screen:

1. In the Explorer window, select StarterGui and add a ScreenGui.

   1. Hover over StarterGui and click the ⊕ button. A contextual menu displays.

   2. Insert a ScreenGui.

2. Select the new ScreenGui and add a button.

   1. Hover over ScreenGui and click the ⊕ button. A contextual menu displays.

   2. Insert either a TextButton or ImageButton.

   

Creating Buttons on Part Faces

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

To add a button to the face of a part:

1. In the Explorer window, select the part and add a SurfaceGui.

   1. Hover over the part and click the ⊕ button. A contextual menu displays.

   2. Insert a SurfaceGui.

2. Select the new SurfaceGui and add any type of button or input.

   1. Hover over SurfaceGui and click the ⊕ button. A contextual menu displays.

   2. Insert either a TextButton or ImageButton.

   

   If you don't see the button, try choosing a different face in the Face property of the SurfaceGui.

Changing the Appearance of an ImageButton

Changing the appearance of an ImageButton when a user is interacting with it provides useful visual feedback. For example, when an ImageButton changes visual appearance when a user hovers over it, it lets the user know that it isn't disabled and that they have the option to click it if they want to perform that ImageButton action.

An ImageButton has three properties to change its visual appearance:

• Image - The image that displays when a user is not interacting with the ImageButton.

• HoverImage - The image that displays when a user is hovering their cursor over the ImageButton.

• PressedImage - The image that displays when a user is clicking the ImageButton.

To change the appearance of an ImageButton with user input:

1. Add an ImageButton to a screen or a surface.

2. In the Explorer window, click the ImageButton object.

3. In the Properties window, assign three different respective asset IDs for the Image, HoverImage, and PressedImage properties.

Scripting Buttons

You can script an action when a user presses a button by connecting the button to a GuiButton.Activated event. For example, when you parent the following LocalScript to a button, the button changes to a random color every time a user clicks 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)