15 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

ImageLabel

Inherits from: GuiLabel → GuiObject → GuiBase2d → GuiBase → Instance → Object

An ImageLabel renders a rectangle, like a Frame does, with an image asset. The display of the image can be manipulated through the ImageColor3 and ImageTransparency properties. To display only the image and hide the rectangle, set GuiObject.BackgroundTransparency to 1.

Advanced ImageLabel usage includes:

Tiled images can be created by setting ScaleType to ScaleType.Tile, then TileSize to the size of rendered tiles.
9-slice images can be created by setting ScaleType to ScaleType.Slice, then SliceCenter to the center area of the 9‑slice image.
Sprite sheets can be implemented through the use of ImageRectOffset and ImageRectSize. Packing multiple images into one and using this property can make your experience's image assets load much quicker, especially if you use many small icons in your GUIs.

Inherits from: GuiLabel

Memory category: Gui

Properties

Name	Type / Returns	Description
ImageLabel.Image	ContentId	The image content displayed by the UI element. Reads and writes to `ImageContent`.
ImageLabel.ImageColor3	Color3	Determines how a rendered image will be colorized.
ImageLabel.ImageContent	Content	The image content displayed by the UI element. Supports asset URIs and `EditableImage` objects.
ImageLabel.ImageRectOffset	Vector2	The offset in pixels of the sub-area of an image to be displayed.
ImageLabel.ImageRectSize	Vector2	Determines the size in pixels of the sub-area of an image to be displayed.
ImageLabel.ImageTransparency	float	Determines the transparency of the rendered image.
ImageLabel.IsLoaded	boolean	Indicates whether the image has finished loading from Roblox.
ImageLabel.ResampleMode	ResamplerMode	Selects the image resampling mode for the label.
ImageLabel.ScaleType	ScaleType	Determines how an image will scale if displayed in a UI element whose size differs from the source image.
ImageLabel.SliceCenter	Rect	Sets the slice boundaries of a 9-sliced image.
ImageLabel.SliceScale	float	Scales the 9-slice edges by the specified ratio.
ImageLabel.TileSize	UDim2	Sets the tiling size of the `ImageLabel`.

Inherited from GuiObject

Name	Type / Returns	Description
GuiObject.Active	boolean	Determines whether this UI element sinks input.
GuiObject.AnchorPoint	Vector2	Determines the origin point of a `GuiObject`, relative to its absolute size.
GuiObject.AutomaticSize	AutomaticSize	Determines whether resizing occurs based on child content.
GuiObject.BackgroundColor	BrickColor	Determines the color of the `GuiObject` background.
GuiObject.BackgroundColor3	Color3	Determines the `GuiObject` background color.
GuiObject.BackgroundTransparency	float	Determines the transparency of the `GuiObject` background and border.
GuiObject.BorderColor	BrickColor	Determines the color of the `GuiObject` border.
GuiObject.BorderColor3	Color3	Determines the color of the `GuiObject` border.
GuiObject.BorderMode	BorderMode	Determines in what manner the `GuiObject` border is laid out relative to its dimensions.
GuiObject.BorderSizePixel	int	Determines the pixel width of the `GuiObject` border.
GuiObject.ClipsDescendants	boolean	Determines if descendant `GuiObjects` outside of the bounds of a parent GUI element should render.
GuiObject.Draggable	boolean	Determines whether a `GuiObject` (and its descendants) can be dragged around the screen.
GuiObject.GuiState	GuiState	Determines whether the player's mouse is being actively pressed on the `GuiObject` or not.
GuiObject.InputSink	InputSink	Controls whether, and how, the `GuiObject` sinks input that occurs over it.
GuiObject.Interactable	boolean	Determines whether the `GuiButton` can be interacted with or not, or if the `GuiState` of the `GuiObject` is changing or not.
GuiObject.LayoutOrder	int	Controls the sort order of the `GuiObject` when used with a `UIGridStyleLayout`.
GuiObject.NextSelectionDown	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved downward.
GuiObject.NextSelectionLeft	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved to the left.
GuiObject.NextSelectionRight	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved to the right.
GuiObject.NextSelectionUp	GuiObject	Sets the `GuiObject` which will be selected when the gamepad selector is moved upward.
GuiObject.Position	UDim2	Determines the pixel and scalar position of the `GuiObject`.
GuiObject.Rotation	float	Determines the number of degrees by which the `GuiObject` is rotated.
GuiObject.Selectable	boolean	Determine whether the `GuiObject` can be selected by a gamepad.
GuiObject.SelectionImageObject	GuiObject	Overrides the default selection adornment used for gamepads.
GuiObject.SelectionOrder	int	The order of `GuiObjects` selected by the gamepad UI selection.
GuiObject.Size	UDim2	Determines the pixel and scalar size of the `GuiObject`.
GuiObject.SizeConstraint	SizeConstraint	Sets the `Size` axes that the `GuiObject` will be based on, relative to the size of its parent.
GuiObject.Transparency	float	A mixed property of `BackgroundTransparency` and `TextTransparency`.
GuiObject.Visible	boolean	Determines whether the `GuiObject` and its descendants will be rendered.
GuiObject.ZIndex	int	Determines the order in which a `GuiObject` renders relative to others.

