GradientKit — A standalone UIGradient effect library

GradientKit is a small, dependency-free Roblox module for creating, reusing, and animating UIGradient objects. It provides built-in effects for buttons, cards, titles, backgrounds, and other Roblox UI without requiring a UI framework or service container.

GradientKit can work with gradients authored in Studio or create them automatically. Each active effect owns its tweens and connections, returns a controller for direct control, and restores the gradient's original state when it stops.

Quick example

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local GradientKit = require(ReplicatedStorage.Packages.GradientKit)

local controller = GradientKit.Apply(script.Parent.Button, "Shine", {
	Duration = 0.8,
	Delay = 2,
})

-- Stop the effect whenever the owning UI is torn down.
controller:Stop()

Apply reuses the first UIGradient under the target or creates one when necessary.

✨ Features

• Fully standalone and dependency-free
• Works with existing Studio-authored UIGradient objects
• Creates gradients automatically when applying an effect to a GuiObject
• One active GradientKit effect per UIGradient
• Automatically stops the previous effect on the same gradient
• Built-in shine, hover, rainbow, scrolling, rotation, sweep, press, and palette effects
• Typed public APIs and exported Luau options
• Configurable tween timing, easing, colors, offsets, and rotation
• Interaction targets for hover and press effects
• Restores original gradient properties when stopped by default
• Optional cleanup of gradients created by Apply
• Cleans up when a gradient is destroyed
• Supports friendly effect aliases such as Flow and Activated

📖 Basic usage

Copy GradientKit into your project and require it from a client script. UI interaction and animation should normally run on the client.

Applying an effect

local controller = GradientKit.Apply(button, "Shine")

if controller:IsRunning() then
	print("The gradient effect is active")
end

The target must be a GuiObject. Apply uses an existing child UIGradient when one is available; otherwise it creates a gradient named Gradient.

Using an existing UIGradient

Create and style the gradient yourself in Studio, then start an effect on it:

local button = script.Parent.Button
local gradient = button.UIGradient

local controller = GradientKit.Start(gradient, "Hover", {
	Duration = 0.35,
})

For interactive effects, Start uses the gradient's parent as the interaction target when that parent is a GuiObject. Override it when a different object should receive input:

GradientKit.Start(label.UIGradient, "Hover", {
	InteractionTarget = button,
})

Creating a gradient

local gradient = GradientKit.Create(frame, {
	Name = "BackgroundGradient",
	Colors = {
		Color3.fromRGB(255, 90, 150),
		Color3.fromRGB(100, 110, 255),
	},
	Rotation = 45,
})

Use either Colors for a palette or Color for a complete ColorSequence.

Targeting one of several gradients

When a GuiObject contains multiple gradients, pass GradientName to Apply:

GradientKit.Apply(frame, "Rotate", {
	GradientName = "BackgroundGradient",
})

Included effects

• Shine — applies a bright center band and sweeps it across the UI.
• Hover — moves a gradient into view on hover and alternates its exit direction.
• HoverStay — slides continuously while hovered and pauses when the pointer leaves.
• Rainbow — generates an HSV rainbow palette and cycles it across the gradient.
• Scroll / Flow — continuously moves the current gradient from one offset to another.
• Rotate — continuously rotates the gradient while preserving its colors and offset.
• Sweep — periodically sweeps the current gradient without imposing a color style.
• Pressed / Activated — moves and optionally rotates the gradient while pressed.
• ColorCycle — continuously cycles through a developer-defined palette of three or more colors.

Effect examples

Shine

GradientKit.Apply(button, "Shine", {
	BaseColor = Color3.fromRGB(255, 80, 160),
	ShineColor = Color3.fromRGB(255, 235, 250),
	Duration = 0.8,
	Delay = 2,
	ShinesPerBurst = 2,
	Rotation = 45,
})

Hover

GradientKit.Apply(button, "Hover", {
	Colors = {
		Color3.fromRGB(255, 220, 80),
		Color3.fromRGB(80, 255, 140),
		Color3.fromRGB(80, 170, 255),
	},
	Duration = 0.4,
})

HoverStay

GradientKit.Apply(button, "HoverStay", {
	Colors = {
		Color3.fromRGB(255, 100, 155),
		Color3.fromRGB(95, 180, 255),
	},
	Duration = 2.5,
})

Rainbow

GradientKit.Apply(title, "Rainbow", {
	Duration = 1,
	Steps = 18,
	Saturation = 1,
	Value = 1,
})

Providing at least three colors through Colors makes Rainbow use that palette instead of generating HSV colors.

Scroll / Flow

GradientKit.Apply(frame, "Flow", {
	StartOffset = Vector2.new(-1, 0),
	EndOffset = Vector2.new(1, 0),
	Duration = 3,
	Rotation = 20,
})

Rotate

