- 🔄 Stateful Animations - Animations that automatically respond to your component's state changes, ensuring UI and state stay perfectly synchronized
- ⛓️ Chainable Animations - Effortlessly build complex animation sequences that flow naturally from one to another
- 🔀 Interruptible Flows - Gracefully handle user interactions by modifying animations mid-flight without jarring visual transitions
- 🧩 Composable System - Create reusable animation components that can be combined in endless ways for consistent motion design
- 🛡️ Memory-Safe Design - Built with React's lifecycle in mind to prevent memory leaks and ensure proper cleanup
Add React-Flow to your wally.toml file:
[dependencies]
ReactFlow = "outofbears/react-flow@0.2.0"Then install with:
wally installSimply clone the repository and include it in your project structure.
Once installed, require React-Flow in your code:
-- For common Roblox setups:
local ReactFlow = require(ReplicatedStorage.Packages.ReactFlow)Creates spring-based physics animations with React bindings. Springs provide natural, bouncy motion that reacts to changes dynamically.
Arguments:
- config: A configuration table with the following properties:
- start: Initial value of the animation (required)
- target: Target value to animate toward (optional)
- speed: Spring stiffness - higher values create faster motion (default: 10)
- damper: Damping ratio - higher values reduce bouncing (default: 1)
Returns:
A binding that updates as the animation progresses, and an update function to modify the animation.
Example:
local useSpring = ReactFlow.useSpring
-- Inside your component:
local position, updatePosition = useSpring({
start = UDim2.fromScale(0, 0), -- Initial Value (required)
target = UDim2.fromScale(0.5, 0.5), -- Target value (optional)
speed = 20,
damper = 0.8,
})
-- Later, update the spring with new parameters:
updatePosition({
target = UDim2.fromScale(0.5, 0.5),
speed = 15,
damper = 0.7,
})
-- Use in your component:
return createElement("Frame", {
Position = position, -- Use binding directly in property
})Creates tween-based animations that follow a specific timing curve. Ideal for animations that need precise timing or easing effects.
Arguments:
- config: A configuration table with the following properties:
- start: Initial value of the animation (required)
- target: Target value to animate toward (optional)
- info: TweenInfo instance (required)
Returns:
A binding that updates as the animation progresses, and an update function to modify the animation.
Example:
local useTween = ReactFlow.useTween
-- Inside your component:
local transparency, updateTransparency = useTween({
start = 1, -- Initial value (required)
target = 0, -- Target value (optional)
-- TweenInfo - controls duration, easing style, and behavior
info = TweenInfo.new(
0.5,
Enum.EasingStyle.Quad,
Enum.EasingDirection.Out,
)
})
-- Later, update the tween:
updateTransparency({
target = 0, -- New target value
-- Optional: update tween configuration
info = TweenInfo.new(0.3, Enum.EasingStyle.Quart, Enum.EasingDirection.InOut),
})
-- Use in your component:
return createElement("Frame", {
BackgroundTransparency = transparency,
})Creates a group of animations that are managed together as a single entity. With useGroupAnimation, you can define multiple animation states by combining the following animation primitives: useAnimation, useSpringAnimation, useSequenceAnimation, and useTweenAnimation. This allows you to define complex animation states and switch between them seamlessly at runtime, providing an elegant way to handle UI state transitions.
Arguments:
- animations: A table mapping state names (e.g., "active", "inactive") to their animation definitions. Each definition can mix multiple animation types.
- defaults: A table providing the default initial values for each animation property.
Returns:
A table of bindings for each animation property, and a function (commonly named playAnimation) that accepts a state name to switch between the defined animation groups.
Example:
local useGroupAnimation = ReactFlow.useGroupAnimation
local useSequenceAnimation = ReactFlow.useSequenceAnimation
local useAnimation = ReactFlow.useAnimation
local Spring = ReactFlow.Spring
local Tween = ReactFlow.Tween
-- Inside your component:
local animations, playAnimation = useGroupAnimation({
enable = useSequenceAnimation({
{
timestamp = 0,
transparency = Tween({target = 0, info = TweenInfo.new(0.2)}),
},
{
timestamp = 0.2,
position = Spring({target = UDim2.fromScale(0.5, 0.5), speed = 20}),
},
}),
disable = useAnimation({
transparency = Tween({target = 1, info = TweenInfo.new(0.1)}),
position = Spring({target = UDim2.fromScale(0.5, 1), speed = 25}),
}),
}, {
transparency = 1
position = UDim2.fromScale(0.5, 1),
})
-- Play the animation with the specificed name:
if enabled then
playAnimation("enable")
else
playAnimation(
"disable",
true -- Optional second argument to play animation immediately
)
end
-- Use the animation bindings in your component:
return createElement("Frame", {
Size = UDim2.new(0, 100, 0, 100),
BackgroundTransparency = animations.transparency,
Position = animations.position,
})TransitionFragment is a component that allows elements to be animated on transition in and out by preserving their presence in a cached fragment during enter and leave operations. When children are added or removed, the component maintains them in the DOM while injecting transition state props, enabling easy enter and exit animations.
The component automatically injects the following props into child elements:
- entering:
boolean- True when the element is being added - exiting:
boolean- True when the element is being removed - onEnterComplete:
() -> ()- Callback when enter animation completes - onExitComplete:
() -> ()- Callback when exit animation completes
This allows child components to respond to transition states and perform appropriate animations while TransitionFragment handles the lifecycle management.
Arguments:
- children: A table containing the elements to be managed with transitions. Elements are automatically cached and transitioned when added or removed.
Returns:
A TransitionFragment component that handles the transition lifecycle and injects transition props into its children.
Example:
local function Entry(props: {
entering: boolean,
exiting: boolean,
onEnterComplete: () -> (),
onExitComplete: () -> ()
})
useEffect(function()
if props.entering then
-- Play enter animation and wait for animation to complete
props.onEnterComplete()
end
end, {props.entering})
useEffect(function()
if props.exiting then
-- Play enter animation and wait for animation to complete
props.onExitComplete()
end
end, {props.exiting})
return ...
end
return createElement(ExampleContainer, {}, {
entries = createElement(TransitionFragment, {}, {
-- list of Entries
})
})React-Flow supports animating the following userdata and native types:
number- Numeric valuesUDim2- 2D positioning (scale and offset)UDim- 1D positioning (scale and offset)Vector2- 2D vectorsVector3- 3D vectorsColor3- RGB color values
CFrame- Position and orientationColorSequenceKeypoint- Color gradient keypointsNumberSequenceKeypoint- Number gradient keypointsBrickColor- Legacy colorsNumberRange- Min/max rangesPhysicalProperties- Physics simulation propertiesRay- Line segmentsRegion3- 3D spatial regionsRegion3int16- Integer-based 3D regions
Round Control Interface
Tower Upgrade Interface
NPC Dialogue
React-Flow was developed by @Nexure with the assistance of @GreenDeno
This project is licensed under the MIT License - see the LICENSE file for details.