🎨 Ripple

Ripple is a simple, lightweight, and easy-to-use Roblox library for creating simple transitions and animations. It is inspired by react-spring and aims to provide an imperative API for general use.

Installation

Ripple is available on NPM and can be installed with the following commands:

npm install @rbxts/ripple
yarn add @rbxts/ripple
pnpm add @rbxts/ripple

# Wally
Ripple = "littensy/ripple@version"

Reference

Supported types

The following data types are supported for animation:

Data type	Converted type
number	[number]
vector	[vector]
Vector2	[vector]
Vector3	[vector]
Color3	[vector] (Oklab)
UDim	[vector]
UDim2	[vector, number]
CFrame	[vector, vector, vector, vector]
Rect	[vector, number]
Map<any, number | vector>	Map<any, number | vector>

---

createSpring(initialValue, options)

createSpring creates a spring object starting at the given value.

local spring = createSpring(0, {
	tension = 170,
	friction = 26,
	start = true,
})

spring:setGoal(1)
spring:onChange(print) --> number, deltaTime

Try the react-spring visualizer →

Parameters

• initialValue: The value that the spring should start with.
• optional options: The physical properties of the spring.

Options

Option	Type	Description
tension1	number	Influences the number of bounces in the animation. Defaults to 170.
friction1	number	Influences the level of spring in the animation. Defaults to 26.
mass1	number	Influences the speed of the spring and height of the bounce. Defaults to 1.
frequency2	number	How quickly the spring responds to changes.
dampingRatio2	number	Dictates how the spring slows down.
precision	number	The distance to the goal before the spring is considered idle. Defaults to 0.001.
restVelocity	number	The smallest velocity before the spring is considered idle. Derived from precision by default.
position	T	Set the position of the spring.
velocity	T	Set the velocity of the spring.
impulse	T	Add to the velocity of the spring.
start	boolean	Connect to Heartbeat while animating. Defaults to false.

Returns

createSpring returns a spring object.

---

createTween(initialValue, options)

createTween creates a tween object starting at the given value.

local tween = createTween(0, {
	easing = "quadOut",
	duration = 1,
	start = true,
})

tween:setGoal(1)
tween:onChange(print) --> number, deltaTime

Parameters

• initialValue: The value that the spring should start with.
• optional options: The properties of the tween.

Options

Option	Type	Description
easing	Easing	The easing function to use for animation.
duration	number	Duration of one repetition of the tween, in seconds.
repeats	number	Number of times the tween repeats.
reverses	boolean	Reverse directions when repeating.
position	T	Continue the rest of the tween from this position.
start	boolean	Connect to Heartbeat while animating. Defaults to false.

Easing functions

"linear"	"instant"	"smoothstep"
"sineIn"	"sineOut"	"sineInOut"
"backIn"	"backOut"	"backInOut"
"quadIn"	"quadOut"	"quadInOut"
"quartIn"	"quartOut"	"quartInOut"
"quintIn"	"quintOut"	"quintInOut"
"bounceIn"	"bounceOut"	"bounceInOut"
"elasticIn"	"elasticOut"	"elasticInOut"
"expoIn"	"expoOut"	"expoInOut"
"circIn"	"circOut"	"circInOut"
"cubicIn"	"cubicOut"	"cubicInOut"

See examples of easing functions →

Returns

createTween returns a tween object.

---

createMotion(initialValue, options)

createMotion creates an animation that switches between a spring and a tween.

local motion = createMotion(0, {
	spring = { tension = 170, friction = 26 },
	tween = { easing = "quadOut", duration = 1 },
	start = true,
})

motion:onChange(print) --> number, deltaTime
motion:tween(1)
task.wait(1)
motion:spring(0)

Warning

This creates both a spring and a tween object, which can be wasteful if your animation uses only one or the other.

Use createSpring or createTween if you do not need to switch animation types.

Parameters

• initialValue: The value that the spring and tween should start with.
• optional options: The properties of the spring or tween.

Options

Option	Type	Description
spring	SpringOptions<T>	The spring options to use for spring animations.
tween	TweenOptions<T>	The tween options to use for tween animations.
start	boolean	Connect to Heartbeat while animating. Defaults to false.

Returns

createMotion returns a motion object that controls a spring and a tween.

---

Examples

React Button

local function Button()
	local binding, spring = useSpring(0, config.stiff)

	return React.createElement("TextButton", {
		[React.Change.GuiState] = function(rbx: TextButton)
			if rbx.GuiState == Enum.GuiState.Hover then
				spring:setGoal(20)
			elseif rbx.GuiState == Enum.GuiState.Press then
				spring:setGoal(-20, { impulse = -100 })
			else
				spring:setGoal(0)
			end
		end,
		Text = "Button",
		Size = binding:map(function(offset)
			return UDim2.fromOffset(100 + offset, 50 + offset)
		end),
	})
end

Vide Button

local function Button()
	local getValue, spring = useSpring(0, config.stiff)

	return create "TextButton" {
		Text = "Button",
		Size = function()
			return UDim2.fromOffset(100 + getValue(), 50 + getValue())
		end,

		changed("GuiState", function(state: Enum.GuiState)
			if state == Enum.GuiState.Hover then
				spring:setGoal(20)
			elseif state == Enum.GuiState.Press then
				spring:setGoal(-20, { impulse = -100 })
			else
				spring:setGoal(0)
			end
		end),
	}
end

---

Ripple is licensed under the MIT License.

Footnotes

1. Tension, friction, and mass are not compatible with frequency or damping ratio. ↩ ↩² ↩³

2. Frequency and damping ratio are not compatible with tension, friction, or mass. ↩ ↩²