🎨 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 | | ---------------- | --------- | ---------------------------------------------------------------------------------------------- | | tension[^1] | number | Influences the number of bounces in the animation. Defaults to 170. | | friction[^1] | number | Influences the level of spring in the animation. Defaults to 26. | | mass[^1] | number | Influences the speed of the spring and height of the bounce. Defaults to 1. | | frequency[^2] | number | How quickly the spring responds to changes. | | dampingRatio[^2] | 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. |

[^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.

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

---

<p align="center"> Ripple is licensed under the <a href="LICENSE.md">MIT License</a>. </p> <div align="center">

</div>