🎨 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:

---

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

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

Easing functions

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

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. ↩ ↩²