Skip to content

UIButton

A UIControl for a button, should be inside client context. Inherits from UIControl.

Properties

Property Name Return Type Description Tags
text string Returns the button's label text. Read-Write
fontSize integer Returns the font size of the label text. Read-Write
isInteractable boolean Returns whether the Button can interact with the cursor (click, hover, etc). Read-Write
shouldClipToSize boolean Whether or not the button and its shadow should be clipped when exceeding the bounds of this control. Read-Write
shouldScaleToFit boolean Whether or not the button's label should scale down to fit within the bounds of this control. Read-Write
boundAction string Returns the name of the action binding that is toggled when the button is pressed or released, or nil if no binding has been set. Read-Write
isHittable boolean When set to true, this control can receive input from the cursor and blocks input to controls behind it. When set to false, the cursor ignores this control and can interact with controls behind it. Read-Write

Functions

Function Name Return Type Description Tags
GetButtonColor() Color Gets the button's default color. None
SetButtonColor(Color) None Sets the button's default color. None
GetHoveredColor() Color Gets the button's color when hovered. None
SetHoveredColor(Color) None Sets the button's color when hovered. None
GetPressedColor() Color Gets the button's color when pressed. None
SetPressedColor(Color) None Sets the button's color when pressed. None
GetDisabledColor() Color Gets the button's color when it's not interactable. None
SetDisabledColor(Color) None Sets the button's color when it's not interactable. None
GetFontColor() Color Gets the font's color. None
SetFontColor(Color) None Sets the font's color. None
SetImage(string brushMUID) None Sets the image to a new MUID. You can get this MUID from an Asset Reference. None
SetFont(string fontId) None Sets the button's text to use the specified font asset. None
GetShadowColor() Color Returns the color of the button's drop shadow. None
SetShadowColor(Color) None Sets the color of the button's drop shadow. None
GetShadowOffset() Vector2 Returns the offset of the button's drop shadow in UI space. None
SetShadowOffset(Vector2) None Sets the offset of the button's drop shadow in UI space. None
GetCurrentTouchIndex() integer Returns the touch index currently interacting with this button. Returns nil if the button is not currently being interacted with. Client-Only

Events

Event Name Return Type Description Tags
clickedEvent Event<UIButton> Fired when button is clicked. This triggers on mouse-button up, if both button-down and button-up events happen inside the button hitbox. None
pressedEvent Event<UIButton> Fired when button is pressed. (mouse button down) None
releasedEvent Event<UIButton> Fired when button is released. (mouse button up) None
hoveredEvent Event<UIButton> Fired when button is hovered. None
unhoveredEvent Event<UIButton> Fired when button is unhovered. None
touchStartedEvent Event<UIButton, Vector2 location, integer touchIndex> Fired when the player starts touching the control on a touch input device. Parameters are the screen location of the touch and a touch index used to distinguish between separate touches on a multitouch device. Client-Only
touchStoppedEvent Event<UIButton, Vector2 location, integer touchIndex> Fired when the player stops touching the control on a touch input device. Parameters are the screen location from which the touch was released and a touch index used to distinguish between separate touches on a multitouch device. Client-Only
tappedEvent Event<UIButton, Vector2 location, integer touchIndex> Fired when the player taps the control on a touch input device. Parameters are the screen location of the tap and the touch index with which the tap was performed. Client-Only
flickedEvent Event<UIButton, number angle> Fired when the player performs a quick flicking gesture on the control on a touch input device. The angle parameter indicates the direction of the flick. 0 indicates a flick to the right. Values increase in degrees counter-clockwise, so 90 indicates a flick straight up, 180 indicates a flick to the left, etc. Client-Only
pinchStartedEvent Event<UIButton> Fired when the player begins a pinching gesture on the control on a touch input device. Input.GetPinchValue() may be polled during the pinch gesture to determine how far the player has pinched. Client-Only
pinchStoppedEvent Event<UIButton> Fired when the player ends a pinching gesture on a touch input device. Client-Only
rotateStartedEvent Event<UIButton> Fired when the player begins a rotating gesture on the control on a touch input device. Input.GetRotateValue() may be polled during the rotate gesture to determine how far the player has rotated. Client-Only
rotateStoppedEvent Event<UIButton> Fired when the player ends a rotating gesture on a touch input device. Client-Only

Examples

Example using:

GetTouchPosition

GetPinchValue

GetRotateValue

pinchStartedEvent

