AnimatedBuilder Patterns: Rebuild Only What Moves
AnimatedBuilder deep dive: the child optimization, composed builders, Listenable.merge, AnimatedWidget subclasses, status listeners, RepaintBoundary, and pitfalls.
Published on • November 12, 2026
AI Assistant

An AnimationController ticking at 60 frames per second is only useful if the rebuild cost per frame stays tiny. AnimatedBuilder is the widget that turns a Listenable into a scoped rebuild, and the difference between a smooth animation and a janky one is almost always how you use its builder and child. This post goes past the basic example into the patterns that hold up in production.
The builder and the child optimization
The constructor is AnimatedBuilder({required Listenable animation, required TransitionBuilder builder, Widget? child}). Everything that does not depend on the animation should go into child, which the framework builds once and hands back to your builder:
AnimatedBuilder(
animation: _rotation,
builder: (context, child) => Transform.rotate(
angle: _rotation.value,
child: child,
),
child: const ProductCardVisual(), // built once, reused every tick
)
The API docs are blunt about it: if the builder contains a subtree that does not depend on the animation, building it once is more efficient, and using the pre-built child “is a good practice.” Forgetting this is the single most common explicit-animation mistake.
AnimatedWidget as the cleaner alternative
When the widget has no extra state, subclassing AnimatedWidget removes the closure entirely:
class SpinningBadge extends AnimatedWidget {
const SpinningBadge({super.key, required Animation<double> rotation})
: super(listenable: rotation);
@override
Widget build(BuildContext context) {
final angle = (listenable as Animation<double>).value;
return Transform.rotate(angle: angle, child: const BadgeArt());
}
}
The class docs say AnimatedWidget is “most useful for widgets that are otherwise stateless,” and point to AnimatedBuilder for the more complex case with additional state. The framework ships a whole family of these already: RotationTransition, ScaleTransition, SlideTransition, FadeTransition, SizeTransition, and friends.
Combining controllers with Listenable.merge
A widget often depends on two sources, a controller plus a ValueNotifier, or a controller plus a focus node. Fan them into one Listenable:
AnimatedBuilder(
animation: Listenable.merge([_controller, _dragState]),
builder: (context, _) => Opacity(
opacity: _dragState.value ? 0.5 : 1,
child: ScaleTransition(scale: _scale, child: const Panel()),
),
)
Listenable.merge returns a listenable that fires when any source fires, so one builder covers both. Keep the merged list stable across builds (a field, not a constructor-local), otherwise you churn listeners every frame.
Nested and composed builders
Nothing stops you from nesting builders, and it is the right tool when two animations touch different parts of one widget:
AnimatedBuilder(
animation: _fadeIn,
builder: (context, child) => Opacity(
opacity: _fadeIn.value,
child: SlideTransition(position: _slideOffset, child: child),
),
child: const Header(),
)
The inner builder’s child is the outer builder’s child, so the expensive leaf is still built once. A flatter alternative is one builder reading both values; prefer that when the two animations always change together.
Reacting to status changes
Values are not the whole story. AnimationStatusListener, typed as void Function(AnimationStatus status), is attached with addStatusListener and fires on dismissed, forward, reverse, and completed, which is where you chain the next animation or flip app state:
_controller.addStatusListener((status) {
if (status == AnimationStatus.completed) _advanceToNextStage();
});
Remove it in dispose alongside _controller.dispose(). Do not do heavy work directly in the listener; schedule it, because status callbacks run during the frame.
Repaint boundaries around expensive subtrees
Rebuild scope and repaint scope are different problems. A RepaintBoundary “creates a separate display list for its child,” so when an ancestor repaints, the boundary’s cached pixels are reused instead of repainted:
RepaintBoundary(
child: AnimatedBuilder(
animation: _controller,
builder: (context, child) => CustomPaint(painter: _wavePainter()),
),
)
This matters when a fast animation sits next to a large static subtree: without a boundary, the whole shared layer repaints every tick. Watch for the opposite mistake too, wrapping every small widget so memory grows with layers.
Choosing the tool
| Situation | Use |
|---|---|
| One target value, no control needed | Implicit widget (AnimatedContainer, AnimatedOpacity) |
| One tween to a target, no controller | TweenAnimationBuilder |
| Controller-driven rebuild of a subtree | AnimatedBuilder |
| Same, but no extra state, reusable widget | AnimatedWidget subclass or a *Transition |
Non-animation Listenable (notifier, focus, controller) | ListenableBuilder or ValueListenableBuilder |
The existing implicit animations post covers the first row, the explicit animations post covers controller setup and the child trick, and the ListenableBuilder patterns post covers the non-animation listener cases.
Common pitfalls
- Doing expensive work inside
builder: layout math, string formatting, and image decoding all run per frame. Hoist them out or pass them viachild. - Rebuilding the whole page because the builder was placed too high in the tree. Scope it as low as possible.
- Recreating the animation,
Tween, orListenable.mergelist on every build, which tears down and reattaches listeners. - Forgetting to dispose the controller or remove status listeners, leaking tickers past the route.
- Reading
animation.valueoutside the builder, which silently skips rebuilds.
Takeaway: Put everything that does not change into child, subclass AnimatedWidget when there is no extra state, merge multiple sources with Listenable.merge, isolate repaints with RepaintBoundary, and keep expensive work out of the builder, because a builder that runs 60 times a second is the only place your animation budget can really be lost.
Sources
- https://api.flutter.dev/flutter/widgets/AnimatedBuilder-class.html
- https://api.flutter.dev/flutter/widgets/AnimatedWidget-class.html
- https://api.flutter.dev/flutter/widgets/ListenableBuilder-class.html
- https://api.flutter.dev/flutter/animation/AnimationStatusListener.html
- https://api.flutter.dev/flutter/widgets/RepaintBoundary-class.html
- https://docs.flutter.dev/ui/animations