flutter-core:flutter-animations

What this skill does

# Flutter Animations

Master Flutter's animation system to create smooth, performant, and delightful user experiences through implicit animations, explicit control, hero transitions, and physics-based motion.

## Overview

Flutter's animation framework is built on a fundamental principle: well-designed animations make UIs feel more intuitive, contribute to a polished experience, and provide visual feedback that guides users through your application. The framework offers a comprehensive toolkit ranging from simple, pre-packaged implicit animations to fully customizable explicit animations with physics simulations.

Understanding when and how to use each type of animation is crucial for building modern Flutter applications. This skill provides comprehensive guidance on Flutter's animation capabilities, performance optimization techniques, and best practices for creating smooth, responsive animations.

## Animation Philosophy in Flutter

Flutter approaches animations through a layered architecture that balances ease of use with powerful control:

**Progressive Complexity**: Start with the simplest solution that meets your needs. Flutter encourages using implicit animations for straightforward transitions, explicit animations when you need coordination, and custom implementations only when necessary. This progressive approach ensures you're not adding unnecessary complexity to your codebase.

**Declarative Animation**: Unlike imperative animation systems where you manually calculate and set values frame-by-frame, Flutter's declarative approach lets you specify what should change and the framework handles the interpolation. You describe the start and end states, and Flutter smoothly transitions between them.

**Composition Over Inheritance**: Flutter's animation classes are designed to compose together. A `CurvedAnimation` wraps an `AnimationController`, a `Tween` transforms values, and these pieces combine to create sophisticated effects without deep inheritance hierarchies.

**Performance First**: The animation system is optimized for 60fps (or 120fps on capable devices) by default. The framework provides tools like `RepaintBoundary` and `AnimatedBuilder` to minimize unnecessary rebuilds and ensure smooth performance even on lower-end devices.

## Implicit vs Explicit Animations

The choice between implicit and explicit animations is one of the first decisions you'll make when adding motion to your Flutter app.

### Implicit Animations

Implicit animations are Flutter widgets that automatically animate property changes over a specified duration. They derive from `ImplicitlyAnimatedWidget` and handle all animation controller management internally.

**When to Use Implicit Animations**:
- Animating simple property changes (opacity, size, color, position)
- One-off transitions triggered by user interaction or state changes
- Prototyping animation ideas quickly
- When you don't need to coordinate multiple animations together

**Common Implicit Animated Widgets**:
- `AnimatedContainer` - Animates container properties like size, color, padding, and borders
- `AnimatedOpacity` - Fades widgets in and out
- `AnimatedPositioned` - Animates position changes within a Stack
- `AnimatedAlign` - Animates alignment changes
- `AnimatedPadding` - Animates padding transitions
- `AnimatedSwitcher` - Cross-fades between different widgets
- `TweenAnimationBuilder` - Creates custom implicit animations for any property

**Key Advantages**:
- Minimal boilerplate code
- No need to manage AnimationController lifecycle
- Automatic cleanup when widget is disposed
- Perfect for UI polish and subtle transitions

**Example Use Case**: A button that changes color when pressed, a container that expands when selected, or a widget that fades in when data loads.

### Explicit Animations

Explicit animations give you full control over the animation lifecycle through `AnimationController`. You manage when animations start, stop, reverse, and repeat.

**When to Use Explicit Animations**:
- Coordinating multiple simultaneous animations (staggered effects)
- Creating looping or repeating animations
- Responding to user gestures in real-time (drag, fling)
- Building complex animation choreography
- When you need precise control over animation timing

**Core Components**:
- `AnimationController` - The animation timeline controller
- `Tween` - Maps animation values to custom ranges
- `CurvedAnimation` - Applies easing curves
- `AnimatedBuilder` - Efficiently rebuilds only animated parts
- `AnimatedWidget` - Base class for reusable animated widgets

**Key Advantages**:
- Fine-grained control over timing and playback
- Ability to coordinate multiple animations
- Support for custom animation curves
- Integration with gestures and physics simulations

**Example Use Case**: A loading spinner that continuously rotates, a card that flips over with coordinated opacity and rotation changes, or an interactive animation that follows user drag gestures.

## Hero Animations

Hero animations, also known as shared element transitions, create visual continuity between screens by animating a widget from one route to another. This pattern is ubiquitous in modern mobile apps - think of tapping a photo thumbnail that smoothly expands into a full-screen view.

**How Hero Animations Work**:

1. **Tagging**: Wrap widgets on both the source and destination screens with `Hero` widgets sharing the same `tag`
2. **Detection**: When you push a new route, Flutter's Navigator detects matching hero tags
3. **Animation**: The hero widget flies from its position on the first screen to its position on the second screen
4. **Morphing**: The hero can change size, shape, and position during the transition

**Behind the Scenes**:

Flutter doesn't actually move the widget between screens. Instead, it:
- Creates a copy in an overlay above both routes
- Animates the overlay widget's bounds using `RectTween`
- Uses `MaterialRectArcTween` for curved motion paths
- Removes the overlay and reveals the destination widget when complete

**Standard Hero Pattern**:
The most common pattern involves an image or card that appears on a list screen and expands to fill the detail screen. The hero tag uniquely identifies which elements should animate together.

**Radial Hero Animations**:
A variant where the hero transforms from circular to rectangular (or vice versa) while flying between screens. This requires using `MaterialRectCenterArcTween` and `RadialExpansion` to maintain the circular clipping during the animation.

**Best Practices**:
- Use meaningful, unique tags that won't accidentally match other heroes
- Keep the widget tree structure similar between source and destination
- Wrap image heroes in `Material(color: Colors.transparent)` for smooth transitions
- Use `timeDilation` to slow animations during development and debugging
- Ensure heroes have defined sizes on both screens

## Performance Considerations

Creating smooth animations requires understanding Flutter's rendering pipeline and avoiding common performance pitfalls.

### The 60fps Target

Flutter aims to render frames in 16ms or less (60 frames per second). On devices with 120Hz displays, this target drops to 8ms. Each frame consists of:
- **Build phase** (8ms budget): Constructing the widget tree
- **Layout/Paint phase** (8ms budget): Measuring and rendering

If either phase exceeds its budget, you'll experience jank - visible stuttering or dropped frames.

### Critical Performance Rules

**1. Avoid Opacity Widget in Animations**

The `Opacity` widget is expensive because it requires rendering the child into an intermediate buffer before applying opacity. For animations:
- Use `AnimatedOpacity` instead of wrapping widgets in `Opacity`
- Use `FadeInImage` for image fade transitions
- Apply opacity directly to decoration colors when possible

**2. Optimize AnimatedBuilder Usage**

`AnimatedBuilder` rebuilds its subtree on every animation frame. To minimize work:
- Pass static wi