- 🔄 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.1.6"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,
})DynamicList is a component that automatically tracks and manages the addition, removal, and updating of child elements based on changes to its children prop. It ensures that its internal state stays synchronized with the provided children, updating dynamically when the children list changes.
Key behavior:
- Child management: The component will add new children or update existing ones based on changes in the
childrenprop. - Removing children: When a child element is removed, it must call its
destroyhandler to clean up. Theremovehandler will notifyDynamicListthat the child has been removed by the parent, triggering the necessary state updates.
This makes it easy to create lists where child elements can be added, updated, or removed without requiring manual state management.
Arguments:
- children: A table containing the elements to be managed by the list. The elements are automatically synchronized with the list’s internal state.
Returns:
A DynamicList component that handles the automatic synchronization of its children, ensuring they stay in sync with the latest state.
Example:
local items, updateItems = useState({ item1 = "hello world!" })
useEffect(function()
local thread = task.delay(5, function()
updateItems(function(state)
local newState = table.clone(state)
newState.item1 = nil
return newState
end)
end)
return function()
task.cancel(thread)
end
end, {})
return createElement(DynamicList, {}, {
item1 = items.items1 and createElement("TextLabel", {
Text = items.item1,
})
})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.