### Starting Animations with Configs

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Shows how to specify animation configurations when starting an animation using the imperative API.

```APIDOC
## Starting Animations with Configs

### Description
This example demonstrates how to apply specific animation configurations (like mass, tension, friction) when initiating an animation using the `api.start` method.

### Method
`api.start(props, config)`

### Example
```lua
api.start({
    position = UDim2.fromScale(0.5, 0.5),
    rotation = 0,
    config = { mass = 10, tension = 100, friction = 50 },
})
```
```

--------------------------------

### RoactSpring Loop Prop Examples

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Demonstrates different ways to configure the 'loop' prop for animations.

```APIDOC
## RoactSpring Loop Prop

### Description
Customizes animation looping behavior.

### Method
`useSpring`

### Parameters
#### Request Body
- **loop** (boolean) - Use `true` to repeat an animation indefinitely.
- **loop** (function) - A function called after each loop. Return `true` to continue looping, or `false` to stop.
- **loop** (table) - Define a `loop` table to customize the loop animation separately. It may contain any of the `useSpring` props.

### Request Examples

**Boolean Loop:**
```lua
-- Transparency repeatedly animates from 0 to 1
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    to = { transparency = 1 },
    loop = true,
})
```

**Function Loop:**
```lua
-- Transparency animates from 0 to 1 three times
local count = React.useRef(0)
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    to = { transparency = 1 },
    loop = function()
        count += 1
        return 3 > count.value
    end,
})
```

**Table Loop:**
```lua
-- Transparency repeatedly animates from 0 to 1 with 1 second delays
local count = React.useRef(0)
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    to = { transparency = 1 },
    loop = { delay = 1, reset = true },
})
```

**Inherited Props with Loop:**
```lua
-- The loop doesn't run more than once
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    loop = { transparency = 1 },
})

-- To loop the animation, try adding `reset = true` to the loop prop
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    loop = {
        transparency = 1,
        reset = true,
    },
})

-- Alternatively, add `from = { transparency: 1 }` to the loop object
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    loop = {
        transparency = 1,
        from = { transparency = 1 },
    },
})

-- Override inherited config
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    loop = {
        transparency = 1,
        config = { friction = 5 },
    },
})
```
```

--------------------------------

### Start Animation with Spring Configuration

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/configs.md

Use this to start an animation with specific spring physics properties like mass, tension, and friction.

```lua
api.start({
    position = UDim2.fromScale(0.5, 0.5),
    rotation = 0,
    config = { mass: 10, tension: 100, friction: 50 },
})
```

--------------------------------

### Roact-Spring Controller Class Example

Source: https://context7.com/chriscerie/roact-spring/llms.txt

Demonstrates using the Controller class for spring animations in a React class component. Initialize the controller with styles and an API, then use the API to start animations.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

local Example = React.Component:extend("Example")

function Example:init()
    self.styles, self.api = RoactSpring.Controller.new({
        size = UDim2.fromOffset(150, 150),
        position = UDim2.fromScale(0.5, 0.5),
        rotation = 0,
        transparency = 0,
    })
end

function Example:render()
    return React.createElement("TextButton", {
        Position = self.styles.position,
        Size = self.styles.size,
        Rotation = self.styles.rotation,
        Transparency = self.styles.transparency,
        Text = "Click me!",

        [React.Event.Activated] = function()
            self.api:start({
                size = UDim2.fromOffset(200, 200),
                rotation = 45,
                config = { tension = 100, friction = 10 },
            }):andThen(function()
                -- Chain another animation after the first completes
                self.api:start({
                    size = UDim2.fromOffset(150, 150),
                    rotation = 0,
                })
            end)
        end,
    })
end
```

--------------------------------

### Starting Animation with Configs

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Initiates an animation with specific configuration options for mass, tension, and friction. This allows fine-tuning the animation's behavior.

```lua
api.start({
    position = UDim2.fromScale(0.5, 0.5),
    rotation = 0,
    config = { mass = 10, tension = 100, friction = 50 },
})
```

--------------------------------

### Imperative useSpring Hook Example

Source: https://context7.com/chriscerie/roact-spring/llms.txt

Control animations programmatically using the returned API's `start` method. The `andThen` callback executes after the animation completes.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

-- Imperative usage: control animations with api.start()
local function ImperativeExample()
    local styles, api = RoactSpring.useSpring(function()
        return {
            position = UDim2.fromScale(0.5, 0.5),
            rotation = 0,
            transparency = 1,
        }
    end)

    return React.createElement("TextButton", {
        Position = styles.position,
        Rotation = styles.rotation,
        Transparency = styles.transparency,
        Size = UDim2.fromScale(0.2, 0.2),
        [React.Event.Activated] = function()
            api.start({
                position = UDim2.fromScale(0.5, 0.8),
                rotation = 45,
                transparency = 0,
                config = { mass = 1, tension = 170, friction = 26 },
            }):andThen(function()
                print("Animation finished!")
            end)
        end,
    })
end
```

