Imperative API and Advanced Control
What you'll learn: How to break out of React Spring's declarative shell and take direct, programmatic command of your animations when complex state logic demands it.
Why Go Imperative?
React Spring's declarative hooks (useSpring, useTransition) work beautifully for most cases—you change props, animations react. But sometimes you need surgical precision: triggering animations from event handlers, coordinating with external libraries, or building complex interactive sequences that don't map cleanly to React's render cycle.
The imperative API gives you a reference to the animation controller itself, letting you start, stop, update, or chain animations on demand—like having a remote control instead of relying on automatic sensors.
The api Object
When you call useSpring() or useSprings(), you can destructure an api object alongside your animated values:
const [springs, api] = useSpring(() => ({
x: 0,
opacity: 1
}));
This api lets you imperatively control animations:
function handleClick() {
api.start({ x: 100, opacity: 0 });
}
You're no longer tied to re-renders—api.start() fires immediately, perfect for mouse events, timers, or WebSocket messages.
Advanced Control Methods
api.start(config)— Trigger new animation valuesapi.stop()— Freeze animation mid-flightapi.pause()/api.resume()— Temporarily halt and continue- Chaining with promises —
api.start().then(() => ...)for sequencing
Think of it as switching from a thermostat (declarative: "keep the room at 70°F") to a manual dial (imperative: "turn heat up NOW").
When to Use It
Use the imperative API when animations need to respond to non-React events, complex user interactions, or when declarative updates would cause unnecessary re-renders. It's your escape hatch for performance and precision.
Key Takeaway: The imperative API gives you direct animation control via the api object, perfect for event-driven, programmatic sequences that don't fit React's declarative model.