Skip to Content
Kinemium

GuiObject

Position, size, style, and interact with user interface elements in Luau.

GuiObject is the common base class for visual GUI elements. Whether you're making a panel, button, text label, or a more complex interface, GuiObject gives you the properties you need to control its layout, appearance, and input behavior.

It inherits from GuiBase2d. This page covers the members defined by GuiObject, in addition to the shared object behavior described in the Object and Instance references.

Getting started

The following example configures an existing GUI object inside your interface. It creates a centered panel that occupies half of the available width, with a fixed height.

local function stylePanel(panel)
    panel.AnchorPoint = Vector2.new(0.5, 0.5)
    panel.Position = UDim2.new(0.5, 0, 0.5, 0)
    panel.Size = UDim2.new(0.5, 0, 0, 180)
    panel.BackgroundColor3 = Color3.fromRGB(30, 32, 38)
    panel.BackgroundTransparency = 0
    panel.BorderSizePixel = 0
    panel.Visible = true
end

Properties

Defaults below refer to the base GuiObject; subclasses can choose different defaults.

Layout

PropertyTypeAccessDefaultDescription
PositionUDim2Read/writeUDim2.new(0, 0, 0, 0)Position relative to the parent.
SizeUDim2Read/writeUDim2.new(0, 100, 0, 100)Requested width and height.
AnchorPointVector2Read/writeVector2.new(0, 0)The point within the element placed at Position.
AbsolutePositionVector2Read-onlyInitially (0, 0)Resolved top-left position in GUI coordinates.
AbsoluteSizeVector2Read-onlyResolved from layoutActual width and height in GUI units.
AutomaticSizeEnum.AutomaticSizeRead/writeNoneLets the element resize to fit its content on selected axes.
LayoutOrdernumberRead/write0Integer order value for layout components.
RotationnumberRead/write0Rotation around the center of the element, in degrees.

Appearance

PropertyTypeAccessDefaultDescription
BackgroundColor3Color3Read/writeWhiteThe background color.
BackgroundTransparencynumberRead/write0Background transparency, clamped between 0 and 1.
TransparencynumberRead/write0Alias for BackgroundTransparency on the base class.
BorderColor3Color3Read/writeBlackThe border color.
BorderSizePixelnumberRead/write0Border thickness in pixels, stored as an integer.
BorderModeEnum.BorderModeRead/writeDefault enum valueHow the border is positioned relative to the object.
VisiblebooleanRead/writetrueWhether the object is visible. Hidden ancestors can also hide it.
ClipsDescendantsbooleanRead/writefalseRestricts descendants to the parent's clipping area.
ZIndexnumberRead/write0Integer stacking order property.

Transparency is recognized as a base property alias but isn't listed in the registered property metadata. A value of 1 makes the background transparent, not necessarily the text, images, or children.

ZIndex is exposed, but don't assume pointer hit testing sorts by ZIndex. The current hit traversal follows hierarchy and sibling order, testing later siblings and children first within a GUI tree.

Input

PropertyTypeAccessDefaultDescription
ActivebooleanRead/writefalseMakes the element eligible for pointer input and movement input notifications.
InputSinkbooleanRead/writefalseMakes the object eligible to receive pointer input even if Active is false.
SelectablebooleanRead/writetrueMarks whether the element is selectable.
GuiStateEnum.GuiStateRead/writeIdleCurrent stored GUI state.

GuiState can be assigned from Luau. The base class does not establish automatic transitions for every input event. Likewise, Selectable is a stored setting; a complete selection-navigation API is not defined here.

Positioning and sizing

UDim2 combines a relative scale with a fixed offset on each axis. If a parent is 800 pixels wide, an X scale of 0.5 with an offset of 20 resolves to 420 pixels.

local function align(panel)
    -- Full parent width, minus 24 pixels of space.
    panel.Size = UDim2.new(1, -24, 0, 48)
    panel.Position = UDim2.new(0, 12, 0, 12)
end

AnchorPoint

An anchor of (0, 0) places the top-left corner at Position. An anchor of (0.5, 0.5) places the center there, and (1, 1) places the bottom-right corner there.

local function center(panel)
    panel.AnchorPoint = Vector2.new(0.5, 0.5)
    panel.Position = UDim2.new(0.5, 0, 0.5, 0)