--------------------------------

### Roact-Spring Velocity Configuration

Source: https://context7.com/chriscerie/roact-spring/llms.txt

Demonstrates setting an initial velocity for a spring animation using `useSpring`. This allows for directional initial movement, affecting how the animation starts.

```lua
local styles = RoactSpring.useSpring({
    position = UDim2.fromScale(0.5, 0.5),
    config = {
        velocity = { -0.01, 0, -0.01, 0 }, -- Initial velocity towards top-left
    },
})
```

--------------------------------

### Imperative Start with Reset

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Starts an animation imperatively, explicitly setting the 'from' values and controlling the reset behavior. The first call starts from 0, the second ignores 'from' and starts from the current value.

```lua
local styles, api = RoactSpring.useSpring(function()
    return { transparency = 0.5 }
end)

-- The spring will start from 0
api.start({
    from = { transparency = 0 },
    to = { transparency = 1 },
})

-- The spring will ignore `from` and start from its current position
api.start({
    reset = false,
    from = { transparency = 0 },
    to = { transparency = 1 },
})
```

--------------------------------

### Individual delay for each spring

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useTrail.md

Pass a `delay` property to each spring individually to control their staggered start times. This example makes each spring start 0.1 seconds later than the previous one.

```lua
-- The first spring will start 0.1 seconds after the previous one, the second 0.2 seconds, and so on
local springs, api = RoactSpring.useTrail(length, function(index)
    return {
        transparency = items[index].transparency,
        delay = index * 0.1,
    }
end)
```

--------------------------------

### Imperative useTrail with Custom Delays

Source: https://context7.com/chriscerie/roact-spring/llms.txt

This imperative example demonstrates `useTrail` with custom delays applied to each spring. It's useful for fine-grained control over the timing of sequential animations.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

local buttonData = {
    { text = "LOREM", color = Color3.fromRGB(240, 215, 72) },
    { text = "IPSUM", color = Color3.fromRGB(241, 108, 230) },
    { text = "DOLOR", color = Color3.fromRGB(138, 223, 240) },
    { text = "SIT", color = Color3.fromRGB(177, 223, 233) },
}

-- Imperative with custom delays per spring
local function CustomDelayTrail()
    local springs, api = RoactSpring.useTrail(#buttonData, function(index) 
        return {
            transparency = 1,
            position = UDim2.fromScale(0.2, 0.1 * index),
            delay = index * 0.15, -- Custom delay: 0.15s between each
        }
    end)

    React.useEffect(function()
        api.start(function(index) 
            return {
                transparency = 0,
                position = UDim2.fromScale(0.5, 0.1 * index),
            }
        end)
    end, {}) 

    -- Render springs...
end
```

--------------------------------

### Install roact-spring with Wally (react-lua)

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/intro.md

Add the latest version of roact-spring to your wally.toml for react-lua projects. Ensure you are using a version compatible with react-lua's scope.

```toml
ReactSpring = "chriscerie/react-spring@<version>"
```

--------------------------------

### Loop Animation Inheriting Props

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Demonstrates how loop properties can inherit from the main spring configuration. This example shows a loop that only runs once due to inherited props.

```lua
-- The loop doesn't run more than once
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    loop = { transparency = 1 },
})
```

--------------------------------

### Declarative useSpring Hook Example

Source: https://context7.com/chriscerie/roact-spring/llms.txt

Use this hook for animations that update automatically when state changes. Ensure Roact and RoactSpring are required.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

-- Declarative usage: animation updates when toggle state changes
local function DeclarativeExample() 
    local toggle, setToggle = React.useState(false)
    local styles = RoactSpring.useSpring({
        from = { transparency = 0, position = UDim2.fromScale(0.3, 0.5) },
        to = {
            transparency = if toggle then 1 else 0,
            position = if toggle then UDim2.fromScale(0.7, 0.5) else UDim2.fromScale(0.3, 0.5),
        },
        config = if toggle then { tension = 200 } else { tension = 50 },
    }, { toggle })

    return React.createElement("TextButton", {
        Position = styles.position,
        Transparency = styles.transparency,
        Size = UDim2.fromScale(0.2, 0.2),
        [React.Event.Activated] = function()
            setToggle(function(prevState)
                return not prevState
            end)
        end,
    })
end
```

--------------------------------

### Install roact-spring with npm (roblox-ts)

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/intro.md

Install roact-spring for roblox-ts projects using npm. This command adds the package to your project's dependencies.

```bash
npm i @rbxts/roact-spring
```

--------------------------------

