swiftui-animations

name: swiftui-animations
description: Use when building, debugging, or refining animations in SwiftUI iOS/macOS apps. Covers implicit/explicit animations, transitions, gesture-driven interactions, and modern iOS 17+ APIs like PhaseAnimator and KeyframeAnimator.

You are an expert in SwiftUI animations. Help developers create smooth, performant, and accessible animations following Apple's best practices.

Core Principles

How SwiftUI Animation Works

1. Animations are driven by state changes – SwiftUI animates the difference between old and new state
2. Transactions propagate down – When you wrap a state change in withAnimation, a transaction flows through the view hierarchy
3. Only animatable data animates – Types must conform to Animatable (most built-in types do: CGFloat, Color, CGSize, etc.)
4. Animation is declarative – You describe what the end state looks like, SwiftUI figures out the interpolation

Mental Model

State Change → Transaction Created → View Diffed → Animatable Properties Interpolated → Frames Rendered

Think of animations as automatic interpolation between two snapshots of your view. Your job is to:
1. Define the two states clearly
2. Tell SwiftUI which timing curve to use
3. Ensure the properties you want animated are Animatable

Implicit Animations

The easiest way to animate – attach an .animation() modifier or wrap state changes in withAnimation.

withAnimation (Recommended)

Wraps a state change so all resulting view updates animate:

withAnimation(.spring(duration: 0.4, bounce: 0.3)) {
    isExpanded.toggle()
}

When to use: When you control the state change (button taps, gestures, responses).

.animation() Modifier

Animates whenever the observed value changes:

Circle()
    .scaleEffect(isActive ? 1.2 : 1.0)
    .animation(.easeInOut(duration: 0.3), value: isActive)

When to use: When state changes outside your control (bindings, parent state).

Critical: Always use value: parameter. The old .animation(.default) without value is deprecated and causes unpredictable behavior.

Timing Curves

Rule of thumb: Use .spring() unless you have a reason not to. Apple's HIG recommends spring animations for most interactions.

Explicit Animations

For custom types and complex animations where implicit animation isn't enough.

The Animatable Protocol

Any type can animate if it provides an animatableData property:

struct AnimatableGradient: View, Animatable {
    var progress: CGFloat

    var animatableData: CGFloat {
        get { progress }
        set { progress = newValue }
    }

    var body: some View {
        // Use progress (0→1) to interpolate colors, positions, etc.
    }
}

SwiftUI calls the setter repeatedly with interpolated values between old and new state.

AnimatableModifier

For reusable animated effects:

struct CountingModifier: AnimatableModifier {
    var value: Double

    var animatableData: Double {
        get { value }
        set { value = newValue }
    }

    func body(content: Content) -> some View {
        content.overlay(Text("\(Int(value))"))
    }
}

// Usage: Text counts from 0 to 100
Text("Score").modifier(CountingModifier(value: score))

Animating Shapes

Shapes animate via their animatableData. For multiple values, use AnimatablePair:

struct Wedge: Shape {
    var startAngle: Double
    var endAngle: Double

    var animatableData: AnimatablePair<Double, Double> {
        get { AnimatablePair(startAngle, endAngle) }
        set {
            startAngle = newValue.first
            endAngle = newValue.second
        }
    }

    func path(in rect: CGRect) -> Path { /* ... */ }
}

Nested pairs for 3+ values: AnimatablePair<CGFloat, AnimatablePair<CGFloat, CGFloat>>

Transitions

Transitions animate views entering and leaving the view hierarchy. They only apply when views are inserted/removed (via if, switch, ForEach changes).

Built-in Transitions

if showDetail {
    DetailView()
        .transition(.slide)
}

Combining Transitions

.transition(.scale.combined(with: .opacity))

// Or use extension for reusability:
extension AnyTransition {
    static var scaleAndFade: AnyTransition {
        .scale(scale: 0.8).combined(with: .opacity)
    }
}

Asymmetric Transitions

Different animations for insertion vs removal:

.transition(.asymmetric(
    insertion: .move(edge: .trailing).combined(with: .opacity),
    removal: .move(edge: .leading).combined(with: .opacity)
))

Custom Transitions

Build from any ViewModifier:

struct SlideAndBlur: ViewModifier {
    let active: Bool

    func body(content: Content) -> some View {
        content
            .offset(x: active ? 200 : 0)
            .blur(radius: active ? 10 : 0)
    }
}

extension AnyTransition {
    static var slideBlur: AnyTransition {
        .modifier(
            active: SlideAndBlur(active: true),
            identity: SlideAndBlur(active: false)
        )
    }
}

Key gotcha: Transitions require withAnimation around the state change that adds/removes the view. The .animation() modifier on the view itself won't trigger transitions.

Gesture-Driven Animations

Interactive animations that respond to user touch in real-time.

Basic Drag with Spring Release

@State private var offset: CGSize = .zero

var body: some View {
    Circle()
        .offset(offset)
        .gesture(
            DragGesture()
                .onChanged { offset = $0.translation }
                .onEnded { _ in
                    withAnimation(.spring(response: 0.4, dampingFraction: 0.6)) {
                        offset = .zero
                    }
                }
        )
}

GestureState for Auto-Reset

@GestureState automatically resets when gesture ends – perfect for temporary states:

@GestureState private var dragOffset: CGSize = .zero

var body: some View {
    Card()
        .offset(dragOffset)
        .animation(.interactiveSpring, value: dragOffset)
        .gesture(
            DragGesture()
                .updating($dragOffset) { value, state, _ in
                    state = value.translation
                }
        )
}

Velocity-Aware Animations

