10 min read

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

UIGradient

Inherits from: UIComponent → UIBase → Instance → Object

UIGradient applies a color and transparency gradient to the parent GuiObject. The appearance of the gradient is configurable through its Color, Transparency, Offset, Rotation, Scale, TileMode, and Type.

UIGradient will not apply to child or descendant GuiObjects. In order to apply the same gradient to multiple objects, you will need multiple gradient instances.

See also appearance modifiers for more information on the UIGradient modifier and how it works.

Supported Objects

You can apply UIGradient modifiers to Frame, TextLabel, TextButton, ImageLabel, ImageButton, Path2D, and ViewportFrame. However, ScrollingFrame and TextBox are not currently supported.

Performance Considerations

In order to efficiently use a UIGradient, follow these principles:

Avoid using more than 6 color stops on the Color sequence.
Avoid using a UIGradient on any object that applies a text stroke (TextStrokeColor3), as the gradient will try to blend with strokes and borders, and may cause performance issues.
Avoid setting Color and Transparency frequently: this causes the sequence of colors to rebuild often, which is expensive. If possible, set these properties only once and try to animate the Offset or Rotation properties to achieve a similar effect. Alternatively, you can change the color of the parent GuiObject using such properties as BackgroundColor3, ImageColor3, or TextColor3.
When applying an unchanging gradient on a UI element whose state changes a lot, there is a tradeoff between using a UIGradient (processing time) and a static gradient image (memory).

Inherits from: UIComponent

Memory category: Instances

Properties

Name	Type / Returns	Description
UIGradient.Color	ColorSequence	Determines the color blended with the parent `GuiObject` along the length of the gradient.
UIGradient.Enabled	boolean	Whether the gradient is enabled or not.
UIGradient.Offset	Vector2	Determines the scalar translation of the gradient from the center of the parent `GuiObject`.
UIGradient.Rotation	float	Determines the clockwise rotation in degrees of the gradient starting from left to right.
UIGradient.Scale	float	Multiplies the extent of the gradient, controlling how much of the color/transparency sequence is visible within the element.
UIGradient.TileMode	GradientTileMode	Determines how the gradient repeats.
UIGradient.Transparency	NumberSequence	Determines how much the parent `GuiObject` can be seen through along the length of the gradient.
UIGradient.Type	GradientType	Determines the shape of the gradient as linear, radial, or conical.

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

UIGradient.Color

This property describes the color to blend with the parent GuiObject along the provided ColorSequence. This property works in a similar manner to Beam.Color or Trail.Color, except that it applies over a distance determined by the Offset and Rotation.

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

UIGradient.Enabled

Whether the gradient is enabled or not.

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

UIGradient.Offset

This property determines the scalar translation of the gradient from the center of the parent GuiObject. It is a scalar translation, meaning that the actual pixel offset is determined by the AbsoluteSize of the parent GuiObject. For example, a value of (1, 0) shifts the gradient horizontally to the right by a distance equal to the parent object's size. Depending on the Rotation, this may cause the gradient to be partially visible or not visible at all.

Also see Rotation which also affects the geometry of the applied gradient.

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

UIGradient.Rotation

This property determines the clockwise rotation in degrees of the UIGradient starting from left to right. The beginning and end control points snap to the edges of the parent GuiObject, but maintain the provided rotation.

Also see Offset which also affects the geometry of the applied gradient.

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

UIGradient.Scale

This property multiplies the extent of the gradient, controlling how much of the color/transparency sequence is visible within the parent GuiObject.

A value of 1 (default) means the full sequence spans the element exactly once.
Values less than 1 compress the gradient so that the full sequence fits in a smaller region. The remaining area is determined by TileMode. Note that Scale is clamped to a minimum of 0.001 to avoid degenerate gradients.
Values greater than 1 stretch the gradient beyond the element bounds so that only a portion of the sequence is visible.

The effect of Scale also depends on the gradient's Type:

GradientType.Linear — Scale affects the distance between the start and end control points.
GradientType.Radial — Scale affects the radius of the radial gradient.
GradientType.Conical — Scale affects the angular sweep, clamped so that the sweep does not exceed a full revolution.

See also TileMode which determines how the gradient repeats when Scale causes it to not fill the entire element.

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

UIGradient.TileMode

This property determines what happens when the gradient Scale is less than 1 or when Offset shifts the gradient so that it does not fully cover the element. See GradientTileMode for possible values and their effect.

See also Scale which controls how much of the color/transparency sequence is visible.

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

UIGradient.Transparency

This property describes how opaque the parent UI element will be along the provided NumberSequence. This property works in a similar manner to Beam.Transparency or Trail.Transparency, except that it applies over a distance determined by the Offset and Rotation.

Note that the envelope values of the NumberSequenceKeypoints are ignored.

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

UIGradient.Type

This property determines how the gradient varies across the parent GuiObject. See GradientType for possible values and their effect.

See also Scale which controls how much of the color/transparency sequence is visible, and TileMode which determines repetition behavior.

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

Methods

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 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.