Inherited from GuiBase2d

Name	Type / Returns	Description
GuiBase2d.AbsolutePosition	Vector2	Describes the actual screen position of a `GuiBase2d` element, in pixels.
GuiBase2d.AbsoluteRotation	float	Describes the actual screen rotation of a `GuiBase2d` element, in degrees.
GuiBase2d.AbsoluteSize	Vector2	Describes the actual screen size of a `GuiBase2d` element, in pixels.
GuiBase2d.AutoLocalize	boolean	When set to `true`, localization will be applied to this `GuiBase2d` and its descendants.
GuiBase2d.Localize	boolean	Automatically set to true when a localization table's `LocalizationTable.Root` targets this object, or an ancestor of this object.
GuiBase2d.RootLocalizationTable	LocalizationTable	A reference to a `LocalizationTable` to be used to apply automated localization to this `GuiBase2d` and its descendants.
GuiBase2d.SelectionBehaviorDown	SelectionBehavior	Customizes gamepad selection behavior in the down direction.
GuiBase2d.SelectionBehaviorLeft	SelectionBehavior	Customizes gamepad selection behavior in the left direction.
GuiBase2d.SelectionBehaviorRight	SelectionBehavior	Customizes gamepad selection behavior in the right direction.
GuiBase2d.SelectionBehaviorUp	SelectionBehavior	Customizes gamepad selection behavior in the up direction.
GuiBase2d.SelectionGroup	boolean	Allows customization of gamepad selection movement.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

ImageLabel.Image

This property is a content-type property that should hold the asset ID of a decal or image uploaded to Roblox. It functions identically to Decal.Texture with regards to loading the image from Roblox. The rendered image can be modified using ImageColor3 and ImageTransparency.

Field	Value
type	ContentId
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.ImageColor3

This property determines how an image is colorized. When set to white, no colorization occurs. This property is very useful for reusing image assets; if the source image is completely white with transparency, you can set the entire color of the image at once with this property.

Field	Value
type	Color3
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.ImageContent

This property should hold an asset URI or a reference to an EditableImage object.

The asset URI can reference a decal or image uploaded to Roblox. It functions identically to Decal.Texture with regards to loading the image.

The rendered image will be colorized using ImageButton.ImageColor3. It is possible to make the image render as tiled, scaled to fit, or 9-sliced, by adjusting the ImageButton.ScaleType property.

Field	Value
type	Content
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.ImageRectOffset

Allows the partial display of an image in conjunction with ImageRectSize. This property determines the pixel offset (from the top-left) of the image area to be displayed.

Field	Value
type	Vector2
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.ImageRectSize

Allows the partial display of an image in conjunction with ImageRectOffset. This property determines the pixel size of the image area to be displayed. If either dimension is set to 0, the entire image is displayed instead.

Field	Value
type	Vector2
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.ImageTransparency

This property determines the alpha of a UI element's rendered image. A value of 0 is completely opaque and a value of 1 is completely transparent (invisible).

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

Code samples: View on Creator Hub (Oscillate-ImageTransparency).

ImageLabel.IsLoaded

This property indicates if the ImageLabel.Image property has finished loading from Roblox. Images declined by moderation will never load.

Field	Value
type	boolean
tags	["ReadOnly","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":false,"can_save":false}
capabilities	["UI"]

Code samples: View on Creator Hub (Image-Load-Time).

ImageLabel.ResampleMode

