Applying UIGradients

Applying UIGradients

5 min

Applying gradients to your interfaces is simple using a UIGradient. You don’t need any image editing skills to add a small sheen to buttons. In this article, you’ll learn how to insert and edit UIGradients.

Your First UIGradient

  1. To begin, you must have some GUI elements in your game already. If you don’t, visit articles/Intro to GUIs for instructions on inserting GUIs. In these steps, we will be editing a TextLabel, but these steps are the same for any other kind of GUI object.

  2. Select the element that you want to apply a gradient to. Click the circle ⊕ button. Type “UIGradient” and select it on the list.

Inserting a UIGradient using the plus button in the Explorer window

  1. You should now have a UIGradient object to edit! Select it to change its appearance in the Properties window. Let’s start by changing the color of this gradient. In the Properties window, click the … next to UIGradient/Color|Color:

The Properties window with the Color property selected

  1. The datatype/ColorSequence editor will appear for the UIGradient/Color property. This will allow you to edit keypoints on the gradient. Try adding a few and changing their color:

The ColorSequence editor for the UIGradient.Color property. A single purple keypoint has been added.

  1. You can also edit the UIGradient/Transparency property in a similar manner. Again, click the … next to Transparency in the properties window:

The Properties window with the Transparency property selected

  1. This opens the datatype/NumberSequence editor. In a similar manner as color, you can add keypoints to change the transparency at certain points along the gradient:

The NumberSequence editor for the UIGradient.Transparency property. The end keypoint was changed to 1, causing the TextLabel to fade out.

  1. Other properties like UIGradient/Rotation|Rotation and UIGradient/Offset|Offset can be edited from the Properties window as well. These change the geometry of the gradient. You can read more about these on their API pages.

How Are Gradients Applied?

It’s important to know that gradients are applied though multiplication. This means that if a gradient is white, it uses the original color of the GUI element it is applied to. Conversely, if the gradient is black, the result color is always black. Knowing this, following the following tips could prove useful:

  • If you are using a UIGradient for light or shadow effects, you should use black, white and grey colors on the gradient. Use the GUI element’s color properties as a base color.
  • Multiplication also applies to transparency. A gradient with 50% transparency applied to an object that is 50% transparent is just as transparent as an object that is 75% transparent with no gradient.

How Does Gradient Geometry Work?

When you set the UIGradient/Rotation|Rotation or UIGradient/Offset|Offset property, there’s a couple things going on under the hood. Two invisible control points are used to render the gradient, and their positions are changed when you manipulate these properties. See the animations below for a visual explanation of how these properties change the control points. The red point is the starting point, and the blue point is the end point.

UIGradient Offset UIGradient Rotation

Animating UIGradient

Using TweenService, it is possible to animate the properties of a UIGradient. In this example, a TextLabel contains a UIGradient with the UIGradient/Transparency|Transparency property set. Its UIGradient/Offset|Offset property is tweened from -1 to 1.

local TweenService = game:GetService("TweenService")
local uiGradent = script.Parent

-- TweenInfo.new(time, EasingStyle, EasingDirection, repeatCount, reverses, delayTime)
local tweenInfo = TweenInfo.new(1, Enum.EasingStyle.Linear, Enum.EasingDirection.In, -1, false, 0)

-- The properties to tween (Offset from -1 to 1)
uiGradent.Offset = Vector2.new(-1, 0)
local goals = {
	Offset = Vector2.new(1, 0);

-- Create and play the tween
-- Since TweenInfo.repeatCount is negative, it will loop indefinitely
local tween = TweenService:Create(uiGradent, tweenInfo, goals)