Skip to content
Blog

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

SituationUse
One target value, no control neededImplicit widget (AnimatedContainer, AnimatedOpacity)
One tween to a target, no controllerTweenAnimationBuilder
Controller-driven rebuild of a subtreeAnimatedBuilder
Same, but no extra state, reusable widgetAnimatedWidget 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 via child.
  • Rebuilding the whole page because the builder was placed too high in the tree. Scope it as low as possible.
  • Recreating the animation, Tween, or Listenable.merge list 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.value outside 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