UIGradient

Show Deprecated

UIGradient is a UIComponent that applies a color and transparency gradient to the UI elements rendered by the parent GuiObject. The appearance of the gradient is configurable through the following properties:

Gradient Window Example

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

Supported Objects

You can apply gradients to Frame, TextLabel, TextButton, ImageLabel, ImageButton, 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): 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 trade-off between using a UIGradient (processing time) and a static gradient image (memory).

See also:

Summary

Properties

Color: ColorSequence

Determines the color blended with the parent GuiObject along the length of the gradient.

Enabled: boolean

Whether the gradient is enabled or not.

Offset: Vector2

Determines the scalar translation of the gradient from the center of the parent GuiObject.

Rotation: number

Determines the clockwise rotation in degrees of the gradient starting from left to right.

Transparency: NumberSequence

Determines how much the parent GuiObject can be seen through along the length of the gradient.

Methods

Events

Properties

Color

ColorSequence
Read Parallel

The Color of a UIGradient describes the color to blend with the parent UI element along the provided ColorSequence. This property works in a similar manner to Beam.Color or Trail.Color, except that it applies over an on-screen distance determined by the Offset and Rotation of the UIGradient. The image below shows the linear interpolation of four color values:

How the UIGradient Color ColorSequence applies color to a GuiObject

Enabled

boolean
Read Parallel

Whether the gradient is enabled or not.

Offset

Vector2
Read Parallel

The Offset of a UIGradient determines the scalar translation of the gradient from the center of the parent GuiObject. This value is a scalar translation, meaning that the actual pixel offset is determined by the AbsoluteSize of the parent GuiObject. So, a value of (1, 0) would shift the gradient horizontally to the right by a distance equal to the parent GuiObject's on screen-size. Depending on the Rotation, this may cause the gradient to be partially visible or not visible at all.

An animation of a UIGradient's Offset being animated on the X axis from -1 to 1.

In the animation above, the offset of a UIGradient is animated back and forth between the values (-1, 0) and (1, 0). The red dot indicates the start of the gradient, and the blue dot indicates the end. Note how the distance animated is twice that of the frame's width, as the offset is scalar.

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

Code Samples

UIGradient.Offset Animation
local RunService = game:GetService("RunService")



local OFFSET_SPEED_X = 1 -- units per second



local uiGradient = script.Parent



local function onRenderStep(deltaTime)

	local currentOffsetX = uiGradient.Offset.X

	if currentOffsetX < -1 then

		uiGradient.Offset = Vector2.new(1, 0)

	else

		uiGradient.Offset = Vector2.new(currentOffsetX - OFFSET_SPEED_X * deltaTime, 0)

	end

end



RunService.RenderStepped:Connect(onRenderStep)

Rotation

number
Read Parallel

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

An animation of a UIGradient's Rotation being animated from 0 to 360

The animation above shows the snapping behavior of the gradient control points. The red indicates the start point, and the blue indicates the end. Although the control points do not move at a constant pace, the angle between them changes at a constant pace.

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

Code Samples

UIGradient.Rotation Animation
local RunService = game:GetService("RunService")



local ROTATE_SPEED = 90 -- degrees per second



local uiGradient = script.Parent



local function onRenderStep(deltaTime)

	local currentRotation = uiGradient.Rotation

	uiGradient.Rotation = (currentRotation + ROTATE_SPEED * deltaTime) % 360

end



RunService.RenderStepped:Connect(onRenderStep)

Transparency

NumberSequence
Read Parallel

The Transparency of a UIGradient describes how "see-through" 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 an on-screen distance determined by the Offset and Rotation of the UIGradient. The image below shows the linear interpolation of three transparency values:

How the UIGradient Transparency NumberSequence applies transparency to a GuiObject

Note: the envelope values of the NumberSequenceKeypoints are ignored.

Methods

Events