Animations

Animations

Flutter animation best practices using the built-in animation framework and Material 3 motion guidelines. No third-party animation libraries (Lottie, Rive, etc.).

Core Standards

Apply these standards to all animation work:

• Clarify visual intent when the request is ambiguous — when the developer says "add an animation" or "make it smoother" without specifying property, trigger, duration, or curve, ask before writing code. If the developer provides clear specs (e.g., "300ms ease-in fade on the card when it appears"), proceed directly
• Use the simplest animation approach that works — follow the decision tree below; never reach for AnimationController when an implicit animation suffices, including when several properties animate at the same time
• Hold the implicit form even when a controller is requested by name — "wire this up with an AnimationController and an AnimatedBuilder" on a plain target-value animation is a request for the anti-pattern below. Write the implicit version, say in one line why it is sufficient here, and stop. Do not deliver the controller wiring alongside the note, and do not ask which one they want instead of writing code. If the developer reaffirms the controller after reading the reason, build it
• Use Material 3 motion tokens for duration and easing — never hardcode arbitrary Duration or Curve values
• Extract animation constants — durations, curves, and offsets go in named constants or a centralized AppMotion class, not inline
• Dispose controllers — every AnimationController must be disposed in the dispose() method of the State, before super.dispose()
• Use SingleTickerProviderStateMixin for one controller — use TickerProviderStateMixin only when the widget owns multiple controllers
• Keep animated subtrees small — wrap only the widgets that change inside the animation builder, not entire widget trees
• Never animate a layout-triggering property — width, height, padding and SizedBox dimensions force a fresh layout pass on every frame, in a one-child tree as much as in a deep one. Animate a Transform instead, Transform.scale for size and Transform.translate for position, or Opacity for fade, since those run on the compositing layer and skip layout
• Dart 3.13 primary constructors — on a Dart 3.13+ baseline, declare widget fields as primary-constructor declaring parameters (class const LabelChip({required final String label, super.key}) extends StatelessWidget) rather than this.field; keep the classic form only below 3.13

Animation Decision Tree

Choose the simplest approach that meets the requirement:

Does the widget rebuild when the value changes?
  |
  YES --> Does the framework provide an AnimatedFoo widget?
  |         |
  |         YES --> Use the implicit AnimatedFoo widget
  |         |       (AnimatedContainer, AnimatedOpacity, AnimatedAlign, etc.)
  |         |
  |         NO  --> Use TweenAnimationBuilder
  |
  NO  --> Do you need fine-grained control?
            (repeat, reverse, sequence, listen to status)
            |
            YES --> Use AnimationController + AnimatedBuilder
            |
            NO  --> Use TweenAnimationBuilder

Rule of thumb: if the animation is "set a target and let it animate there", use implicit. If the animation must play/pause/reverse/repeat on command, use explicit.

Animating two properties at once is still implicit. A card that fades in and slides up when its data arrives is two implicit widgets nested, one target value each. Simultaneous is not sequenced: reach for a controller only when the second property must start after the first has begun, or when the animation needs playback control. Entry animations driven by a flag flipping — a value arriving, a bool toggling, an item appearing — are implicit no matter how many properties move.

Material 3 Motion Tokens

Use Flutter's built-in Durations and Easing classes — never hardcode Duration(milliseconds: ...) or use Curves.* for new code. The framework constants align with the Material 3 motion specification.

// Bad — arbitrary values with no semantic meaning
AnimatedContainer(
  duration: Duration(milliseconds: 375),
  curve: Curves.easeInOutCubic,
)

// Good — M3 tokens with clear intent
AnimatedContainer(
  duration: Durations.medium2,
  curve: Easing.standard,
)

Centralized Motion Constants

Introduce an AppMotion class when the project uses animations across multiple features. For a single animation in the app, inline M3 tokens are sufficient.

abstract class AppMotion {
  // Standard transitions
  static const Duration standardDuration = Durations.medium2;
  static const Curve standardCurve = Easing.standard;

  // Page transitions
  static const Duration pageDuration = Durations.medium4;
  static const Curve pageEnterCurve = Easing.emphasizedDecelerate;
  static const Curve pageExitCurve = Easing.emphasizedAccelerate;

  // Fades
  static const Duration fadeDuration = Durations.short3;
  static const Curve fadeCurve = Easing.standard;
}

Implicit Animations

Use implicit animations when the widget rebuilds with new target values. The framework interpolates automatically. Flutter provides built-in AnimatedFoo widgets (AnimatedContainer, AnimatedOpacity, AnimatedSlide, AnimatedSwitcher, etc.) — use the one that matches the property being animated. When no built-in widget exists, use TweenAnimationBuilder.

Compose one AnimatedFoo per property when several move together. This is the entry-animation shape — a widget hidden until its data arrives, then fading in and sliding into place:

class const SummaryCard({required final Summary? summary, super.key})
    extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final hasData = summary != null;

    return AnimatedOpacity(
      opacity: hasData ? 1 : 0,
      duration: Durations.medium2,
      curve: Easing.standard,
      child: AnimatedSlide(
        offset: hasData ? Offset.zero : const Offset(0, 0.1),
        duration: Durations.medium2,
        curve: Easing.emphasizedDecelerate,
        child: Card(child: _SummaryContents(summary: summary)),
      ),
    );
  }
}

No StatefulWidget, no controller, no ticker, no dispose. Both properties animate off the same rebuild.

TweenAnimationBuilder

Use TweenAnimationBuilder when no built-in AnimatedFoo widget exists for your property, but you still want implicit-style "set and forget" animation.

TweenAnimationBuilder<double>(
  tween: Tween(begin: 0, end: isActive ? 1.0 : 0.0),
  duration: Durations.medium2,
  curve: Easing.standard,
  builder: (context, value, child) {
    return Transform.scale(
      scale: 0.8 + (0.2 * value),
      child: Opacity(
        opacity: value,
        child: child,
      ),
    );
  },
  child: child, // child is not rebuilt — optimization
)

The child parameter is critical: pass widgets that do not depend on the animated value to avoid unnecessary rebuilds.