GradientKit.Apply(frame, "Rotate", {
	Duration = 5,
	Clockwise = true,
	Degrees = 360,
})

Set Clockwise = false for counter-clockwise rotation.

Sweep

GradientKit.Apply(card, "Sweep", {
	Duration = 0.75,
	Delay = 2.25,
	StartOffset = Vector2.new(-1, 0),
	EndOffset = Vector2.new(1, 0),
})

Pressed / Activated

GradientKit.Apply(button, "Pressed", {
	Duration = 0.12,
	RestOffset = Vector2.new(0, 0),
	PressedOffset = Vector2.new(0.1, 0),
})

The gradient can also rotate slightly during the press:

GradientKit.Apply(button, "Activated", {
	PressedOffset = Vector2.new(0.08, 0),
	RestRotation = 0,
	PressedRotation = 8,
})

ColorCycle

GradientKit.Apply(title, "ColorCycle", {
	Colors = {
		Color3.fromRGB(255, 90, 130),
		Color3.fromRGB(255, 200, 80),
		Color3.fromRGB(90, 220, 255),
		Color3.fromRGB(165, 100, 255),
	},
	Duration = 1.2,
})

ColorCycle requires at least three colors.

Preserving your own gradient style

Some effects have built-in visual styles. Shine creates a base/shine color sequence and Hover provides a default palette. Disable those defaults when the gradient's existing colors should remain in control:

GradientKit.Start(gradient, "Shine", {
	UseDefaultStyle = false,
})

SetupDefaults is accepted as a backward-compatible alias for UseDefaultStyle.

Scroll, Rotate, Sweep, and Pressed preserve the existing gradient style unless colors are explicitly supplied.

Stopping effects

Stop with the controller

local controller = GradientKit.Apply(button, "Shine")
controller:Stop()

Stop with the gradient or controller

GradientKit.Stop(button.UIGradient)
GradientKit.Stop(controller)

Stop every active effect

local stoppedCount = GradientKit.StopAll()

Stop returns whether an active effect was found. StopAll returns the number of controllers that were stopped. Calling Stop with no target also stops all active effects.

⚙️ API

GradientKit.Create(guiObject, properties?) -> UIGradient

Creates and parents a new UIGradient under guiObject.

Supported properties are Name, Enabled, Color, Colors, Transparency, Offset, and Rotation.

GradientKit.Apply(guiObject, effectName, options?) -> Controller

Applies an effect directly to a GuiObject, reusing a matching existing gradient or creating one when necessary. GradientName selects a specific gradient by name.

GradientKit.Start(gradient, effectName, options?) -> Controller

Starts an effect on a specific UIGradient. Starting another effect on the same gradient automatically stops the previous controller first.

GradientKit.Stop(target?) -> boolean

Stops an effect using its controller or UIGradient. With no target, all active effects are stopped and the return value indicates whether any were active.

GradientKit.StopAll() -> number

Stops all active effects and returns the number stopped.

GradientKit.IsActive(gradient) -> boolean

Returns whether the gradient currently has an active GradientKit controller.

GradientKit.GetController(gradient) -> Controller?

Returns the active controller for the gradient, if one exists.

Controller methods

controller:Stop() -> boolean
controller:IsRunning() -> boolean

Complete configuration reference

Gradient properties (GradientKit.Create)

Effect options

All options are optional. Unsupported options are ignored by effects that do not use them.

Effect aliases

GradientKit ignores spaces, underscores, hyphens, and capitalization when resolving effect names.

Shine / Shimmer
HoverStay / Hover Stay / hover-stay
Rainbow / RGB
Scroll / Flow
Rotate / Spin
Pressed / Press / Activated / Activate / Click
ColorCycle / ColourCycle / Cycle / ColorShift

📝 Notes

• GradientKit is intended for client-side UI.
• Hover, HoverStay, and Pressed require an interaction target. Apply supplies the target automatically; Start resolves it from the gradient's parent when possible.
• Stopping an effect restores Enabled, Color, Transparency, Offset, and Rotation from before the effect started unless RestoreOnStop = false.
• DestroyOnStop only destroys gradients created by GradientKit.Apply; it never destroys a gradient supplied by the developer.
• Destroying a UIGradient automatically removes its active controller and tracked connections.
• Effects are self-contained and use Roblox TweenService plus lightweight task loops instead of a permanent global frame-by-frame scheduler.

🛠️ Installation

Place the package somewhere accessible to your client UI code, for example:

ReplicatedStorage
└── Packages
    └── GradientKit

Then require it from a LocalScript:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local GradientKit = require(ReplicatedStorage.Packages.GradientKit)

GradientKit does not depend on this exact folder structure; it is only a suggested organization.

License

This project is released under the MIT License.

See LICENSE for details.

made with ❤️ by biotoxin495