pinchStoppedEvent

rotateStartedEvent

rotateStoppedEvent

In this example we manipulate a UI Button object with a multi-touch pinching gesture. The pinch gesture is used to move, scale and rotate a the UI Text on screen.

-- Client Script as a child of the UI Text.
local UI_OBJECT = script.parent

-- Make the UI Control hittable
UI_OBJECT.isHittable = true

local isPinching = false
local isRotating = false
local startingWidth
local startingHeight
local startingAngle

function Tick()
    -- Position
    local touch1 = Input.GetTouchPosition(1)
    local touch2 = Input.GetTouchPosition(2)

    if touch1 ~= nil and touch2 ~= nil then
        local position = (touch1 + touch2) / 2

        UI_OBJECT:SetAbsolutePosition(position)
    end

    -- Scale
    if isPinching then
        local pinchPercent = Input.GetPinchValue()

        UI_OBJECT.width = CoreMath.Round(startingWidth * pinchPercent)
        UI_OBJECT.height = CoreMath.Round(startingHeight * pinchPercent)
    end

    -- Rotate
    if isRotating then
        local angle = Input.GetRotateValue()

        UI_OBJECT.rotationAngle = startingAngle + angle
    end
end

local function OnPinchStarted()
    isPinching = true
    startingWidth = UI_OBJECT.width
    startingHeight = UI_OBJECT.height
end

local function OnPinchStopped()
    isPinching = false
end

-- Detect pinch gesture start/end
UI_OBJECT.pinchStartedEvent:Connect(OnPinchStarted)
UI_OBJECT.pinchStoppedEvent:Connect(OnPinchStopped)

local function OnRotateStarted()
    isRotating = true
    startingAngle = UI_OBJECT.rotationAngle
end

local function OnRotateStopped()
    isRotating = false
end

-- Detect rotation gesture start/end
UI_OBJECT.rotateStartedEvent:Connect(OnRotateStarted)
UI_OBJECT.rotateStoppedEvent:Connect(OnRotateStopped)

See also: UIControl.SetAbsolutePosition | UIButton.isHittable | CoreObject.parent | CoreMath.Round


Example using:

clickedEvent

pressedEvent

releasedEvent

hoveredEvent

unhoveredEvent

text

This example will demonstrate how you can listen for the various events of a UI button object. This example will also show you how to change the text in a UI Button by using the text property of the UI Button.

-- Make the cursor visible
UI.SetCursorVisible(true)

--Allow the cursor to interact with UI
UI.SetCanCursorInteractWithUI(true)

-- Get the UI button object so that its events can be listened to
local propUIButton = script:GetCustomProperty("UIButton"):WaitForObject()

-- This function will be called whenever the button is click
function OnClick(button)
    print("The button has been pressed")
end

-- This function will be called whenever the player presses down on the button
function OnPress(button)
    -- Change the text displayed by the button
    button.text = "Button is being held"
end

-- This function will be called whenever the player releases their mouse after having
-- held it down over the button
function OnRelease(button)
    -- Change the text displayed by the button
    button.text = "Button was released"
end

-- This function will be called whenever the mouse passes over the button
function OnHover(button)
    -- Change the text displayed by the button
    button.text = "Mouse is over button"
end

-- This function will be called whenever your mouse passes off of the button
function OnUnhover(button)
    -- Change the text displayed by the button
    button.text = "Mouse off of button"
end

-- Bind the "OnClick" function to the "clickedEvent" of the button so that clicking on the
-- button fires the "OnClick" function
propUIButton.clickedEvent:Connect(OnClick)

-- Bind the "OnPress" function to the "pressedEvent" of the button so that the "OnPress" function
-- is fired immediately after the mouse is held down and on top of the button
propUIButton.pressedEvent:Connect(OnPress)

-- Bind the "OnRelease" function to the "releasedEvent" of the button. This will cause the "OnRelease" function
-- to be fired whenever the left mouse button is released while the mouse is above the button
propUIButton.releasedEvent:Connect(OnRelease)

-- Bind the "OnHover" function to the "hoverEvent" of the button. This will cause the "OnHover" function to be
-- fired whenever the mouse passes over the button.
propUIButton.hoveredEvent:Connect(OnHover)

-- Bind the "OnUnhover" function to the "unhoveredEvent" of the button. THis will cause the "OnUnhover" function to
-- be fired whenever the mouse leaves the button.
propUIButton.unhoveredEvent:Connect(OnUnhover)

