Roblox UtilitiesDevlHub Roblox Documentation

Class

UIGradient

Inherits
UIComponent › UIBase › Instance › Object
Memory category
Instances

Applies a color and transparency gradient to the parent GuiObject.

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

Properties 8#

ColorColorSequenceDetermines the color blended with the parent GuiObject along the length of the gradient.ReadSafe
EnabledbooleanWhether the gradient is enabled or not.ReadSafe
OffsetVector2Determines the scalar translation of the gradient from the center of the parent GuiObject.ReadSafe
RotationfloatDetermines the clockwise rotation in degrees of the gradient starting from left to right.ReadSafe
ScalefloatMultiplies the extent of the gradient, controlling how much of the color/transparency sequence is visible within the element.ReadSafeNotBrowsable
TileModeGradientTileModeDetermines how the gradient repeats.ReadSafeNotBrowsable
TransparencyNumberSequenceDetermines how much the parent GuiObject can be seen through along the length of the gradient.ReadSafe
TypeGradientTypeDetermines the shape of the gradient as linear, radial, or conical.ReadSafeNotBrowsable

Color: ColorSequence#

ReadSafe

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.

Enabled: boolean#

ReadSafe

Whether the gradient is enabled or not.

Offset: Vector2#

ReadSafe

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.

Rotation: float#

ReadSafe

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.

Scale: float#

NotBrowsableReadSafe

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:

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

TileMode: GradientTileMode#

NotBrowsableReadSafe

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.

Transparency: NumberSequence#

ReadSafe

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.

Type: GradientType#

NotBrowsableReadSafe

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.

Inherited members#

Inherited from Instance 58
Properties (10)

Archivable, archivable, Capabilities, IsInSandbox, Name, Parent, PredictionMode, RobloxLocked, Sandboxed, UniqueId

Methods (39)

AddTag, children, ClearAllChildren, Clone, clone, Destroy, destroy, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, FindFirstChild, findFirstChild, FindFirstChildOfClass, FindFirstChildWhichIsA, FindFirstDescendant, GetActor, GetAttribute, GetAttributeChangedSignal, GetAttributes, GetChildren, getChildren, GetDebugId, GetDescendants, GetFullName, GetStyled, GetStyledPropertyChangedSignal, GetTags, HasTag, IsAncestorOf, IsDescendantOf, isDescendantOf, IsPropertyModified, QueryDescendants, Remove, remove, RemoveTag, ResetPropertyToDefault, SetAttribute, WaitForChild

Events (9)

AncestryChanged, AttributeChanged, ChildAdded, childAdded, ChildRemoved, DescendantAdded, DescendantRemoving, Destroying, StyledPropertiesChanged

Inherited from Object 6
Properties (2)

ClassName, className

Methods (3)

GetPropertyChangedSignal, IsA, isA

Events (1)

Changed