end

AutomaticSize

Use AutomaticSize when an element should grow to accommodate its content. The requested Size still contributes to the base dimensions, and available parent space, padding, and constraints can limit the final size.

ValueBehavior
Enum.AutomaticSize.NoneNo automatic growth.
Enum.AutomaticSize.XAutomatically sizes the width.
Enum.AutomaticSize.YAutomatically sizes the height.
Enum.AutomaticSize.XYAutomatically sizes both axes.
local function fitContent(panel)
    panel.Size = UDim2.new(1, 0, 0, 0)
    panel.AutomaticSize = Enum.AutomaticSize.Y
end

AbsolutePosition and AbsoluteSize

Read these when you need the geometry that has actually been resolved by layout. Layout components, size constraints, padding, and scrolling can change the final geometry without changing the requested Position or Size.

AbsolutePosition and AbsoluteSize cannot be assigned. Geometry may not yet reflect the latest changes before the next layout update; AbsoluteSize can calculate an initial size before the first layout pass.

Methods

ContainsPoint

ContainsPoint(x: number, y: number): boolean

Checks whether a point falls inside this GUI element. Pass screen-space GUI coordinates for screen interfaces, or canvas coordinates when testing elements on a surface interface. The method accounts for the object's rotation, ancestor rotations, effective visibility, and ancestor clipping.

local function isInside(panel, x, y)
    return panel:ContainsPoint(x, y)
end

This is a geometry check, not a guarantee that the element would receive a click. It does not require Active or InputSink, test whether another GUI covers it, or test the alpha of individual pixels.

Events

GuiObject exposes input events and mouse events. Connect to them with :Connect().

EventCallback argumentsDescription
InputBeganinput: InputObjectA supported mouse button is pressed on the selected target.
InputChangedinput: InputObjectPointer movement for active elements in the hit chain, or a mouse wheel change on the selected target.
InputEndedinput: InputObjectA mouse button is released after being pressed on the target.
MouseEnterx: number, y: numberThe pointer enters the object's hover area.
MouseLeavex: number, y: numberThe pointer leaves the object's hover area.
MouseMovedx: number, y: numberThe pointer moves while hovering over the object.
MouseWheelForwardx: number, y: numberThe mouse wheel scrolls forward over the target.
MouseWheelBackwardx: number, y: numberThe mouse wheel scrolls backward over the target.

Mouse coordinates are in screen space for screen GUI elements and canvas space for surface GUI hits, rather than offsets relative to the receiving object. A surface pointer leaving the canvas may report its last valid position.

Hover effects

You can listen to hover events even on a passive element that doesn't consume clicks.

local function addHoverEffect(panel)
    local originalColor = panel.BackgroundColor3

    panel.MouseEnter:Connect(function()
        panel.BackgroundColor3 = Color3.fromRGB(65, 70, 85)
    end)

    panel.MouseLeave:Connect(function()
        panel.BackgroundColor3 = originalColor
    end)
end

Processing mouse input

Set Active to true to make a regular GUI object eligible to receive pointer input. InputSink also makes it eligible, and text boxes are eligible independently of these settings. Transparent objects can still receive input.

local function listenForPress(panel)
    panel.Active = true

    panel.InputBegan:Connect(function(input)
        if input.UserInputType == Enum.UserInputType.MouseButton1 then
            print("Pressed at", input.Position)
        end
    end)

    panel.InputEnded:Connect(function(input)
        if input.UserInputType == Enum.UserInputType.MouseButton1 then
            print("Released at", input.Position)
        end
    end)
end

The release is delivered to the original pressed target even if the pointer has moved outside its bounds. This is useful for drag interactions. The input objects are temporary; read or copy the values you need inside the callback rather than retaining the input object for later use.

The base GUI event dispatcher shown here handles mouse movement, mouse buttons, and mouse wheel input. Keyboard, touch, and gamepad delivery through these particular events are not established by this class. InputBegan, InputChanged, and InputEnded pass one argument, not a second processed-input flag.

See also

  • Instance, parent, children, cloning, attributes, tags, and property-change notifications.
  • Object, shared object behavior.
  • UIShader, custom visual effects for GUI elements.

On this page