### Loop Animation with Reset and Transparency

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Configures a looping animation for transparency, ensuring it resets on each loop iteration. This example animates transparency from 0 to 1.

```lua
-- Transparency repeatedly animates from 0 to 1
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    loop = {
        transparency = 1,
        reset = true,
    },
})
```

--------------------------------

### Install roact-spring with Wally (legacy Roact)

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/intro.md

Add the latest version of roact-spring to your wally.toml for legacy Roact projects. Ensure you are using a version compatible with legacy Roact's scope.

```toml
RoactSpring = "chriscerie/roact-spring@<version>"
```

--------------------------------

### Imperative Animation with useSpring API

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useSpring.md

Preferred for more control, this method returns an API to start and stop animations. Animations do not run automatically on mount or re-render.

```lua
local styles, api = RoactSpring.useSpring(function()
    return { transparency = 0 }
end)

-- Update spring with new props
api.start({ transparency = if toggle then 1 else 0 })
-- Stop animation
api.stop()
```

--------------------------------

### Loop Animation with Explicit From Value

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Sets an explicit 'from' value within the loop configuration to control the starting point of each loop iteration. This example animates transparency from 1 to 1, effectively restarting.

```lua
-- Transparency repeatedly animates from 0 to 1
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    loop = {
        transparency = 1,
        from = { transparency = 1 },
    },
})
```

--------------------------------

### Loop Animation with Boolean

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Enables continuous looping of an animation when set to true. This example animates transparency from 0 to 1 repeatedly.

```lua
-- Transparency repeatedly animates from 0 to 1
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    to = { transparency = 1 },
    loop = true,
})
```

--------------------------------

### Basic Spring Animation in Class Component

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Getting Started.md

Use `Controller` for class components to manage animations. This example animates the transparency of a TextButton when activated.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

function App:init()
    self.styles, self.api = RoactSpring.Controller.new({
        transparency = 1 
    })
end

-- When button is pressed, animate transparency to 0
function App:render()
    return React.CreateElement("TextButton", {
        Size = UDim2.fromScale(0.5, 0.5),
        Transparency = self.styles.transparency,
        [React.Event.Activated] = function()
            self.api:start({ transparency = 0 })
        end,
    })
end
```

--------------------------------

### Basic Spring Animation in Function Component (React-Lua)

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Getting Started.md

A minimal example of `useSpring` for function components using React-Lua, focusing on the hook's basic structure.

```lua
local function App(_)
    local styles, api = RoactSpring.useSpring(function()
        return { transparency = 1 }
    end)
end
```

--------------------------------

### Loop Animation with Table Configuration

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Customizes loop behavior using a table, allowing specific props like delay or reset to be applied per loop iteration. This example adds a 1-second delay between loops.

```lua
-- Transparency repeatedly animates from 0 to 1 with 1 second delays
local count = React.useRef(0)
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    to = { transparency = 1 },
    loop = { delay = 1, reset = true },
})
```

--------------------------------

### Apply Styles to Components with Springs

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useSprings.md

Render components using the animated values provided by the 'springs' array. This example shows how to apply animated 'Position' to 'Frame' elements.

```lua
local contents = {}
for i = 1, 4 do
    contents[i] = React.createElement("Frame", {
        Position = springs[i].position,
        Size = UDim2.fromScale(0.3, 0.3),
    })
end
return contents
```

--------------------------------

### Imperative Animation with useSpring and API

Source: https://github.com/chriscerie/roact-spring/blob/main/README.md

Use the useSpring hook for imperative animations. It returns animated styles and an API object to control animations. The start method can be used to animate properties with specified configurations.

```lua
local styles, api = RoactSpring.useSpring(function()
    return {
        position = UDim2.fromScale(0.3, 0.3),
        rotation = 0,
    }
end)

