GuiObject

Show Deprecated
Not Creatable
Not Browsable

GuiObject is an abstract class (much like BasePart) for a 2D user interface object. It defines all the properties relating to the display of a graphical user interface (GUI) object such as Size and Position. It also has some useful read‑only properties like AbsolutePosition, AbsoluteSize, and AbsoluteRotation.

To manipulate the layout of GUI objects in special ways, you can use a layout structure such as list/flex or grid, and you can style them beyond their core properties through appearance modifiers.

Although it's possible to detect mouse button events on any GUI object using InputBegan and InputEnded, only ImageButton and TextButton have convenient dedicated events such as Activated to detect click/press.

Summary

Properties

Properties inherited from GuiBase2d

Methods

Events

Events inherited from GuiBase2d

Properties

Active

Read Parallel

This property determines whether this GuiObject will sink input to 3D space, such as underlying models with a ClickDetector class such as DragDetector. In other words, if the player attempts to click the detector with the mouse hovering over an active UI element, the UI will block the input from reaching the detector.

For GuiButton objects (ImageButton and TextButton), this property determines whether Activated fires (AutoButtonColor will still work for those as well). The events InputBegan, InputChanged, and InputEnded work as normal no matter the value of this property.

Code Samples

TextButton Active Debounce

-- Place this LocalScript within a TextButton (or ImageButton)
local textButton = script.Parent
textButton.Text = "Click me"
textButton.Active = true
local function onActivated()
-- This acts like a debounce
textButton.Active = false
-- Count backwards from 5
for i = 5, 1, -1 do
textButton.Text = "Time: " .. i
task.wait(1)
end
textButton.Text = "Click me"
textButton.Active = true
end
textButton.Activated:Connect(onActivated)

AnchorPoint

Read Parallel

This property determines the origin point of a GuiObject, relative to its absolute size. The origin point determines from where the element is positioned (through GuiObject.Position) and from which the rendered GuiObject.Size expands.

See here for illustrated diagrams and details.

Code Samples

AnchorPoint Demo

local guiObject = script.Parent
while true do
-- Top-left
guiObject.AnchorPoint = Vector2.new(0, 0)
guiObject.Position = UDim2.new(0, 0, 0, 0)
task.wait(1)
-- Top
guiObject.AnchorPoint = Vector2.new(0.5, 0)
guiObject.Position = UDim2.new(0.5, 0, 0, 0)
task.wait(1)
-- Top-right
guiObject.AnchorPoint = Vector2.new(1, 0)
guiObject.Position = UDim2.new(1, 0, 0, 0)
task.wait(1)
-- Left
guiObject.AnchorPoint = Vector2.new(0, 0.5)
guiObject.Position = UDim2.new(0, 0, 0.5, 0)
task.wait(1)
-- Dead center
guiObject.AnchorPoint = Vector2.new(0.5, 0.5)
guiObject.Position = UDim2.new(0.5, 0, 0.5, 0)
task.wait(1)
-- Right
guiObject.AnchorPoint = Vector2.new(1, 0.5)
guiObject.Position = UDim2.new(1, 0, 0.5, 0)
task.wait(1)
-- Bottom-left
guiObject.AnchorPoint = Vector2.new(0, 1)
guiObject.Position = UDim2.new(0, 0, 1, 0)
task.wait(1)
-- Bottom
guiObject.AnchorPoint = Vector2.new(0.5, 1)
guiObject.Position = UDim2.new(0.5, 0, 1, 0)
task.wait(1)
-- Bottom-right
guiObject.AnchorPoint = Vector2.new(1, 1)
guiObject.Position = UDim2.new(1, 0, 1, 0)
task.wait(1)
end

AutomaticSize

Read Parallel

This property is used to automatically size parent UI objects based on the size of its descendants. You can use this property to dynamically add text and other content to a UI object at edit or run time, and the size will adjust to fit that content.

When AutomaticSize is set to an Enum.AutomaticSize value to anything other than None, this UI object may resize depending on its child content.

For more information on how to use this property and how it works, please see here.

Code Samples

LocalScript in a ScreenGui

-- Array of text labels/fonts/sizes to output
local labelArray = {
{ text = "Lorem", font = Enum.Font.Creepster, size = 50 },
{ text = "ipsum", font = Enum.Font.IndieFlower, size = 35 },
{ text = "dolor", font = Enum.Font.Antique, size = 55 },
{ text = "sit", font = Enum.Font.SpecialElite, size = 65 },
{ text = "amet", font = Enum.Font.FredokaOne, size = 40 },
}
-- Create an automatically-sized parent frame
local parentFrame = Instance.new("Frame")
parentFrame.AutomaticSize = Enum.AutomaticSize.XY
parentFrame.BackgroundColor3 = Color3.fromRGB(90, 90, 90)
parentFrame.Size = UDim2.fromOffset(25, 100)
parentFrame.Position = UDim2.fromScale(0.1, 0.1)
parentFrame.Parent = script.Parent
-- Add a list layout
local listLayout = Instance.new("UIListLayout")
listLayout.Padding = UDim.new(0, 5)
listLayout.Parent = parentFrame
-- Set rounded corners and padding for visual aesthetics
local roundedCornerParent = Instance.new("UICorner")
roundedCornerParent.Parent = parentFrame
local uiPaddingParent = Instance.new("UIPadding")
uiPaddingParent.PaddingTop = UDim.new(0, 5)
uiPaddingParent.PaddingLeft = UDim.new(0, 5)
uiPaddingParent.PaddingRight = UDim.new(0, 5)
uiPaddingParent.PaddingBottom = UDim.new(0, 5)
uiPaddingParent.Parent = parentFrame
for i = 1, #labelArray do
-- Create an automatically-sized text label from array
local childLabel = Instance.new("TextLabel")
childLabel.AutomaticSize = Enum.AutomaticSize.XY
childLabel.Size = UDim2.fromOffset(75, 15)
childLabel.Text = labelArray[i]["text"]
childLabel.Font = labelArray[i]["font"]
childLabel.TextSize = labelArray[i]["size"]
childLabel.TextColor3 = Color3.new(1, 1, 1)
childLabel.Parent = parentFrame
-- Visual aesthetics
local roundedCorner = Instance.new("UICorner")
roundedCorner.Parent = childLabel
local uiPadding = Instance.new("UIPadding")
uiPadding.PaddingTop = UDim.new(0, 5)
uiPadding.PaddingLeft = UDim.new(0, 5)
uiPadding.PaddingRight = UDim.new(0, 5)
uiPadding.PaddingBottom = UDim.new(0, 5)
uiPadding.Parent = childLabel
task.wait(2)
end

