# Flutter Perf Animation

> Use when an animation drops frames, a looping animation keeps running off-screen, many animations start together, or a list item animates on insert or remove. Reviews Flutter animation cost: setState called on every animation tick, animating width, height or padding instead of a transform, controllers created in build or never disposed, tickers running for hidden screens, simultaneous effects, and third-party animation files (Lottie, Rive). Do not use for static Opacity, blur or clipping (flutter-perf-rendering-effects) or for general rebuild scope (flutter-perf-build-and-rebuild).

- Skill: `kinwisenz-devops/flutter-perf-animation` (Agent Skill)
- Install (CLI): `npx get-skill add kinwisenz-devops/flutter-perf-animation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinwisenz-devops/flutter-perf-animation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KinwiseNZ-DevOps (https://skillmd.com/u/kinwisenz-devops)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/kinwisenz-devops/flutter-perf-animation

---


# Animation

Animation is meant to run every frame, so small costs repeat 60 or more times a second. Act only on an animation the profile shows is expensive.

## Gate

Profile mode, physical device. In DevTools, are the frames janky while the animation runs, and is the time in build, layout, paint or raster? The remedy depends on which one. Judge against the device's real refresh rate (see [guardrails](../flutter-performance-specialist/references/guardrails.md)).

## 1. Rebuilds per tick

| Pattern | Action |
|---|---|
| `controller.addListener(() => setState(...))` rebuilding a large subtree | Use `AnimatedBuilder`, `AnimatedWidget` or a transition widget, and pass the static subtree as the builder's `child`. See [flutter-perf-build-and-rebuild](../flutter-perf-build-and-rebuild/SKILL.md) section 5 |
| One animated value | `TweenAnimationBuilder`, a ready-made `*Transition` widget, or an `Animated*` implicit widget; no custom controller needed |
| `Tween` and `CurvedAnimation` created inside `build()` | Create once in `initState` (or as fields) |

## 2. Layout versus transform

Animating `width`, `height`, `padding`, `margin` or alignment can run layout every frame. A `Transform` or `*Transition` (`ScaleTransition`, `SlideTransition`, `FadeTransition`) changes how the child is painted without relaying out its neighbours. Use it only when the visual result is the same: a transform does not change the space the widget takes in the layout. Confirm in the timeline that layout time fell.

Opacity and clipping inside animations: [flutter-perf-rendering-effects](../flutter-perf-rendering-effects/SKILL.md).

## 3. Lifecycle

- Dispose every `AnimationController` in `State.dispose()`; use the `SingleTickerProviderStateMixin` for one controller and `TickerProviderStateMixin` for several.
- A repeating animation (`repeat()`) on a screen that is not visible still costs CPU and battery. Routes under another route are muted by the navigator; for tabs, pages and offscreen widgets you control, stop the controller or wrap the subtree in `TickerMode(enabled: ...)`.
- A stale `Ticker` or leaked controller is a memory problem too: [flutter-perf-memory-and-leaks](../flutter-perf-memory-and-leaks/SKILL.md).

## 4. Many animations at once

Many items animating together (a list of cards, particles, staggered entrances) multiply the per-frame cost. Stagger them with `Interval` curves, limit how many run at once, and animate only what is on screen. Drive many identical items from one controller instead of one each, where the design allows.

## 5. Lists

`AnimatedList` and `SliverAnimatedList` are the framework tools for animated insert and remove; they do not remove the need for lazy item construction. Keep item builders cheap: [flutter-perf-lists-and-scrolling](../flutter-perf-lists-and-scrolling/SKILL.md).

## 6. Lottie, Rive and similar files

These are third-party packages; their cost depends on file complexity and the package version. Measure before blaming or replacing them.

- Check file size and complexity, and how many play at once, especially inside list items.
- Load the file once and reuse it; do not reload it on every build.
- Do not add or swap a package without need (see [guardrails](../flutter-performance-specialist/references/guardrails.md)).

## 7. Reduced motion

`MediaQuery.disableAnimations` reports the user's platform setting to reduce animation. Respecting it is good practice, but removing animation changes the design: state it as a visual trade-off in the report, never slip it in.

## Verify

Same interaction, same device, before and after: janky frame count and the build, layout and paint times during the animation. Method: [flutter-perf-profiling-and-validation](../flutter-perf-profiling-and-validation/SKILL.md).

## Hard rules

- Act only on what the user asked. Before answering or changing anything, open the relevant files and check what is already done; report only what you checked, never guess, and do not redo finished work. Reason: guesses and repeated work waste the user's credit.