-- Later
api.start({
    position = UDim2.fromScale(0.5, 0.5),
    rotation = 45,
    config = { tension = 170, friction = 26 },
})
```

--------------------------------

### Loop Animation with Function

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Allows custom loop control by providing a function that returns true to continue looping or false to stop. This example loops three times.

```lua
-- Transparency animates from 0 to 1 three times
local count = React.useRef(0)
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    to = { transparency = 1 },
    loop = function()
        count += 1
        return 3 > count.value
    end,
})
```

--------------------------------

### Declarative Update with Explicit Reset

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Demonstrates a declarative animation update where 'reset' is explicitly set to true, ensuring the animation always starts from scratch from the 'from' value on each toggle.

```lua
-- The spring will always start from scratch from 0.2
local styles = RoactSpring.useSpring({
    reset = true,
    from = { transparency = 0.2 },
    to = { transparency = if toggle then 0 else 1 },
}, { toggle })
```

--------------------------------

### Roact Spring API Methods

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Defines the available methods on the imperative API object, including `start`, `stop`, and `pause`, for controlling animations. The `api` table's identity is stable across re-renders.

```lua
local api = {
    -- Start your animation optionally giving new props to merge 
    start: (props) => Promise,
    -- Cancel some or all animations depending on the keys passed, no keys will cancel all. 
    stop: (keys) => void,
    -- Pause some or all animations depending on the keys passed, no keys will pause all. 
    pause: (keys) => void,
}
```

--------------------------------

### Basic Spring Animation in Function Component (React-Lua)

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Getting Started.md

Use `useSpring` for function components with React-Lua to animate properties. This example animates the transparency of a TextButton when pressed.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

-- When button is pressed, animate transparency to 0
local function App(_)
    local styles, api = RoactSpring.useSpring(function()
        return { transparency = 1 }
    end)

    return React.CreateElement("TextButton", {
        Size = UDim2.fromScale(0.5, 0.5),
        Transparency = styles.transparency,
        [React.Event.Activated] = function()
            api.start({ transparency = 0 })
        end,
    })
end
```

--------------------------------

### Declarative Update with Default Reset

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Shows a declarative animation update where 'reset' is false by default, meaning it won't restart from 'from' on subsequent toggles. The animation starts from 0.2 on mount.

```lua
-- The spring will start from 0.2 on mount and ignore `from` on future updates
local styles = RoactSpring.useSpring({
    from = { transparency = 0.2 },
    to = { transparency = if toggle then 0 else 1 },
}, { toggle })
```

--------------------------------

### Configuring delay for staggered springs

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useTrail.md

Override the default delay between springs by passing a `delay` property. This example sets a fixed delay of 0.2 seconds for each spring after the previous one.

```lua
-- Now each spring will start 0.2 seconds after the previous one
local springs, api = RoactSpring.useTrail(length, function(index)
    return {
        transparency = items[index].transparency,
        delay = 0.2,
    }
end)
```

--------------------------------

### Declarative useTrail for Staggered List Animation

Source: https://context7.com/chriscerie/roact-spring/llms.txt

This declarative pattern uses `useTrail` to animate a list of elements with a sequential, staggered effect. Each element's animation starts after the previous one, creating a cascading reveal.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

local buttonData = {
    { text = "LOREM", color = Color3.fromRGB(240, 215, 72) },
    { text = "IPSUM", color = Color3.fromRGB(241, 108, 230) },
    { text = "DOLOR", color = Color3.fromRGB(138, 223, 240) },
    { text = "SIT", color = Color3.fromRGB(177, 223, 233) },
}