BackgroundColor3

Read Parallel

This property determines the color of a GuiObject background (the fill color). If your element contains text, such as a TextBox, TextButton, or TextLabel, make sure the color of your background contrasts the text's color.

Another property that determines the visual properties of the background is GuiObject.BackgroundTransparency; if this is set to 1, neither the background nor the border will render.

See also BorderColor3.

Code Samples

Rainbow Frame

-- Put this code in a LocalScript in a Frame
local frame = script.Parent
while true do
for hue = 0, 255, 4 do
-- HSV = hue, saturation, value
-- If we loop from 0 to 1 repeatedly, we get a rainbow!
frame.BorderColor3 = Color3.fromHSV(hue / 256, 1, 1)
frame.BackgroundColor3 = Color3.fromHSV(hue / 256, 0.5, 0.8)
task.wait()
end
end

BackgroundTransparency

Read Parallel

This property determines the transparency of the GuiObject background and border. It does not, however, determine the transparency of text if the GUI is a TextBox, TextButton, or TextLabel; text transparency is determined TextBox.TextTransparency, TextButton.TextTransparency, and TextLabel.TextTransparency respectively.

If this property is set to 1, neither the background nor the border will render and the GUI background will be completely transparent.

BorderColor3

Read Parallel

Determines the color of the GuiObject rectangular border (also known as the stroke color). This is separate from the object's GuiObject.BackgroundColor3. You will not be able to see the object's border if its GuiObject.BorderSizePixel property is set to 0.

Note that the UIStroke component allows for more advanced border effects.

Code Samples

Button Highlight

-- Put me inside some GuiObject, preferrably an ImageButton/TextButton
local button = script.Parent
local function onEnter()
button.BorderSizePixel = 2
button.BorderColor3 = Color3.new(1, 1, 0) -- Yellow
end
local function onLeave()
button.BorderSizePixel = 1
button.BorderColor3 = Color3.new(0, 0, 0) -- Black
end
-- Connect events
button.MouseEnter:Connect(onEnter)
button.MouseLeave:Connect(onLeave)
-- Our default state is "not hovered"
onLeave()

BorderMode

Read Parallel

This property determines in what manner the GuiObject border is laid out relative to its dimensions using the enum of the same name, Enum.BorderMode.

Note that UIStroke can override this property and allow for more advanced border effects.

BorderSizePixel

Read Parallel

This property determines how wide the GuiObject border renders, in pixels. Setting this to 0 disables the border altogether.

Note that UIStroke can override this property and allow for more advanced border effects.

Code Samples

Button Highlight

-- Put me inside some GuiObject, preferrably an ImageButton/TextButton
local button = script.Parent
local function onEnter()
button.BorderSizePixel = 2
button.BorderColor3 = Color3.new(1, 1, 0) -- Yellow
end
local function onLeave()
button.BorderSizePixel = 1
button.BorderColor3 = Color3.new(0, 0, 0) -- Black
end
-- Connect events
button.MouseEnter:Connect(onEnter)
button.MouseLeave:Connect(onLeave)
-- Our default state is "not hovered"
onLeave()

ClipsDescendants

Read Parallel

This property determines if the GuiObject will clip (make invisible) any portion of descendant GUI elements that would otherwise render outside the bounds of the rectangle.

Note that Rotation isn't supported by this property. If this or any ancestor GUI has a non‑zero Rotation, this property is ignored and descendant GUI elements will be rendered regardless of this property's value.

Read Only
Not Replicated
Read Parallel

When the player's finger is being tapped and held on the GuiObject, the GuiState of the GuiObject will be set to Press. Similarly, When the player's finger is being released from the GuiObject, the GuiState of the GuiObject will be set to Idle, and when Interactable is turned off on the GuiObject, the Class.GuiState of the GuiObject will be set to NonInteractable.

Interactable

Read Parallel

Determines whether the GuiButton can be interacted with or not, or if the GuiState of the GuiObject is changing or not.

On a GuiButton:

On a GuiObject:

LayoutOrder

Read Parallel

This property controls the sorting order of the GuiObject when using a UIGridStyleLayout (such as UIListLayout or UIPageLayout) with SortOrder set to Enum.SortOrder.LayoutOrder. It has no functionality if the object does not have a sibling UI layout structure.

GuiObjects are sorted in ascending order where lower values take priority over higher values. Objects with equal values fall back to the order they were added in.

If you are unsure if you'll need to add an element between two existing elements in the future, it's a good practice to use multiples of 100 (0, 100, 200, etc.). This ensures a large gap of layout order values which you can use for elements ordered in-between other elements.

See also ZIndex which determines the object's rendering order instead of sorting order.

NextSelectionDown

Read Parallel

This property sets the GuiObject selected when the user moves the gamepad selector downward. If this property is empty, moving the gamepad downward will not change the selected GUI.

Moving the gamepad selector downward sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.

See also NextSelectionUp, NextSelectionLeft, and NextSelectionRight.

Code Samples

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

NextSelectionLeft

Read Parallel