See also: CoreObject.GetCustomProperty | UI.SetCursorVisible


Example using:

tappedEvent

flickedEvent

In this example we listen for the tapped and flicked touch gestures on the UI object. When one of those events is triggered, the pertinent information is printed to the screen.

-- Client Script as a child of the UI Button.
local UI_OBJECT = script.parent

-- Make the UI Control hittable
UI_OBJECT.isHittable = true

function OnTappedEvent(control, location, touchIndex)
    UI.PrintToScreen("Tap ".. touchIndex ..": ".. tostring(location))
end

function OnFlickedEvent(control, angle)
    UI.PrintToScreen("Flick: " .. angle)
end

UI_OBJECT.tappedEvent:Connect(OnTappedEvent)
UI_OBJECT.flickedEvent:Connect(OnFlickedEvent)

See also: UI.PrintToScreen | Event.Connect | UIButton.isHittable


Example using:

touchStartedEvent

touchStoppedEvent

In this example, the touch inputs on the UI object are tracked in two different ways, with a counter and with a table. Each time the amount of touches change a summary of the touch information is printed to screen.

-- Client Script as a child of the UI Button.
local UI_OBJECT = script.parent

-- Make the UI Control hittable
UI_OBJECT.isHittable = true

local touchCount = 0
local activeTouches = {}

function PrintTouchInfo()
    local str = touchCount .. ": ["
    local addComma = false

    for id,_ in pairs(activeTouches) do
        if addComma then
            str = str .. ", "
        end

        addComma = true
        str = str .. id
    end

    str = str .. "]"

    UI.PrintToScreen(str)
end

local function OnTouchStarted(control, location, touchId)
    touchCount = touchCount + 1
    activeTouches[touchId] = true

    PrintTouchInfo()
end

local function OnTouchStopped(control, location, touchId)
    touchCount = touchCount - 1
    activeTouches[touchId] = nil

    PrintTouchInfo()
end

UI_OBJECT.touchStartedEvent:Connect(OnTouchStarted)
UI_OBJECT.touchStoppedEvent:Connect(OnTouchStopped)

See also: UI.PrintToScreen | Event.Connect | UIButton.isHittable


Example using:

SetButtonColor

unhoveredEvent

This example will show you how to change the color of a button by using the SetButtonColor method. It's important to remember that colors in Core use red, gree, and blue values between 0 and 1 as opposed to values between 0 and 255.

-- Make the cursor visible
UI.SetCursorVisible(true)

--Allow the cursor to interact with UI
UI.SetCanCursorInteractWithUI(true)

-- Get the UI Button object
local propUIButton = script:GetCustomProperty("UIButton"):WaitForObject()

-- The button will switch to this color when the mouse leaves the button
local MouseOffColor = Color.New(0.5, 0.2, 0.4)

-- This function will be called whenever the mouse leaves the button and set
-- the color of the button to the color of "MouseOffColor"
function OnUnhover(button)
    button:SetButtonColor(MouseOffColor)
end

-- Bind the "OnUnhover" function to the "unhoveredEvent" of the button. THis will cause the "OnUnhover" function to
-- be fired whenever the mouse leaves the button
propUIButton.unhoveredEvent:Connect(OnUnhover)

See also: Color.New | CoreObject.GetCustomProperty | UI.SetCursorVisible


Example using:

boundAction

pressedEvent

UI Buttons can be used as direct input to control the gameplay. This is especially useful for touch-screen devices, where UI Buttons can be setup as virtual controls. In this example, a UI Button has a value set for its boundAction property. When the button is pressed, the button's pressedEvent will callback. If the boundAction property has been set to a valid input action (for example "Jump") then the Input actionPressedEvent will also callback.

local UIBUTTON = script:GetCustomProperty("UIButton"):WaitForObject()

UI.SetCursorVisible(true)
UI.SetCanCursorInteractWithUI(true)

local function OnPressed()
    print("Button: " .. UIBUTTON.boundAction)
end

local function OnActionPressed(player, action, value)
    print("Action: " .. action .. ", value: " .. tostring(value))
end

UIBUTTON.pressedEvent:Connect(OnPressed)
Input.actionPressedEvent:Connect(OnActionPressed)

See also: Input.actionPressedEvent | CoreObject.GetCustomProperty | UI.SetCanCursorInteractWithUI


Tutorials

UI in Core


Last update: June 30, 2022