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).
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 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.
3. Lifecycle
- Dispose every
AnimationControllerinState.dispose(); use theSingleTickerProviderStateMixinfor one controller andTickerProviderStateMixinfor 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 inTickerMode(enabled: ...). - A stale
Tickeror leaked controller is a memory problem too: flutter-perf-memory-and-leaks.
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.
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).
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.
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.