This property sets the GuiObject selected when the user moves the gamepad selector to the left. If this property is empty, moving the gamepad to the left will not change the selected GUI.

Moving the gamepad selector to the left sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.

See also NextSelectionUp, NextSelectionDown, and NextSelectionRight.

Code Samples

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

NextSelectionRight

Read Parallel

This property sets the GuiObject selected when the user moves the gamepad selector to the right. If this property is empty, moving the gamepad to the right will not change the selected GUI.

Moving the gamepad selector to the right sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.

See also NextSelectionUp, NextSelectionDown, and NextSelectionLeft.

Code Samples

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

NextSelectionUp

Read Parallel

This property sets the GuiObject selected when the user moves the gamepad selector upward. If this property is empty, moving the gamepad upward will not change the selected GUI.

Moving the gamepad selector upward sets the GuiService.SelectedObject to this object unless the GUI is not Selectable. Note that this property can be set to a GUI element even if it is not Selectable, so you should ensure that the value of a GUI's selectable property matches your expected behavior.

See also NextSelectionDown, NextSelectionLeft, NextSelectionRight.

Code Samples

Creating a Gamepad Selection Grid

-- Setup the Gamepad selection grid using the code below
local container = script.Parent:FindFirstChild("Container")
local grid = container:GetChildren()
local rowSize = container:FindFirstChild("UIGridLayout").FillDirectionMaxCells
for _, gui in pairs(grid) do
if gui:IsA("GuiObject") then
local pos = gui.Name
-- Left edge
gui.NextSelectionLeft = container:FindFirstChild(pos - 1)
-- Right edge
gui.NextSelectionRight = container:FindFirstChild(pos + 1)
-- Above
gui.NextSelectionUp = container:FindFirstChild(pos - rowSize)
-- Below
gui.NextSelectionDown = container:FindFirstChild(pos + rowSize)
end
end
-- Test the Gamepad selection grid using the code below
local GuiService = game:GetService("GuiService")
local UserInputService = game:GetService("UserInputService")
GuiService.SelectedObject = container:FindFirstChild("1")
function updateSelection(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
local key = input.KeyCode
local selectedObject = GuiService.SelectedObject
if not selectedObject then
return
end
if key == Enum.KeyCode.Up then
if not selectedObject.NextSelectionUp then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Down then
if not selectedObject.NextSelectionDown then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Left then
if not selectedObject.NextSelectionLeft then
GuiService.SelectedObject = selectedObject
end
elseif key == Enum.KeyCode.Right then
if not selectedObject.NextSelectionRight then
GuiService.SelectedObject = selectedObject
end
end
end
end
UserInputService.InputBegan:Connect(updateSelection)

Position

Read Parallel

This property determines the GuiObject pixel and scalar position using a UDim2. Position is centered around the object's GuiObject.AnchorPoint.

The scalar position is relative to the size of the parent GUI element, if any.

The pixel portions of the UDim2 value are the same regardless of the parent GUI's size. The values represent the position of the object in pixels. An object's actual pixel position can be read from the GuiBase2d.AbsolutePosition property.

Rotation

Read Parallel

This property determines the number of degrees by which the GuiObject is rotated. Rotation is relative to the center of the object, not the AnchorPoint, meaning you cannot change the point of rotation. Additionally, this property is not compatible with ClipsDescendants.

Selectable

Read Parallel

This property determines whether the GuiObject can be selected when navigating GUIs using a gamepad.

If this property is true, a GUI can be selected. Selecting a GUI also sets the GuiService.SelectedObject property to that object.

When this is false, the GUI cannot be selected. However, setting this to false when a GUI is selected will not deselect it nor change the value of the GuiService.SelectedObject property.

Add GuiObject.SelectionGained and GuiObject.SelectionLost will not fire for the element. To deselect a GuiObject, you must change the GuiService.SelectedObject property.

This property is useful if a GUI is connected to several GUIs via properties such as this GuiObject.NextSelectionUp, GuiObject.NextSelectionDown, NextSelectionRight, or NextSelectionLeft. Rather than change all of the properties so that the Gamepad cannot select the GUI, you can disable its Selectable property to temporarily prevent it from being selected. Then, when you want the gamepad selector to be able to select the GUI, simply re-enable its selectable property.

Code Samples

Limiting TextBox Selection

local GuiService = game:GetService("GuiService")
local textBox = script.Parent
local function gainFocus()
textBox.Selectable = true
GuiService.SelectedObject = textBox
end
local function loseFocus(_enterPressed, _inputObject)
GuiService.SelectedObject = nil
textBox.Selectable = false
end
-- The FocusLost and FocusGained event will fire because the textBox
-- is of type TextBox
textBox.Focused:Connect(gainFocus)
textBox.FocusLost:Connect(loseFocus)

SelectionImageObject

Read Parallel

This property overrides the default selection adornment used for gamepads.

Note that the chosen SelectionImageObject overlays the selected GuiObject with the Size of the image. For best results, you should size the custom SelectionImageObject via the scale UDim2 values to help ensure that the object scales properly over the selected element.

Changing the SelectionImageObject for a GuiObject element only affects that element. To affect all of a user's GUI elements, set the PlayerGui.SelectionImageObject property.

To determine or set which GUI element is selected by the user, you can use the GuiService.SelectedObject property. The player uses the gamepad to select different GUI elements, invoking the NextSelectionUp, NextSelectionDown, NextSelectionLeft, and NextSelectionRight events.

SelectionOrder

Read Parallel

GuiObjects with a lower SelectionOrder are selected earlier than GuiObjects with a higher SelectionOrder when starting the gamepad selection or calling GuiService:Select() on an ancestor. This property does not affect directional navigation. Default value is 0.

Size

Read Parallel

This property determines the GuiObject scalar and pixel size using a UDim2.

The scalar size is relative to the size of the parent GUI element, if any.

The pixel portions of the UDim2 value are the same regardless of the parent GUI's size. The values represent the size of the object in pixels. An object's actual pixel size can be read from the GuiBase2d.AbsoluteSize property.

If the GuiObject has a parent, its size along each axis is also influenced by the parent's SizeConstraint.

Code Samples

Health Bar

local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Paste script into a LocalScript that is
-- parented to a Frame within a Frame
local frame = script.Parent
local container = frame.Parent
container.BackgroundColor3 = Color3.new(0, 0, 0) -- black
-- This function is called when the humanoid's health changes
local function onHealthChanged()
local human = player.Character.Humanoid
local percent = human.Health / human.MaxHealth
-- Change the size of the inner bar
frame.Size = UDim2.new(percent, 0, 1, 0)
-- Change the color of the health bar
if percent < 0.1 then
frame.BackgroundColor3 = Color3.new(1, 0, 0) -- black
elseif percent < 0.4 then
frame.BackgroundColor3 = Color3.new(1, 1, 0) -- yellow
else
frame.BackgroundColor3 = Color3.new(0, 1, 0) -- green
end
end
-- This function runs is called the player spawns in
local function onCharacterAdded(character)
local human = character:WaitForChild("Humanoid")
-- Pattern: update once now, then any time the health changes
human.HealthChanged:Connect(onHealthChanged)
onHealthChanged()
end
-- Connect our spawn listener; call it if already spawned
player.CharacterAdded:Connect(onCharacterAdded)
if player.Character then
onCharacterAdded(player.Character)
end

SizeConstraint

Read Parallel

This property sets the Size axes that the GuiObject will be based on, relative to the size of its parent.

This property is useful for creating GUI objects that are meant to scale with either the width or height of a parent object, but not both, effectively preserving the aspect ratio of the object.

Transparency

Hidden
Not Replicated
Read Parallel

A mixed property of BackgroundTransparency and TextTransparency.

Visible

Read Parallel

This property whether the GuiObject and its descendants will be rendered.

The rendering of individual components of a GuiObject can be controlled individually through transparency properties such as GuiObject.BackgroundTransparency, TextLabel.TextTransparency and ImageLabel.ImageTransparency.

When this property is false, the GuiObject will be ignored by layout structures such as UIListLayout, UIGridLayout, and UITableLayout. In other words, the space that the element would otherwise occupy in the layout is used by other elements instead.

Code Samples

UI Window

local gui = script.Parent
local window = gui:WaitForChild("Window")
local toggleButton = gui:WaitForChild("ToggleWindow")
local closeButton = window:WaitForChild("Close")
local function toggleWindowVisbility()
-- Flip a boolean using the `not` keyword
window.Visible = not window.Visible
end
toggleButton.Activated:Connect(toggleWindowVisbility)
closeButton.Activated:Connect(toggleWindowVisbility)

ZIndex

Read Parallel

This property determines the order in which a GuiObject renders relative to others.

By default, GuiObjects render in ascending priority order where those with lower ZIndex values are rendered under those with higher values. You can change the render order within a ScreenGui, SurfaceGui, or BillboardGui by changing the value of its ZIndexBehavior.

If you are unsure if you'll need to add an element between two existing elements in the future, it's a good practice to use multiples of 100 (0, 100, 200, etc.). This ensures a large gap of render order values which you can use for elements layered in-between other elements.

See also LayoutOrder which controls the sorting order of a GuiObject when used with a layout structure such as UIListLayout or UIGridLayout.

Methods

TweenPosition

Smoothly moves a GUI to a new UDim2 position in the specified time using the specified Enum.EasingDirection and Enum.EasingStyle.

This function will return whether the tween will play. It will not play if another tween is acting on the GuiObject and the override parameter is false.

See also GuiObject:TweenSize() and GuiObject:TweenSizeAndPosition().

Parameters

endPosition: UDim2

Where the GUI should move to.

easingDirection: Enum.EasingDirection

The direction in which to ease the GUI to the endPosition.

Default Value: "Out"
easingStyle: Enum.EasingStyle

The style in which to ease the GUI to the endPosition.

Default Value: "Quad"
time: number

How long, in seconds, the tween should take to complete.

Default Value: 1
override: bool

Whether the tween will override an in-progress tween.

Default Value: false
callback: function

A callback function to execute when the tween completes.

Default Value: "nil"

Returns

Whether the tween will play.

Code Samples

Tween a GUI's Position

local START_POSITION = UDim2.new(0, 0, 0, 0)
local GOAL_POSITION = UDim2.new(1, 0, 1, 0)
local guiObject = script.Parent
local function callback(state)
if state == Enum.TweenStatus.Completed then
print("The tween completed uninterrupted")
elseif state == Enum.TweenStatus.Canceled then
print("Another tween cancelled this one")
end
end
-- Initialize the GuiObject position, then start the tween:
guiObject.Position = START_POSITION
local willPlay = guiObject:TweenPosition(
GOAL_POSITION, -- Final position the tween should reach
Enum.EasingDirection.In, -- Direction of the easing
Enum.EasingStyle.Sine, -- Kind of easing to apply
2, -- Duration of the tween in seconds
true, -- Whether in-progress tweens are interrupted
callback -- Function to be callled when on completion/cancelation
)
if willPlay then
print("The tween will play")
else
print("The tween will not play")
end

TweenSize

Smoothly resizes a GuiObject to a new UDim2 in the specified time using the specified Enum.EasingDirection and Enum.EasingStyle.

This function will return whether the tween will play. Normally this will always return true, but it will return false if another tween is active and override is set to false.

See also GuiObject:TweenSize() and GuiObject:TweenSizeAndPosition().

Parameters

endSize: UDim2

The size that the GUI should resize.

easingDirection: Enum.EasingDirection

The direction in which to ease the GUI to the endSize.

Default Value: "Out"
easingStyle: Enum.EasingStyle

The style in which to ease the GUI to the endSize.

Default Value: "Quad"
time: number

How long, in seconds, the tween should take to complete.

Default Value: 1
override: bool

Whether the tween will override an in-progress tween.

Default Value: false
callback: function

A callback function to execute when the tween completes.

Default Value: "nil"

Returns

Whether the tween will play.

Code Samples

Tween a GuiObject's Size

local guiObject = script.Parent
local function callback(didComplete)
if didComplete then
print("The tween completed successfully")
else
print("The tween was cancelled")
end
end
local willTween = guiObject:TweenSize(
UDim2.new(0.5, 0, 0.5, 0), -- endSize (required)
Enum.EasingDirection.In, -- easingDirection (default Out)
Enum.EasingStyle.Sine, -- easingStyle (default Quad)
2, -- time (default: 1)
true, -- should this tween override ones in-progress? (default: false)
callback -- a function to call when the tween completes (default: nil)
)
if willTween then
print("The GuiObject will tween")
else
print("The GuiObject will not tween")
end

TweenSizeAndPosition

Smoothly resizes and moves a GUI to a new UDim2 size and position in the specified time using the specified Enum.EasingDirection and Enum.EasingStyle.

This function will return whether the tween will play. Normally this will always return true, but it will return false if another tween is active and override is set to false.

See also GuiObject:TweenSize() and GuiObject:TweenSizeAndPosition().

Parameters

endSize: UDim2

The size that the GUI should resize.

endPosition: UDim2

Where the GUI should move to.

easingDirection: Enum.EasingDirection

The direction in which to ease the GUI to the endSize and endPosition.

Default Value: "Out"
easingStyle: Enum.EasingStyle

The style in which to ease the GUI to the endSize and endPosition.

Default Value: "Quad"
time: number

How long, in seconds, the tween should take to complete.

Default Value: 1
override: bool

Whether the tween will override an in-progress tween.

Default Value: false
callback: function

A callback function to execute when the tween completes.

Default Value: "nil"

Returns

Whether the tween will play.

Code Samples

Tween a GUI's Size and Position

local frame = script.Parent.Frame
frame:TweenSizeAndPosition(UDim2.new(0, 0, 0, 0), UDim2.new(0, 0, 0, 0))

Events

InputBegan

This event fires when a user begins interacting with the GuiObject via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).