Use gesture velocity for natural-feeling releases:

.onEnded { gesture in
    let velocity = CGVector(
        dx: gesture.velocity.width / 300,
        dy: gesture.velocity.height / 300
    )
    withAnimation(.spring(response: 0.4, dampingFraction: 0.7, blendDuration: 0.25).speed(1)) {
        // Factor velocity into final position
    }
}

Tracking Animation Progress

Use GeometryReader + PreferenceKey or iOS 17's onGeometryChange to read animated values for coordinated effects.

Spring Parameters for Gestures

Modern APIs (iOS 17+)

iOS 17 introduced powerful declarative animation APIs that simplify complex sequences.

PhaseAnimator

Cycles through discrete phases automatically – perfect for looping or multi-step animations:

enum BouncePhase: CaseIterable {
    case initial, compress, stretch, settle

    var scale: CGSize {
        switch self {
        case .initial: CGSize(width: 1, height: 1)
        case .compress: CGSize(width: 1.1, height: 0.9)
        case .stretch: CGSize(width: 0.9, height: 1.1)
        case .settle: CGSize(width: 1, height: 1)
        }
    }
}

PhaseAnimator(BouncePhase.allCases) { phase in
    Circle()
        .scaleEffect(phase.scale)
} animation: { phase in
    switch phase {
    case .initial: .spring(duration: 0.2, bounce: 0.5)
    default: .spring(duration: 0.25, bounce: 0.3)
    }
}

Trigger-based: Add trigger: parameter to run on value change instead of looping:

PhaseAnimator(phases, trigger: triggerValue) { phase in ... }

KeyframeAnimator

Fine-grained control with keyframes on multiple properties:

KeyframeAnimator(initialValue: AnimationState()) { state in
    Circle()
        .offset(x: state.xOffset)
        .scaleEffect(state.scale)
        .opacity(state.opacity)
} keyframes: { _ in
    KeyframeTrack(\.xOffset) {
        LinearKeyframe(0, duration: 0.1)
        SpringKeyframe(100, duration: 0.4, spring: .bouncy)
        SpringKeyframe(0, duration: 0.3)
    }
    KeyframeTrack(\.scale) {
        LinearKeyframe(1.0, duration: 0.1)
        CubicKeyframe(1.3, duration: 0.2)
        CubicKeyframe(1.0, duration: 0.4)
    }
}

Keyframe types:
- LinearKeyframe – Constant velocity
- CubicKeyframe – Bezier easing
- SpringKeyframe – Physics-based
- MoveKeyframe – Instant jump (no interpolation)

New Spring Syntax

iOS 17 simplified spring parameters:

// Old (still works)
.spring(response: 0.5, dampingFraction: 0.7)

// New – more intuitive
.spring(duration: 0.5, bounce: 0.3)  // bounce: 0 = no bounce, 1 = max bounce

// Presets
.spring(.smooth)    // No bounce
.spring(.snappy)    // Slight bounce
.spring(.bouncy)    // Pronounced bounce

When to Use What

Critical Rules

DO:

• Always use value: parameter with .animation() modifier – the valueless version is deprecated and buggy
• Prefer withAnimation over .animation() – more explicit control over what triggers animation
• Use springs as default – they feel more natural than linear/ease curves
• Respect reduced motion – check accessibilityReduceMotion (see Accessibility section)
• Animate layout, not frames – use .offset(), .scaleEffect(), .opacity() rather than changing frame directly
• Keep animations under 400ms for UI responses – longer feels sluggish
• Test on device – Simulator timing differs from real hardware

DO NOT:

• Don't animate inside body computation – body should be pure; trigger animations from state changes
• Don't use .animation() without value: – causes unpredictable cascading animations
• Don't fight the framework – if an animation is hard to achieve, reconsider the approach
• Don't animate too many properties simultaneously – pick 2-3 max for clarity
• Don't use DispatchQueue.main.asyncAfter for sequencing – use PhaseAnimator or completion-based APIs
• Don't nest withAnimation blocks – the innermost wins, outer is ignored
• Don't assume animation completion – SwiftUI doesn't guarantee completion callbacks; use Transaction for critical sequencing

Common Gotchas

Accessibility

Respecting Reduced Motion

Users can enable "Reduce Motion" in system settings. Always provide alternatives:

@Environment(\.accessibilityReduceMotion) var reduceMotion

var body: some View {
    Card()
        .transition(reduceMotion ? .opacity : .slide.combined(with: .opacity))
}

// For animations:
func animateChange() {
    if reduceMotion {
        // Instant or simple fade
        withAnimation(.easeOut(duration: 0.15)) {
            isExpanded.toggle()
        }
    } else {
        // Full spring animation
        withAnimation(.spring(duration: 0.4, bounce: 0.3)) {
            isExpanded.toggle()
        }
    }
}

Quick Helper

extension Animation {
    static func respectful(_ animation: Animation, reducedMotion: Animation = .easeOut(duration: 0.15)) -> Animation {
        // Use at call site with @Environment check
        animation
    }
}

// Or create a View extension:
extension View {
    func animateRespectfully<V: Equatable>(
        _ animation: Animation,
        value: V,
        reduceMotion: Bool
    ) -> some View {
        self.animation(reduceMotion ? .easeOut(duration: 0.15) : animation, value: value)
    }
}

Guidelines

• Fade is always safe – .opacity transitions work for everyone
• Reduce, don't remove – some motion helps comprehension; just make it subtle
• Avoid vestibular triggers – large zooms, parallax, spinning are problematic
• Test with setting enabled – Settings → Accessibility → Motion → Reduce Motion