local function StaggeredList()
    local toggle, setToggle = React.useState(false)

    local springProps = {}
    for i in ipairs(buttonData) do
        table.insert(springProps, {
            position = UDim2.fromScale(if toggle then 0.45 else 0.35, 0.05 + i * 0.15),
            transparency = if toggle then 0 else 1,
            config = { damping = 1, frequency = 0.3 },
        })
    end
    local springs = RoactSpring.useTrail(#buttonData, springProps)

    local buttons = {}
    for index, data in ipairs(buttonData) do
        buttons[index] = React.createElement("TextButton", {
            Position = springs[index].position,
            Transparency = springs[index].transparency,
            Size = UDim2.fromScale(0.3, 0.1),
            BackgroundColor3 = data.color,
            Text = data.text,
            [React.Event.Activated] = function()
                setToggle(function(prev) return not prev end)
            end,
        })
    end

    return React.createElement("Frame", { Size = UDim2.fromScale(1, 1) }, buttons)
end
```

--------------------------------

### Roact-Spring Custom Spring Configuration

Source: https://context7.com/chriscerie/roact-spring/llms.txt

Illustrates a custom spring configuration using `useSpring`, detailing various physics properties like mass, tension, friction, and clamp. Also shows how to use duration-based easing.

```lua
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

-- Custom spring configuration with all options
local styles, api = RoactSpring.useSpring(function()
    return {
        position = UDim2.fromScale(0.5, 0.5),
        config = {
            mass = 1,           -- Spring mass (default: 1)
            tension = 170,      -- Spring energetic load (default: 170)
            friction = 26,      -- Spring resistance (default: 26)
            clamp = false,      -- Stop spring at boundaries (default: false)
            velocity = 0,       -- Initial velocity (default: 0)
            bounce = 0.25,      -- Bounce on overshoot when > 0
            precision = 0.01,   -- How close to end before "done"
        },
    }
end)

-- Duration-based animation with easing (instead of spring physics)
api.start({
    position = UDim2.fromScale(0.8, 0.8),
    config = {
        duration = 1,                           -- 1 second duration
        easing = RoactSpring.easings.easeOutBounce, -- Bounce easing
    },
})
```

--------------------------------

### Declarative useTrail with from/to

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useTrail.md

Use this to set initial values for animations that run on mount. The `from` property sets the initial state, and `to` defines the target state.

```lua
local springProps = {}
local length = #items
for index, item in ipairs(items) do
    table.insert(springProps, {
        from = { transparency = item.transparency },
        to = { transparency = if toggles[i] then 1 else 0 },
    })
end
local springs = RoactSpring.useTrail(length, springProps)
```

--------------------------------

### Configure Spring with useSpring

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/configs.md

Provide a default `config` table to `useSpring` to adjust spring settings like mass, tension, and friction.

```lua
local styles, api = RoactSpring.useSpring(function()
    return {
        from = {
            position = UDim2.fromScale(0.5, 0.5),
            rotation = 0,
        },
        config = { mass = 10, tension = 100, friction = 50 },
    }
end)
```

--------------------------------

### Roact-Spring Presets

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/configs.md

Utilize predefined generic presets for common spring configurations. These presets offer quick access to balanced spring physics.

```lua
RoactSpring.config = {
    default = { mass: 1, tension: 170, friction: 26 },
    gentle = { mass: 1, tension: 120, friction: 14 },
    wobbly = { mass: 1, tension: 180, friction: 12 },
    stiff = { mass: 1, tension: 210, friction: 20 },
    slow = { mass: 1, tension: 280, friction: 60 },
    molasses = { mass: 1, tension: 280, friction: 120 },
}
```

--------------------------------

### Basic Spring Animation in Function Component (Legacy Roact + Hooks)

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Getting Started.md

Demonstrates `useSpring` for function components with legacy Roact and roact-hooks. Requires passing the `hooks` table to the hook.

```lua
local function App(_, hooks)
    local styles, api = RoactSpring.useSpring(hooks, function()
        return { transparency = 1 }
    end)
end
```

--------------------------------

### Roact-Spring Preset Configurations

Source: https://context7.com/chriscerie/roact-spring/llms.txt

Shows available preset spring configurations for common animation styles. These presets simplify the process of achieving specific animation behaviors.

```lua
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

-- Available preset configurations
local presets = {
    default = { mass = 1, tension = 170, friction = 26 },
    gentle = { mass = 1, tension = 120, friction = 14 },
    wobbly = { mass = 1, tension = 180, friction = 12 },
    stiff = { mass = 1, tension = 210, friction = 20 },
    slow = { mass = 1, tension = 280, friction = 60 },
    molasses = { mass = 1, tension = 280, friction = 120 },
}
```

--------------------------------

### useSpring To-Prop Shortcut

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useSpring.md

Demonstrates the shortcut for defining the `to` property in `useSpring`.

```lua
-- This...
local styles = RoactSpring.useSpring({ transparency = 1 })
-- is a shortcut for this...
local styles = RoactSpring.useSpring({ to = { transparency = 1 } })
```

--------------------------------

### Imperative API Usage

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Demonstrates the difference between declarative and imperative API usage for toggling transparency.

```APIDOC
## Imperative API Usage Example

### Description
This example contrasts the declarative approach with the imperative approach for toggling an element's transparency using Roact-Spring.

### Declarative API Example
```lua
local toggle, setToggle = useState(false)
local styles = RoactSpring.useSpring({
    transparency = if toggle then 0 else 1,
})

-- Later, to toggle:
setToggle(function(prevState)
    return not prevState
end)
```

### Imperative API Example
```lua
local styles, api = RoactSpring.useSpring(function()
    return { transparency = 1 }
end)

-- Later, to toggle transparency:
api.start({
    transparency = if styles.transparency:getValue() == 1 then 0 else 1
})
```
```

--------------------------------

### Animate Springs on Mount

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useSprings.md

Configure animations to run on component mount by specifying 'from' and 'to' values. This is useful for initial state transitions.

```lua
local springProps = {}
local length = #items
for index, item in ipairs(items) do
    table.insert(springProps, {
        from = { transparency = item.transparency },
        to = { transparency = if toggles[i] then 1 else 0 },
    })
end
local springs = RoactSpring.useSprings(length, springProps)
```

--------------------------------

### RoactSpring.useSpring Overview

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

The basic structure for using the useSpring hook with 'from' and 'to' properties.

```APIDOC
## RoactSpring.useSpring Overview

### Description
Provides a basic hook for animating properties using spring physics.

### Method
`useSpring`

### Endpoint
N/A (Hook)

### Parameters
#### Request Body
- **from** (table) - Required - Starting values for the animation.
- **to** (table) - Required - Target values for the animation.

### Request Example
```lua
RoactSpring.useSpring({
    from = { ... },
    to = { ... }
})
```

### Response
#### Success Response (200)
- **styles** (table) - The animated styles.
- **api** (table) - An API object for imperative control (e.g., start, stop).

#### Response Example
```json
{
  "styles": { ... },
  "api": { ... }
}
```
```

--------------------------------

### Mapping Styles Bindings with :map()

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useSpring.md

Shows how to use the `:map` function on style bindings to create custom behaviors, like animating position based on alpha.

```lua
local function Example(_)
    local styles, api = RoactSpring.useSpring(function()
        return {
            alpha = 0,
        }
    end)

    React.useEffect(function()
        api.start({ alpha = 1 })
    end, {})

	return React.createElement("Frame", {
        Transparency = styles.alpha,
        Position = styles.alpha:map(function(alpha)
            return UDim2.fromScale(0.2, 0.2):Lerp(UDim2.fromScale(0.8, 0.2), alpha)
        end),
    })
end
```

--------------------------------

### Spring Animation with Initial Velocity (Table Value)

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/configs.md

Apply velocity towards the top-left corner and then return to the original position by specifying the velocity as a table.

```lua
-- Will apply velocity towards the top-left corner and then return back to original position
local styles = RoactSpring.useSpring({
    position = UDim2.fromScale(0.5, 0.5),
    config = { velocity = {-0.01, 0, -0.01, 0} },
})
```

--------------------------------

### API Methods

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Details the available methods on the imperative API table returned by `useSpring` or `useSprings`.

```APIDOC
## API Methods

### Description
The `api` table, returned as the second value from `useSpring` or `useSprings`, provides methods to control animations imperatively.

### Methods

- **`start(props): Promise`**
  - Starts or updates an animation. Accepts a table of properties to animate. Returns a Promise that resolves when the animation completes.

- **`stop(keys?): void`**
  - Stops one or all animations. If `keys` (an array of strings) is provided, it stops animations corresponding to those keys. If no keys are provided, all animations are stopped.

- **`pause(keys?): void`**
  - Pauses one or all animations. If `keys` (an array of strings) is provided, it pauses animations corresponding to those keys. If no keys are provided, all animations are paused.

### Note
- The `api` table's identity is stable across re-renders, making it safe to omit from dependency arrays in hooks like `useEffect` or `useCallback`.
```

--------------------------------

### Chaining Animations with Promises

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Illustrates how to execute code after an animation completes by chaining a promise with `andThen`.

```APIDOC
## Chaining Animations with Promises

### Description
This example shows how to run a callback function after an animation has finished by using the `andThen` method on the promise returned by `api.start`.

### Method
`api.start(props).andThen(callback)`

### Example
```lua
api.start({
    position = UDim2.fromScale(0.5, 0.5),
    rotation = 0,
}):andThen(function()
    print("Animation finished!")
end)
```
```

--------------------------------

### RoactSpring Reset Prop

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Explains the 'reset' prop for restarting animations from scratch.

```APIDOC
## RoactSpring Reset Prop

### Description
Use the `reset` prop to start the animation from scratch. When undefined in imperative updates, the spring will assume `reset` is true if `from` is passed. In declarative updates, the spring will assume reset is false if reset is not passed in.

### Method
`useSpring` / `api.start`

### Parameters
#### Request Body
- **reset** (boolean) - If true, the spring starts to animate from scratch (from -> to).

### Request Examples

**Imperative Updates:**
```lua
local styles, api = RoactSpring.useSpring(function()
    return { transparency = 0.5 }
end)

-- The spring will start from 0
api.start({
    from = { transparency = 0 },
    to = { transparency = 1 },
})

-- The spring will ignore `from` and start from its current position
api.start({
    reset = false,
    from = { transparency = 0 },
    to = { transparency = 1 },
})
```

**Declarative Updates:**
```lua
-- The spring will start from 0.2 on mount and ignore `from` on future updates
local styles = RoactSpring.useSpring({
    from = { transparency = 0.2 },
    to = { transparency = if toggle then 0 else 1 },
}, { toggle })

-- The spring will always start from scratch from 0.2
local styles = RoactSpring.useSpring({
    reset = true,
    from = { transparency = 0.2 },
    to = { transparency = if toggle then 0 else 1 },
}, { toggle })
```
```

--------------------------------

### Initialize and Use Controller in Class Component

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Additional Classes/controller.md

Use this snippet when working with class components in roact-spring. It initializes the controller with default styles and provides an API to control animations. The API uses the colon operator.

```lua
function Example:init()
    self.styles, self.api = RoactSpring.Controller.new({
        size = UDim2.fromOffset(150, 150),
        position = UDim2.fromScale(0.5, 0.5),
    })
end

function Example:render()
	return e("TextButton", {
        Position = self.styles.position,
		Size = self.styles.size,

        [React.Event.Activated] = function()
            self.api:start({
                size = UDim2.fromOffset(150, 150),
                config = { tension = 100, friction = 10 },
            })
        end
	})
end
```

--------------------------------

### RoactSpring Default Props

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Explains how the 'default' prop sets default values for other props.

```APIDOC
## RoactSpring Default Props

### Description
The `default` prop lets you set the default value of certain props defined in the same update. For the declarative API, this prop is `true` by default.

### Method
`useSpring`

### Parameters
#### Request Body
- **default** (boolean) - Sets default value of compatible props if true.

### Request Example
```lua
-- Example demonstrating default prop usage (conceptual, as specific examples are not provided in source)
local styles = RoactSpring.useSpring({
    default = true,
    from = { opacity = 0 },
    to = { opacity = 1 },
})
```
```

--------------------------------

### Basic useSpring Hook

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

The basic structure for using the useSpring hook to define animation properties.

```lua
RoactSpring.useSpring({
    from = { ... }
})
```

--------------------------------

### Declarative Animation with useSpring

Source: https://github.com/chriscerie/roact-spring/blob/main/README.md

Use the useSpring hook for declarative animations. It takes a configuration object and returns animated styles. The state can be updated to trigger animations.

```lua
local toggle, setToggle = React.useState(false)
local styles = RoactSpring.useSpring({
    transparency = if toggle then 1 else 0,
})

-- Later
setToggle(function(prevState)
    return not prevState
end)
```

--------------------------------

### Control Animations Imperatively with Roact-Spring API

Source: https://context7.com/chriscerie/roact-spring/llms.txt

The imperative API from Roact-Spring hooks allows programmatic control over animations. Use `api.start()` to begin animations, `api.stop()` to halt them, and `api.pause()` to temporarily suspend them. `api.start()` returns a Promise for chaining.

```lua
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

local function ControlledAnimation()
    local styles, api = RoactSpring.useSpring(function()
        return {
            position = UDim2.fromScale(0.5, 0.5),
            rotation = 0,
            transparency = 0,
            default = true,                              -- Set default config
            config = { tension = 100, friction = 20 },   -- Default config for all animations
        }
    end)

    local function startAnimation()
        -- api.start() returns a Promise
        api.start({
            position = UDim2.fromScale(0.7, 0.3),
            rotation = 180,
        }):andThen(function()
            print("First animation complete!")
            return api.start({
                position = UDim2.fromScale(0.3, 0.7),
                rotation = 360,
            })
        end):andThen(function()
            print("Second animation complete!")
        end)
    end

    local function stopAnimation()
        api.stop()              -- Stop all animations
        -- api.stop({ "position" })  -- Stop only position animation
    end

    local function pauseAnimation()
        api.pause()             -- Pause all animations
        -- api.pause({ "rotation" }) -- Pause only rotation animation
    end

    return React.createElement("Frame", {
        Position = styles.position,
        Rotation = styles.rotation,
        Transparency = styles.transparency,
        Size = UDim2.fromScale(0.2, 0.2),
    })
end
```

--------------------------------

### RoactSpring Props Table

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/props.md

Details on the common properties that can be passed to RoactSpring.useSpring.

```APIDOC
## RoactSpring Props

### Description
All primitives inherit the following properties (though some of them may bring their own additionally):

### Parameters
#### Request Body
- **from** (table) - Starting values.
- **to** (table) - Animates to these values.
- **loop** (table/fn/bool) - Looping settings. See [loop prop](props#loop-prop) for more details.
- **delay** (number) - Delay in seconds before the animation starts.
- **immediate** (boolean) - Prevents animation if true.
- **config** (table) - Spring config (contains mass, tension, friction, etc). See [configs](configs).
- **reset** (bool) - The spring starts to animate from scratch (from -> to) if set true.
- **default** (bool) - Sets default value of compatible props if true. See [default props](props#default-props) for more details.
```

--------------------------------

### Imperative useSprings for List Animation

Source: https://context7.com/chriscerie/roact-spring/llms.txt

An imperative approach to animating lists using `useSprings`, allowing direct control over animations via the returned API. Ideal for triggering animations based on events or state changes.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

local items = { "Item1", "Item2", "Item3", "Item4" }

-- Imperative: animate springs individually with api.start()
local function ImperativeList()
    local springs, api = RoactSpring.useSprings(#items, function(index) 
        return {
            position = UDim2.fromScale(0.2, 0.1 * index),
            transparency = 0,
        }
    end)

    React.useEffect(function()
        -- Animate each spring to a different position based on index
        api.start(function(index) 
            return {
                position = UDim2.fromScale(0.5, 0.1 * index),
                config = { tension = 170, friction = 26 },
            }
        end)
    end, {}) 

    local children = {}
    for i, item in ipairs(items) do
        children[item] = React.createElement("Frame", {
            Position = springs[i].position,
            Transparency = springs[i].transparency,
            Size = UDim2.fromScale(0.3, 0.08),
        })
    end

    return React.createElement("Frame", { Size = UDim2.fromScale(1, 1) }, children)
end
```

--------------------------------

### Declarative useSprings for List Animation

Source: https://context7.com/chriscerie/roact-spring/llms.txt

Use this pattern to define spring properties for each item in a list declaratively. It's suitable for animating multiple elements with independent configurations.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local React = require(ReplicatedStorage.Packages.React)
local RoactSpring = require(ReplicatedStorage.Packages.RoactSpring)

local items = { "Item1", "Item2", "Item3", "Item4" }

-- Declarative: build spring props for each item
local function DeclarativeList()
    local toggle, setToggle = React.useState(false)

    local springProps = {}
    for i, item in ipairs(items) do
        table.insert(springProps, {
            from = { transparency = 1, position = UDim2.fromScale(0.3, 0.1 * i) },
            to = {
                transparency = if toggle then 0 else 1,
                position = if toggle then UDim2.fromScale(0.5, 0.1 * i) else UDim2.fromScale(0.3, 0.1 * i),
            },
        })
    end
    local springs = RoactSpring.useSprings(#items, springProps)

    local children = {}
    for i, item in ipairs(items) do
        children[item] = React.createElement("Frame", {
            Position = springs[i].position,
            Transparency = springs[i].transparency,
            Size = UDim2.fromScale(0.3, 0.08),
        })
    end

    return React.createElement("Frame", { Size = UDim2.fromScale(1, 1) }, children)
end
```

--------------------------------

### Imperative useTrail with API control

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useTrail.md

Pass a function that returns values and use the returned API to imperatively update animations. This method is more powerful and does not animate automatically on mount or re-render.

```lua
local length = #items
local springs, api = RoactSpring.useTrail(length, function(index)
    return { transparency = items[index].transparency }
end)

-- Start animations
api.start(function(index)
    return { position = UDim2.fromScale(0.5 * index, 0.16) }
end)
-- Stop all springs
api.stop()
```

--------------------------------

### Applying Styles to Components

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useSpring.md

Apply the animated values from the `styles` table to component properties.

```lua
return React.createElement("Frame", {
    Transparency = styles.transparency,
    Size = UDim2.fromScale(0.3, 0.3),
})
```

--------------------------------

### Declarative vs. Imperative Animation Toggling

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Compares the declarative `useState` approach with the imperative `useSpring` API for toggling transparency. The imperative API provides direct control over animations.

```lua
--[[
    Using declarative API
]]
local toggle, setToggle = useState(false)
local styles = RoactSpring.useSpring({
    transparency = if toggle then 0 else 1,
})

-- Later
setToggle(function(prevState)
    return not prevState
end)


--[[ 
    Using imperative API
]]
local styles, api = RoactSpring.useSpring(function()
    return { transparency = 1 }
end)

-- Later
api.start({ transparency = if styles.transparency:getValue() == 1 then 0 else 1 })
```

--------------------------------

### Declarative Animation with useSpring

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Hooks/useSpring.md

Use this for simple animations that update when component props change. No explicit API calls are needed.

```lua
local styles = RoactSpring.useSpring({
    transparency = if toggle then 1 else 0,
})
```

```lua
local styles = RoactSpring.useSpring({
    from = { transparency = 0 },
    to = { transparency = if toggle then 1 else 0 },
})
```

--------------------------------

### Apply Initial Velocity to Spring Animation

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/configs.md

Apply an initial velocity to a spring animation. A negative value moves away from the target, and a positive value moves towards it. For multi-dimensional values, specify velocity for each axis.

```lua
-- Start with initial velocity away from `to`
local styles = RoactSpring.useSpring({
    position = if toggle then UDim2.fromScale(0.5, 0.8) else UDim2.fromScale(0.5, 0.5),
    config = { velocity = -0.01 },
})
```

```lua
-- Start with initial velocity pointed towards the top-left corner
local styles = RoactSpring.useSpring({
    position = if toggle then UDim2.fromScale(0.5, 0.8) else UDim2.fromScale(0.5, 0.5),
    config = { velocity = {-0.01, 0, -0.01, 0} },
})
```

--------------------------------

### Chaining Animation Completion with andThen

Source: https://github.com/chriscerie/roact-spring/blob/main/docs/Common/imperatives.md

Executes a callback function after an animation completes by chaining the returned promise with `andThen`. This is useful for sequential tasks.

```lua
api.start({
    position = UDim2.fromScale(0.5, 0.5),
    rotation = 0,
}):andThen(function()
    print("Animation finished!")
end)
```