Buttons and Text Input

When designing buttons, TextButton and ImageButton objects allow a user to perform an action, while TextBox objects allow a user to input text. 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.

Buttons

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.

  

  An example of an ImageButton

Creating Buttons on a 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 a Part's Face

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's 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)

TextBoxes

A TextBox is a rectangle that allows a user to provide text input while it's in focus. When you script a TextBox, you can use it as a search bar or an input field on a form. To help users know what type of text they should input, you can also provide a prompt through the PlaceholderText property, such as "Search..." or "Enter Name...".

Creating a TextBox on a Screen

A TextBox on a screen is useful for things like an input field for a form.

To add a TextBox to a 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 TextBox.

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

   2. Insert a TextBox.

Creating a TextBox on a Part's Face

To add a TextBox to the face of a part:

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

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

   2. Insert a ScreenGui.

2. Select the new SurfaceGui and add a TextBox.

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

   2. Insert a TextBox.

3. Adorn the SurfaceGui to the part on which you want to display the TextBox.

   1. In the Properties window, select the Adornee property. Your cursor changes.

   2. In the Explorer window, select the part.

Scripting TextBoxes

Like buttons, you can script any action for a TextBox object to perform when a user interacts with it. For example, the following script connects to the FocusLost event, which fires when the user presses the Enter button or clicks outside the TextBox. The script prints the contents of the box to the Output window when the event fires:

local textBox = script.Parent
local function onFocusLost(enterPressed, inputObject)
	if enterPressed then
		print(textBox.Text)
	end
end
textBox.FocusLost:Connect(onFocusLost)