The UserInputService has a similarly named event that is not restricted to a specific UI element: UserInputService.InputBegan.

This event will always fire regardless of game state.

See also GuiObject.InputEnded and GuiObject.InputChanged.

Parameters

An InputObject, which contains useful data for querying user input such as thetype of input, state of input, and screen coordinates of the input.


Code Samples

Tracking the Beginning of Input on a GuiObject

-- In order to use the InputBegan event, you must specify the GuiObject
local gui = script.Parent
-- A sample function providing multiple usage cases for various types of user input
local function inputBegan(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
print("A key is being pushed down! Key:", input.KeyCode)
elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
print("The left mouse button has been pressed down at", input.Position)
elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
print("The right mouse button has been pressed down at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Touch then
print("A touchscreen input has started at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
print("A button is being pressed on a gamepad! Button:", input.KeyCode)
end
end
gui.InputBegan:Connect(inputBegan)

InputChanged

This event fires when a user changes how they're interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).

The UserInputService has a similarly named event that is not restricted to a specific UI element: UserInputService.InputChanged.

This event will always fire regardless of game state.

See also GuiObject.InputBegan and GuiObject.InputEnded.

Parameters

An InputObject, which contains useful data for querying user input such as thetype of input, state of input, and screen coordinates of the input.


Code Samples

GuiObject InputChanged Demo

local UserInputService = game:GetService("UserInputService")
local gui = script.Parent
local function printMovement(input)
print("Position:", input.Position)
print("Movement Delta:", input.Delta)
end
local function inputChanged(input)
if input.UserInputType == Enum.UserInputType.MouseMovement then
print("The mouse has been moved!")
printMovement(input)
elseif input.UserInputType == Enum.UserInputType.MouseWheel then
print("The mouse wheel has been scrolled!")
print("Wheel Movement:", input.Position.Z)
elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
if input.KeyCode == Enum.KeyCode.Thumbstick1 then
print("The left thumbstick has been moved!")
printMovement(input)
elseif input.KeyCode == Enum.KeyCode.Thumbstick2 then
print("The right thumbstick has been moved!")
printMovement(input)
elseif input.KeyCode == Enum.KeyCode.ButtonL2 then
print("The pressure being applied to the left trigger has changed!")
print("Pressure:", input.Position.Z)
elseif input.KeyCode == Enum.KeyCode.ButtonR2 then
print("The pressure being applied to the right trigger has changed!")
print("Pressure:", input.Position.Z)
end
elseif input.UserInputType == Enum.UserInputType.Touch then
print("The user's finger is moving on the screen!")
printMovement(input)
elseif input.UserInputType == Enum.UserInputType.Gyro then
local _rotInput, rotCFrame = UserInputService:GetDeviceRotation()
local rotX, rotY, rotZ = rotCFrame:toEulerAnglesXYZ()
local rot = Vector3.new(math.deg(rotX), math.deg(rotY), math.deg(rotZ))
print("The rotation of the user's mobile device has been changed!")
print("Position", rotCFrame.p)
print("Rotation:", rot)
elseif input.UserInputType == Enum.UserInputType.Accelerometer then
print("The acceleration of the user's mobile device has been changed!")
printMovement(input)
end
end
gui.InputChanged:Connect(inputChanged)

InputEnded

The InputEnded event fires when a user stops interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).

The UserInputService has a similarly named event that is not restricted to a specific UI element: UserInputService.InputEnded.

This event will always fire regardless of game state.

See also GuiObject.InputBegan and GuiObject.InputChanged.

Parameters

An InputObject, which contains useful data for querying user input such as theEnum.UserInputType, Enum.UserInputState, and InputObject.Position.


Code Samples

Tracking the End of Input on a GuiObject

-- In order to use the InputChanged event, you must specify a GuiObject
local gui = script.Parent
-- A sample function providing multiple usage cases for various types of user input
local function inputEnded(input)
if input.UserInputType == Enum.UserInputType.Keyboard then
print("A key has been released! Key:", input.KeyCode)
elseif input.UserInputType == Enum.UserInputType.MouseButton1 then
print("The left mouse button has been released at", input.Position)
elseif input.UserInputType == Enum.UserInputType.MouseButton2 then
print("The right mouse button has been released at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Touch then
print("A touchscreen input has been released at", input.Position)
elseif input.UserInputType == Enum.UserInputType.Gamepad1 then
print("A button has been released on a gamepad! Button:", input.KeyCode)
end
end
gui.InputEnded:Connect(inputEnded)

MouseEnter

The MouseEnter event fires when a user moves their mouse into a GuiObject element.

Please do not rely on the x and y arguments passed by this event as a fool-proof way to determine where the user's mouse is when it enters a GUI. These coordinates may vary even when the mouse enters the GUI via the same edge - particularly when the mouse enters the element quickly. This is due to the fact the coordinates indicate the position of the mouse when the event fires rather than the exact moment the mouse enters the GUI.

This event fires even when the GUI element renders beneath another element.

If you would like to track when a user's mouse leaves a GUI element, you can use the GuiObject.MouseLeave event.

See Also

Parameters

The mouse's X screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's Y screen coordinate in pixels, relative to the top left corner of the screen.


Code Samples

Printing where a Mouse Enters a GuiObject

local guiObject = script.Parent
guiObject.MouseEnter:Connect(function(x, y)
print("The user's mouse cursor has entered the GuiObject at position", x, ",", y)
end)

MouseLeave

The MouseLeave event fires when a user moves their mouse out of a GuiObject element.

Please do not rely on the x and y arguments passed by this event as a fool-proof way to determine where the user's mouse is when it leaves a GUI. These coordinates may vary even when the mouse leaves the GUI via the same edge - particularly when the mouse leaves the element quickly. This is due to the fact the coordinates indicate the position of the mouse when the event fires rather than the exact moment the mouse leaves the GUI.

This event fires even when the GUI element renders beneath another element.

See Also

Parameters

The mouse's X screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's Y screen coordinate in pixels, relative to the top left corner of the screen.


MouseMoved

Fires whenever a user moves their mouse while it is inside a GuiObject element. It is similar to Mouse.Move, which fires regardless whether the user's mouse is over a GUI element.

Note, this event fires when the mouse's position is updated, therefore it will fire repeatedly while being moved.

The x and y arguments indicate the updated screen coordinates of the user's mouse in pixels. These can be useful to determine the mouse's location on the GUI, screen, and delta since the mouse's previous position if it is being tracked in a global variable.

The code below demonstrates how to determine the Vector2 offset of the user's mouse relative to a GUI element:


local CustomScrollingFrame = script.Parent
local SubFrame = CustomScrollingFrame:FindFirstChild("SubFrame")
local mouse = game.Players.LocalPlayer:GetMouse()
function getPosition(X, Y)
local gui_X = CustomScrollingFrame.AbsolutePosition.X
local gui_Y = CustomScrollingFrame.AbsolutePosition.Y
local pos = Vector2.new(math.abs(X - gui_X), math.abs(Y - gui_Y - 36))
print(pos)
end
CustomScrollingFrame.MouseMoved:Connect(getPosition)

Note that this event may not fire exactly when the user's mouse enters or exits a GUI element. Therefore, the x and y arguments may not match up perfectly to the coordinates of the GUI's edges.

See Also

Parameters

The mouse's X screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's Y screen coordinate in pixels, relative to the top left corner of the screen.


MouseWheelBackward

The WheelBackward event fires when a user scrolls their mouse wheel back when the mouse is over a GuiObject element. It is similar to Mouse.WheelBackward, which fires regardless whether the user's mouse is over a GUI element.

This event fires merely as an indicator of the wheel's backward movement. This means that the x and y mouse coordinate arguments don't change as a result of this event. These coordinates only change when the mouse moves, which can be tracked by the GuiObject.MouseMoved event.

See Also

Parameters

The mouse's X screen coordinate in pixels, relative to the top left corner of the screen.

The mouse's Y screen coordinate in pixels, relative to the top left corner of the screen.


MouseWheelForward

The WheelForward event fires when a user scrolls their mouse wheel forward when the mouse is over a GuiObject element. It is similar to Mouse.WheelForward, which fires regardless whether the user's mouse is over a GUI element.

This event fires merely as an indicator of the wheel's forward movement. This means that the X and Y mouse coordinate arguments do not change as a result of this event. These coordinates only change when the mouse moves, which can be tracked by the GuiObject.MouseMoved event.

See Also

Parameters

The mouse's X screen coordinate in pixels, relative to the top left corner of the screen.

The Y coordinate of the user's mouse.


SelectionGained

This event fires when the Gamepad selector starts focusing on the GuiObject.

If you want to check from the Gamepad select stops focusing on the GUI element, you can use the GuiObject.SelectionLost event.

When a GUI gains selection focus, the value of the SelectedObject property also changes to the that gains selection. To determine which GUI gained selection, check the value of this property.


Code Samples

Handling GUI Selection Gained

local guiObject = script.Parent
local function selectionGained()
print("The user has selected this button with a gamepad.")
end
guiObject.SelectionGained:Connect(selectionGained)

SelectionLost

This event fires when the Gamepad selector stops focusing on the GuiObject.

If you want to check from the Gamepad select starts focusing on the GUI element, you can use the GuiObject.SelectionGained event.

When a GUI loses selection focus, the value of the SelectionObject property changes either to nil or to the GUI element that gains selection focus. To determine which GUI gained selection, or if no GUI is selected, check the value of this property.


Code Samples

Handling GUI Selection Lost

local guiObject = script.Parent
local function selectionLost()
print("The user no longer has this selected with their gamepad.")
end
guiObject.SelectionLost:Connect(selectionLost)

TouchLongPress

This event fires after a brief moment when the player holds their finger on the UI element using a touch-enabled device. It fires with a table of Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires multiple times: Enum.UserInputState.Begin after a brief delay, Enum.UserInputState.Change if the player moves their finger during the gesture, and finally Enum.UserInputState.End. The delay is platform dependent; in Studio it is a little longer than one second.

Since this event only requires one finger, this event can be simulated in Studio using the emulator and a mouse.

Parameters

touchPositions: Array

An array of Vector2 that describe the relative positions of the fingers involved in the gesture.

A Enum.UserInputState that describes the state of the gesture:

  • Begin fires once at the beginning of the gesture (after the brief delay)
  • Change fires if the player moves their finger while pressing down
  • End fires once at the end of the gesture when they release their finger.

Code Samples

Move UI Element with TouchLongPress

local frame = script.Parent
frame.Active = true
local dragging = false
local basePosition
local startTouchPosition
local borderColor3
local backgroundColor3
local function onTouchLongPress(touchPositions, state)
if state == Enum.UserInputState.Begin and not dragging then
-- Start a drag
dragging = true
basePosition = frame.Position
startTouchPosition = touchPositions[1]
-- Color the frame to indicate the drag is happening
borderColor3 = frame.BorderColor3
backgroundColor3 = frame.BackgroundColor3
frame.BorderColor3 = Color3.new(1, 1, 1) -- White
frame.BackgroundColor3 = Color3.new(0, 0, 1) -- Blue
elseif state == Enum.UserInputState.Change then
local touchPosition = touchPositions[1]
local deltaPosition = UDim2.new(
0,
touchPosition.X - startTouchPosition.X,
0,
touchPosition.Y - startTouchPosition.Y
)
frame.Position = basePosition + deltaPosition
elseif state == Enum.UserInputState.End and dragging then
-- Stop the drag
dragging = false
frame.BorderColor3 = borderColor3
frame.BackgroundColor3 = backgroundColor3
end
end
frame.TouchLongPress:Connect(onTouchLongPress)

TouchPan

This event fires when the player moves their finger on the UI element using a touch-enabled device. It fires shortly before GuiObject.TouchSwipe would, and does not fire with GuiObject.TouchTap. This event is useful for allowing the player to manipulate the position of UI elements on the screen.

This event fires with a table of Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires multiple times: Enum.UserInputState.Begin after a brief delay, Enum.UserInputState.Change when the player moves their finger during the gesture, and finally with Enum.UserInputState.End.

This event cannot be simulated in Studio using the emulator and a mouse; you must have a real touch-enabled device to fire it.

Parameters

touchPositions: Array

A Lua array of Vector2 objects, each indicating the position of all the fingers involved in the gesture.

totalTranslation: Vector2

Indicates how far the pan gesture has gone from its starting point.

velocity: Vector2

Indicates how quickly the gesture is being performed in each dimension.

Indicates the Enum.UserInputState of the gesture.


Code Samples

Panning UI Element

local innerFrame = script.Parent
local outerFrame = innerFrame.Parent
outerFrame.BackgroundTransparency = 0.75
outerFrame.Active = true
outerFrame.Size = UDim2.new(1, 0, 1, 0)
outerFrame.Position = UDim2.new(0, 0, 0, 0)
outerFrame.AnchorPoint = Vector2.new(0, 0)
outerFrame.ClipsDescendants = true
local dragging = false
local basePosition
local function onTouchPan(_touchPositions, totalTranslation, _velocity, state)
if state == Enum.UserInputState.Begin and not dragging then
dragging = true
basePosition = innerFrame.Position
outerFrame.BackgroundTransparency = 0.25
elseif state == Enum.UserInputState.Change then
innerFrame.Position = basePosition + UDim2.new(0, totalTranslation.X, 0, totalTranslation.Y)
elseif state == Enum.UserInputState.End and dragging then
dragging = false
outerFrame.BackgroundTransparency = 0.75
end
end
outerFrame.TouchPan:Connect(onTouchPan)

TouchPinch

This event fires when the player uses two fingers to make a pinch or pull gesture on the UI element using a touch-enabled device. A pinch happens when two or more fingers move closer together, and a pull happens when they move apart. This event fires in conjunction with GuiObject.TouchPan. This event is useful for allowing the player to manipulate the scale (size) of UI elements on the screen, and is most often used for zooming features.

This event fires with a table of Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires multiple times: Enum.UserInputState.Begin after a brief delay, Enum.UserInputState.Change when the player moves a finger during the gesture, and finally with Enum.UserInputState.End. It should be noted that the scale should be used multiplicatively.

Since this event requires at least two fingers, it is not possible to simulate it in Studio using the emulator and a mouse; you must have a real touch-enabled device.

Parameters

touchPositions: Array

A Lua array of Vector2 objects, each indicating the position of all the fingers involved in the pinch gesture.

scale: number

A float that indicates the difference from the beginning of the pinch gesture.

velocity: number

A float indicating how quickly the pinch gesture is happening.

Indicates the Enum.UserInputState of the gesture.


Code Samples

Pinch/Pull Scaling

local innerFrame = script.Parent
local outerFrame = innerFrame.Parent
outerFrame.BackgroundTransparency = 0.75
outerFrame.Active = true
outerFrame.Size = UDim2.new(1, 0, 1, 0)
outerFrame.Position = UDim2.new(0, 0, 0, 0)
outerFrame.AnchorPoint = Vector2.new(0, 0)
outerFrame.ClipsDescendants = true
local dragging = false
local uiScale = Instance.new("UIScale")
uiScale.Parent = innerFrame
local baseScale
local function onTouchPinch(_touchPositions, scale, _velocity, state)
if state == Enum.UserInputState.Begin and not dragging then
dragging = true
baseScale = uiScale.Scale
outerFrame.BackgroundTransparency = 0.25
elseif state == Enum.UserInputState.Change then
uiScale.Scale = baseScale * scale -- Notice the multiplication here
elseif state == Enum.UserInputState.End and dragging then
dragging = false
outerFrame.BackgroundTransparency = 0.75
end
end
outerFrame.TouchPinch:Connect(onTouchPinch)

TouchRotate

This event fires when the player uses two fingers to make a pinch or pull gesture on the UI element using a touch-enabled device. Rotation occurs when the angle of the line between two fingers changes. This event fires in conjunction with GuiObject.TouchPan. This event is useful for allowing the player to manipulate the rotation of UI elements on the screen.

This event fires with a table of Vector2 that describe the relative screen positions of the fingers involved in the gesture. In addition, it fires multiple times: Enum.UserInputState.Begin after a brief delay, Enum.UserInputState.Change when the player moves a finger during the gesture, and finally with Enum.UserInputState.End.

Since this event requires at least two fingers, it is not possible to be simulated in Studio using the emulator and a mouse; you must have a real touch-enabled device.

Parameters

touchPositions: Array

A Lua array of Vector2 objects, each indicating the position of all the fingers involved in the gesture.

rotation: number

A float indicating how much the rotation has gone from the start of the gesture.

velocity: number

A float that indicates how quickly the gesture is being performed.

Indicates the Enum.UserInputState of the gesture.


Code Samples

Touch Rotation

local innerFrame = script.Parent
local outerFrame = innerFrame.Parent
outerFrame.BackgroundTransparency = 0.75
outerFrame.Active = true
outerFrame.Size = UDim2.new(1, 0, 1, 0)
outerFrame.Position = UDim2.new(0, 0, 0, 0)
outerFrame.AnchorPoint = Vector2.new(0, 0)
outerFrame.ClipsDescendants = true
local dragging = false
local baseRotation = innerFrame.Rotation
local function onTouchRotate(_touchPositions, rotation, _velocity, state)
if state == Enum.UserInputState.Begin and not dragging then
dragging = true
baseRotation = innerFrame.Rotation
outerFrame.BackgroundTransparency = 0.25
elseif state == Enum.UserInputState.Change then
innerFrame.Rotation = baseRotation + rotation
elseif state == Enum.UserInputState.End and dragging then
dragging = false
outerFrame.BackgroundTransparency = 0.75
end
end
outerFrame.TouchRotate:Connect(onTouchRotate)

TouchSwipe

This event fires when the player performs a swipe gesture on the UI element using a touch-enabled device. It fires with the direction of the gesture (Up, Down, Left or Right) and the number of touch points involved in the gesture. Swipe gestures are often used to change tabs in mobile UIs.

Since this event only requires one finger, it can be simulated in Studio using the emulator and a mouse.

Parameters

swipeDirection: Enum.SwipeDirection

A Enum.SwipeDirection indicating the direction of the swipe gesture (Up, Down, Left or Right).

numberOfTouches: number

The number of touch points involved in the gesture (usually 1).


Code Samples

Bouncing Color Picker

local frame = script.Parent
frame.Active = true
-- How far the frame should bounce on a successful swipe
local BOUNCE_DISTANCE = 50
-- Current state of the frame
local basePosition = frame.Position
local hue = 0
local saturation = 128
local function updateColor()
frame.BackgroundColor3 = Color3.fromHSV(hue / 256, saturation / 256, 1)
end
local function onTouchSwipe(swipeDir, _touchCount)
-- Change the BackgroundColor3 based on the swipe direction
local deltaPos
if swipeDir == Enum.SwipeDirection.Right then
deltaPos = UDim2.new(0, BOUNCE_DISTANCE, 0, 0)
hue = (hue + 16) % 255
elseif swipeDir == Enum.SwipeDirection.Left then
deltaPos = UDim2.new(0, -BOUNCE_DISTANCE, 0, 0)
hue = (hue - 16) % 255
elseif swipeDir == Enum.SwipeDirection.Up then
deltaPos = UDim2.new(0, 0, 0, -BOUNCE_DISTANCE)
saturation = (saturation + 16) % 255
elseif swipeDir == Enum.SwipeDirection.Down then
deltaPos = UDim2.new(0, 0, 0, BOUNCE_DISTANCE)
saturation = (saturation - 16) % 255
else
deltaPos = UDim2.new()
end
-- Update the color and bounce the frame a little
updateColor()
frame.Position = basePosition + deltaPos
frame:TweenPosition(basePosition, Enum.EasingDirection.Out, Enum.EasingStyle.Bounce, 0.7, true)
end
frame.TouchSwipe:Connect(onTouchSwipe)
updateColor()

TouchTap

This event fires when the player performs a tap gesture on the UI element using a touch-enabled device. A tap is a quick single touch without any movement involved (a longer press would fire GuiObject.TouchLongPress, and moving during the touch would fire GuiObject.TouchPan and/or GuiObject.TouchSwipe). It fires with a table of Vector2 objects that describe the relative positions of the fingers involved in the gesture.

Since this event only requires one finger, it can be simulated in Studio using the emulator and a mouse.

Parameters

touchPositions: Array

An array of Vector2 that describe the relative positions of the fingers involved in the gesture.


Code Samples

Tap Transparency Toggle

local frame = script.Parent
frame.Active = true
local function onTouchTap()
-- Toggle background transparency
if frame.BackgroundTransparency > 0 then
frame.BackgroundTransparency = 0
else
frame.BackgroundTransparency = 0.75
end
end
frame.TouchTap:Connect(onTouchTap)