Determines how the image looks when it is scaled. By default, the image smooths out texturing when displayed on the screen larger or smaller than its size in texture memory. When set to Enum.ResamplerMode.Pixelated, the image preserves the sharp edges of pixels.

Field	Value
type	ResamplerMode
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.ScaleType

This property determines in what way an ImageLabel.Image is rendered when the UI element's absolute size differs from the source image's size.

By default, this property is ScaleType.Stretch which will simply stretch/compact the image dimensions so it fits the UI element's space exactly. Since transparent pixels are set to black when uploading to Roblox, transparent images should apply alpha blending to avoid a blackish outline around scaled images.

For ScaleType.Slice, the SliceCenter property will be revealed in the Properties window. This is for nine-slice UI: when scaling up, the corners will remain the source image size. The edges of the image will stretch to the width/height of the image. Finally, the center of the image will stretch to fill the center area of the image.

Finally, for ScaleType.Tile, the TileSize property will be revealed in the Properties window. This is for tiled images, where the size of each image tile is determined by the TileSize property.

Field	Value
type	ScaleType
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.SliceCenter

This property sets the slice boundaries of a 9-sliced image when ScaleType is set to Enum.ScaleType.Slice. Please note that this property is only visible in the Properties window under this condition.

To learn more about 9-slice images, see UI 9 Slice Design.

Field	Value
type	Rect
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.SliceScale

Scales the 9-slice edges by the specified ratio. This means that the edges around the 9-slice will grow as if you'd uploaded a new version of the texture upscaled. Defaults to 1.0.

See also ScaleType, SliceCenter, and SliceScale.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

ImageLabel.TileSize

This property sets the tiling size of the ImageLabel with a default of

UDim2.new(1, 0, 1, 0) . Tiling starts at the top-left corner of the image. This property is only active if the ScaleType for the ImageLabel is set to ScaleType.Tile.

Field	Value
type	UDim2
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Image
serialization	{"can_load":true,"can_save":true}
capabilities	["UI"]

Code samples: View on Creator Hub (Image-ScaleType-Demo).

Methods

Inherited from GuiObject

Name	Type / Returns	Description
GuiObject:TweenPosition	boolean	Smoothly moves a GUI to a new `UDim2`.
GuiObject:TweenSize	boolean	Smoothly resizes a `GuiObject` to a new `UDim2`.
GuiObject:TweenSizeAndPosition	boolean	Smoothly moves a GUI to a new size and position.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

Events

Inherited from GuiObject

Name	Type / Returns	Description
GuiObject.DragBegin		Fired when a player begins dragging the object.
GuiObject.DragStopped		Fired when a player stops dragging the object.
GuiObject.InputBegan		Fired when a user begins interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
GuiObject.InputChanged		Fired when a user changes how they're interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
GuiObject.InputEnded		Fired when a user stops interacting via a Human-Computer Interface device (Mouse button down, touch begin, keyboard button down, etc).
GuiObject.MouseEnter		Fires when a user moves their mouse into a GUI element.
GuiObject.MouseLeave		Fires when a user moves their mouse out of a GUI element.
GuiObject.MouseMoved		Fires whenever a user moves their mouse while it is inside a GUI element.
GuiObject.MouseWheelBackward		Fires when a user scrolls their mouse wheel back when the mouse is over a GUI element.
GuiObject.MouseWheelForward		Fires when a user scrolls their mouse wheel forward when the mouse is over a GUI element.
GuiObject.SelectionGained		Fired when the GuiObject is being focused on with the Gamepad selector.
GuiObject.SelectionLost		Fired when the Gamepad selector stops focusing on the GuiObject.
GuiObject.TouchLongPress		Fires when the player starts, continues and stops long-pressing the UI element.
GuiObject.TouchPan		Fires when the player moves their finger on the UI element.
GuiObject.TouchPinch		Fires when the player performs a pinch or pull gesture using two fingers on the UI element.
GuiObject.TouchRotate		Fires when the player performs a rotation gesture using two fingers on the UI element.
GuiObject.TouchSwipe		Fires when the player performs a swipe gesture on the UI element.
GuiObject.TouchTap		Fires when the player performs a tap gesture on the UI element.

Inherited from GuiBase2d

Name	Type / Returns	Description
GuiBase2d.SelectionChanged		Fires when the gamepad selection moves to, leaves, or changes within the connected `GuiBase2d` or any descendant `GuiObjects`.

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.