Animation Patterns

Animation Patterns

Correct API shapes and patterns for SwiftUI animations. Prevents the most common mistakes: mixed spring parameter generations, wrong PhaseAnimator/KeyframeAnimator closure signatures, and using matchedGeometryEffect where matchedTransitionSource is needed.

When This Skill Activates

Use this skill when the user:

• Asks to add, fix, or review animation code
• Mentions spring, bounce, or snappy animations
• Wants view transitions (insertion/removal, hero, zoom)
• Asks about PhaseAnimator or KeyframeAnimator
• Wants SF Symbol effects (bounce, pulse, wiggle, breathe)
• Mentions matchedGeometryEffect or matchedTransitionSource
• Asks about reduce motion / animation accessibility
• Wants to sequence or chain animations
• Mentions withAnimation, animation completions, or Transaction

Decision Tree

Choose the right reference file based on what the user needs:

What are you animating?
│
├─ A state change (opacity, position, color)
│  └─ → core-animations.md
│     ├─ withAnimation { } — explicit animation
│     ├─ .animation(_:value:) — implicit animation
│     └─ Spring configuration — .spring, .bouncy, .snappy, .smooth
│
├─ A multi-step / sequenced animation
│  └─ → phase-keyframe-animators.md (PhaseAnimator)
│     └─ Cycles through discrete phases automatically or on trigger
│
├─ A complex multi-property animation (scale + rotation + offset)
│  └─ → phase-keyframe-animators.md (KeyframeAnimator)
│     └─ Timeline-based keyframes with per-property tracks
│
├─ A view appearing / disappearing
│  └─ → transitions.md
│     ├─ .transition() — insertion/removal
│     ├─ .contentTransition() — text/symbol changes
│     └─ .asymmetric() — different in/out
│
├─ A hero / zoom navigation transition
│  └─ → transitions.md (matchedTransitionSource section)
│     ├─ iOS 18+: matchedTransitionSource + .navigationTransition(.zoom)
│     └─ iOS 14+: matchedGeometryEffect (NOT for NavigationStack)
│
├─ An SF Symbol animation
│  └─ → symbol-effects.md
│     └─ .symbolEffect(.bounce), .pulse, .wiggle, .breathe, .rotate
│
└─ Spring physics / timing configuration
   └─ → core-animations.md (Spring Configurations section)

API Availability

Top 5 Mistakes — Quick Reference

Review Checklist

When reviewing animation code, verify:

• [ ] Reduce motion — animations respect AccessibilityMotionEffect or UIAccessibility.isReduceMotionEnabled; provide non-motion alternatives
• [ ] Duration limits — no animation exceeds ~0.5s for UI feedback; longer only for decorative/ambient effects
• [ ] Spring vs linear — springs for interactive/physical motion; linear/easeInOut only for opacity fades or progress indicators
• [ ] No deprecated APIs — .animation(.spring()) without value: is deprecated; .animation(nil) is replaced by withTransaction
• [ ] Correct spring generation — parameter names match the same API generation (never mix response with bounce)
• [ ] Completion handlers — using withAnimation(_:completionCriteria:_:completion:) (iOS 17+), not inventing .onAnimationCompleted
• [ ] Transition scope — .transition() only affects views inside if/switch controlled by state; not for views that are always present

Reference Files

Core Animations

Fundamentals of SwiftUI animation: withAnimation, spring configurations, completions, transactions, and timing curves.

withAnimation vs .animation Modifier

Two ways to animate state changes. Use one or the other — never both on the same property.

withAnimation (Explicit — Preferred)

Wraps a state change and animates all views that depend on that state:

Button("Toggle") {
    withAnimation(.spring) {
        isExpanded.toggle()
    }
}

Use when: you control the state change site (button tap, gesture, event).

.animation(_:value:) (Implicit)

Watches a value and animates whenever it changes:

Circle()
    .offset(y: isActive ? -20 : 0)
    .animation(.spring, value: isActive)

Use when: the state change comes from somewhere else (parent view, environment, binding).

Deprecated: .animation Without value:

// ❌ Deprecated in iOS 15 — animates ALL state changes, causes unexpected behavior
Circle()
    .animation(.spring())

// ✅ Always pass value:
Circle()
    .animation(.spring, value: isActive)

Spring Configurations

Three API generations exist. Never mix parameter names across generations.

Generation 1: Physics Parameters (iOS 13+)

Raw physics model. Rarely needed — hard to reason about visually.

Spring(mass: 1.0, stiffness: 100.0, damping: 10.0, initialVelocity: 0.0)

Generation 2: Response / Damping Fraction (iOS 13+)

The most common in existing codebases:

.spring(response: 0.5, dampingFraction: 0.7, blendDuration: 0)

Generation 3: Duration / Bounce (iOS 17+)

Simpler API. Use this for new code targeting iOS 17+.

.spring(duration: 0.5, bounce: 0.3)

Spring Presets (iOS 17+)

Use these instead of manual configuration when possible:

.spring            // Default spring — slight bounce, natural feel
.bouncy            // .spring(duration: 0.5, bounce: 0.3) — playful
.snappy            // .spring(duration: 0.3, bounce: 0.15) — quick, subtle bounce
.smooth            // .spring(duration: 0.5, bounce: 0.0) — no bounce, gentle settle

Migration Table

Anti-Patterns

// ❌ WRONG: Mixing generation 2 and 3 parameter names
.spring(response: 0.5, bounce: 0.3)   // Does NOT compile

// ❌ WRONG: Mixing generation 1 and 2
.spring(mass: 1.0, dampingFraction: 0.7)  // Does NOT compile

// ✅ Pick ONE generation:
.spring(response: 0.5, dampingFraction: 0.7)  // Gen 2
.spring(duration: 0.5, bounce: 0.3)            // Gen 3
.bouncy                                         // Gen 3 preset

Animation Completions (iOS 17+)

Run code after an animation finishes. Uses withAnimation with a completion closure.

withAnimation(.spring) {
    isExpanded = true
} completion: {
    showContent = true
}

Full signature:

withAnimation(
    _ animation: Animation,
    completionCriteria: AnimationCompletionCriteria = .logicallyComplete,
    _ body: () -> Void,
    completion: @Sendable () -> Void
)

Completion Criteria

// Wait for spring to fully settle before enabling interaction
withAnimation(.bouncy, completionCriteria: .removed) {
    cardOffset = .zero
} completion: {
    isInteractive = true
}

Anti-Pattern

// ❌ WRONG: This modifier does NOT exist
view.onAnimationCompleted(for: offset) { }

// ❌ WRONG: This modifier does NOT exist
view.onAnimationEnd { }

// ✅ Use withAnimation completion:
withAnimation(.default) {
    offset = targetOffset
} completion: {
    handleAnimationDone()
}

Transaction Control

withTransaction — Override Animation

Replace the animation for a specific state change:

var transaction = Transaction(animation: .none)
withTransaction(transaction) {
    // This state change happens instantly, no animation
    selectedTab = newTab
}

Disabling Animation

// Disable animation for a specific change
var transaction = Transaction()
transaction.disablesAnimations = true
withTransaction(transaction) {
    resetPosition()
}

// Or use withAnimation(.none) — simpler for one-off cases (iOS 17+)
withAnimation(.none) {
    resetPosition()
}

transaction Modifier

Override animations on a per-view basis:

Text(count, format: .number)
    .contentTransition(.numericText())
    .transaction { transaction in
        transaction.animation = .snappy
    }

Timing Curves

Non-spring animations for specific use cases (opacity fades, progress bars).

.linear                        // Constant speed
.linear(duration: 0.3)         // Constant speed, 0.3s

.easeIn                        // Slow start, fast end
.easeIn(duration: 0.3)

.easeOut                       // Fast start, slow end
.easeOut(duration: 0.3)

.easeInOut                     // Slow start and end
.easeInOut(duration: 0.3)

.timingCurve(0.2, 0.8, 0.2, 1, duration: 0.4)  // Custom cubic bezier

When to use timing curves vs springs:

• Springs: interactive elements, things that feel physical (cards, buttons, toggles)
• easeInOut: opacity fades, color transitions
• linear: progress indicators, continuous rotation

Animation Modifiers

Chain these onto any Animation value:

// Repeat forever (for loading spinners, pulsing effects)
.linear(duration: 1.0).repeatForever(autoreverses: false)

// Repeat a fixed number of times
.easeInOut(duration: 0.5).repeatCount(3, autoreverses: true)

// Delay before starting
.spring.delay(0.2)

// Change speed (2x faster)
.spring.speed(2.0)

Loading Spinner Example

struct Spinner: View {
    @State private var isRotating = false

    var body: some View {
        Image(systemName: "arrow.trianglehead.2.clockwise")
            .rotationEffect(.degrees(isRotating ? 360 : 0))
            .animation(
                .linear(duration: 1.0).repeatForever(autoreverses: false),
                value: isRotating
            )
            .onAppear {
                isRotating = true
            }
    }
}

Staggered Animation Example

ForEach(Array(items.enumerated()), id: \.element.id) { index, item in
    ItemRow(item: item)
        .opacity(isVisible ? 1 : 0)
        .offset(y: isVisible ? 0 : 20)
        .animation(
            .spring.delay(Double(index) * 0.05),
            value: isVisible
        )
}

Common Patterns

Animate on Appear

struct AppearAnimation: View {
    @State private var appeared = false

    var body: some View {
        ContentView()
            .opacity(appeared ? 1 : 0)
            .scaleEffect(appeared ? 1 : 0.8)
            .onAppear {
                withAnimation(.spring) {
                    appeared = true
                }
            }
    }
}

Animatable Modifier for Custom Properties

For properties SwiftUI doesn't natively animate (like text size, stroke dash):

struct CountingText: View, Animatable {
    var value: Double

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

    var body: some View {
        Text("\(Int(value))")
    }
}

Use withAnimation to drive the value change — SwiftUI interpolates animatableData each frame.

Phase & Keyframe Animators

Multi-step and timeline-based animations using PhaseAnimator and KeyframeAnimator (iOS 17+).

PhaseAnimator

Cycles through a sequence of discrete phases, applying different view modifiers at each phase.

API Shape

PhaseAnimator(
    _ phases: some Sequence,          // The phases to cycle through
    trigger: some Equatable,          // Optional: triggers one cycle (omit for continuous)
    content: (PlaceholderContentView<Self>, Phase) -> some View,
    animation: (Phase) -> Animation?  // Animation TO this phase
)

Critical: The content closure receives two parameters — the content proxy and the current phase. Not just the phase.

Auto-Advancing (Continuous Loop)

Omit trigger to loop forever. Phases must be CaseIterable.

enum PulsePhase: CaseIterable {
    case idle, scaled, rotated
}

struct PulsingIcon: View {
    var body: some View {
        PhaseAnimator(PulsePhase.allCases) { content, phase in
            content
                .scaleEffect(phase == .scaled ? 1.2 : 1.0)
                .rotationEffect(.degrees(phase == .rotated ? 15 : 0))
                .opacity(phase == .idle ? 0.8 : 1.0)
        } animation: { phase in
            switch phase {
            case .idle: .easeInOut(duration: 0.6)
            case .scaled: .spring(duration: 0.4, bounce: 0.3)
            case .rotated: .spring(duration: 0.3, bounce: 0.2)
            }
        }
    }
}

Trigger-Based (One Cycle)

Pass a trigger value. Each time it changes, the animator cycles through all phases once and returns to the first.

struct NotificationBadge: View {
    var count: Int

    var body: some View {
        PhaseAnimator(
            [false, true, false],
            trigger: count
        ) { content, phase in
            content
                .scaleEffect(phase ? 1.3 : 1.0)
                .brightness(phase ? 0.1 : 0)
        } animation: { phase in
            phase ? .spring(duration: 0.2, bounce: 0.5) : .spring(duration: 0.3)
        }
    }
}

Using an Array of Values

Phases don't have to be an enum — any Equatable sequence works:

PhaseAnimator([0.0, 1.0, 0.5, 1.0]) { content, opacity in
    content.opacity(opacity)
} animation: { _ in
    .easeInOut(duration: 0.4)
}

Anti-Patterns

// ❌ WRONG: Content closure takes ONE parameter (only phase)
PhaseAnimator(PulsePhase.allCases) { phase in
    Image(systemName: "star.fill")
        .scaleEffect(phase == .big ? 1.5 : 1.0)
}

// ✅ RIGHT: Content closure takes TWO parameters (content, phase)
PhaseAnimator(PulsePhase.allCases) { content, phase in
    content
        .scaleEffect(phase == .big ? 1.5 : 1.0)
}

// ❌ WRONG: Treating phase as a numeric value
PhaseAnimator([0.0, 1.0, 0.0]) { content, phase in
    content.opacity(phase)  // phase is Double here, this IS valid
}
// But if using an enum:
PhaseAnimator(PulsePhase.allCases) { content, phase in
    content.scaleEffect(phase)  // ❌ phase is PulsePhase, not a number
}

// ❌ WRONG: Missing animation closure (defaults to .default for all)
PhaseAnimator(PulsePhase.allCases) { content, phase in
    content.scaleEffect(phase == .big ? 1.5 : 1.0)
}
// ✅ Better: Provide animation per phase for intentional timing

KeyframeAnimator

Timeline-based animation with independent tracks for different properties. Each property follows its own keyframe sequence.

API Shape

KeyframeAnimator(
    initialValue: AnimationValues,       // Custom struct with animatable properties
    trigger: some Equatable,             // Triggers the animation
    content: (AnimationValues) -> some View,
    keyframes: (AnimationValues) -> some Keyframes
)

Step 1: Define an Animatable Values Struct

The struct holds all properties you want to animate. It does NOT need to conform to Animatable.

struct BounceValues {
    var scale: Double = 1.0
    var yOffset: Double = 0.0
    var rotation: Double = 0.0
}

Step 2: Build the Animator

struct BouncingLogo: View {
    @State private var trigger = false

    var body: some View {
        KeyframeAnimator(
            initialValue: BounceValues(),
            trigger: trigger
        ) { values in
            // content closure — read values, apply to view
            Image(systemName: "star.fill")
                .scaleEffect(values.scale)
                .offset(y: values.yOffset)
                .rotationEffect(.degrees(values.rotation))
        } keyframes: { _ in
            // keyframes closure — define tracks per property
            KeyframeTrack(\.scale) {
                SpringKeyframe(1.5, duration: 0.3)
                SpringKeyframe(1.0, duration: 0.3)
            }

            KeyframeTrack(\.yOffset) {
                LinearKeyframe(-30, duration: 0.2)
                SpringKeyframe(0, duration: 0.4, spring: .bouncy)
            }

            KeyframeTrack(\.rotation) {
                CubicKeyframe(15, duration: 0.15)
                CubicKeyframe(-15, duration: 0.15)
                CubicKeyframe(0, duration: 0.2)
            }
        }
        .onTapGesture {
            trigger.toggle()
        }
    }
}

Keyframe Types

KeyframeTrack(\.opacity) {
    MoveKeyframe(0.0)                          // Start invisible
    LinearKeyframe(1.0, duration: 0.3)         // Fade in linearly
    CubicKeyframe(0.5, duration: 0.2)          // Ease to half opacity
    SpringKeyframe(1.0, duration: 0.4)         // Spring back to full
}

Multi-Property Example

struct ShakeValues {
    var xOffset: Double = 0
    var angle: Double = 0
    var scale: Double = 1
}

struct ErrorShake: View {
    @State private var shakeTrigger = 0

    var body: some View {
        KeyframeAnimator(
            initialValue: ShakeValues(),
            trigger: shakeTrigger
        ) { values in
            TextField("Email", text: .constant(""))
                .offset(x: values.xOffset)
                .rotationEffect(.degrees(values.angle))
                .scaleEffect(values.scale)
        } keyframes: { _ in
            KeyframeTrack(\.xOffset) {
                LinearKeyframe(10, duration: 0.07)
                LinearKeyframe(-10, duration: 0.07)
                LinearKeyframe(8, duration: 0.07)
                LinearKeyframe(-8, duration: 0.07)
                LinearKeyframe(4, duration: 0.07)
                LinearKeyframe(0, duration: 0.07)
            }

            KeyframeTrack(\.angle) {
                LinearKeyframe(2, duration: 0.07)
                LinearKeyframe(-2, duration: 0.07)
                LinearKeyframe(1, duration: 0.07)
                LinearKeyframe(-1, duration: 0.07)
                LinearKeyframe(0, duration: 0.14)
            }

            KeyframeTrack(\.scale) {
                SpringKeyframe(1.05, duration: 0.15)
                SpringKeyframe(1.0, duration: 0.25)
            }
        }
    }
}

Continuous KeyframeAnimator

Omit trigger and add repeating: true for looping animations:

KeyframeAnimator(
    initialValue: FloatValues(),
    repeating: true
) { values in
    Circle()
        .offset(y: values.yOffset)
        .opacity(values.opacity)
} keyframes: { _ in
    KeyframeTrack(\.yOffset) {
        CubicKeyframe(-10, duration: 1.0)
        CubicKeyframe(0, duration: 1.0)
    }
    KeyframeTrack(\.opacity) {
        CubicKeyframe(0.5, duration: 1.0)
        CubicKeyframe(1.0, duration: 1.0)
    }
}

Anti-Patterns

// ❌ WRONG: Using a raw Double instead of a struct
KeyframeAnimator(initialValue: 0.0, trigger: trigger) { value in
    Circle().scaleEffect(value)
} keyframes: { _ in
    KeyframeTrack(\.self) {  // \.self works but limits to ONE property
        SpringKeyframe(1.5, duration: 0.3)
    }
}
// ✅ Use a struct so you can animate multiple properties independently

// ❌ WRONG: Key path into the view instead of the values struct
KeyframeTrack(\.scaleEffect) { ... }  // Does NOT compile
// ✅ Key path into your values struct
KeyframeTrack(\.scale) { ... }

// ❌ WRONG: Using withAnimation to drive keyframes
withAnimation {
    KeyframeAnimator(...)  // KeyframeAnimator manages its own timing
}
// ✅ Use the trigger parameter to start the animation

// ❌ WRONG: Forgetting duration on LinearKeyframe / CubicKeyframe
LinearKeyframe(1.0)  // Missing duration — won't compile
// ✅ Always provide duration
LinearKeyframe(1.0, duration: 0.3)
// Note: MoveKeyframe does NOT take a duration (it's instantaneous)

PhaseAnimator vs KeyframeAnimator

Choose PhaseAnimator when:

• You have discrete visual states (idle → active → settled)
• All properties change at the same time
• You want automatic looping with CaseIterable

Choose KeyframeAnimator when:

• Properties need different timing (scale peaks before rotation)
• You need precise timeline control
• You want spring physics on some properties and linear on others

CustomAnimation Protocol (iOS 17+)

For entirely custom animation curves. Rarely needed — prefer built-in springs and timing curves.

struct CustomBounce: CustomAnimation {
    var target: Double = 1.0

    func animate<V: VectorArithmetic>(
        value: V, time: TimeInterval, context: inout AnimationContext<V>
    ) -> V? {
        // Return nil when animation is done
        guard time < 1.0 else { return nil }
        // Return interpolated value
        let progress = time / 1.0
        let bounce = sin(progress * .pi * 3) * (1 - progress) * 0.3
        return value.scaled(by: 1.0 + bounce)
    }

    func shouldMerge<V: VectorArithmetic>(
        previous: Animation, value: V, time: TimeInterval,
        context: inout AnimationContext<V>
    ) -> Bool {
        // Return true to merge with in-flight animation of same type
        false
    }
}

// Usage
withAnimation(Animation(CustomBounce())) {
    isExpanded.toggle()
}

SF Symbol Effects

Animate SF Symbols using the .symbolEffect() modifier (iOS 17+). These are purpose-built animations — do not use withAnimation for symbol effects.

Available Effects

Three Usage Patterns

1. Continuous (Repeating)

Starts when the view appears and loops indefinitely. Pass the effect directly to .symbolEffect():

// Pulsing while loading
Image(systemName: "wifi")
    .symbolEffect(.pulse, isActive: isSearching)

// Variable color always running
Image(systemName: "antenna.radiowaves.left.and.right")
    .symbolEffect(.variableColor.iterative)

// Breathing while recording
Image(systemName: "mic.fill")
    .symbolEffect(.breathe, isActive: isRecording)

Use isActive: to start/stop the effect based on state.

2. One-Shot (Event-Based with value:)

Triggers once each time a value changes. Use the .symbolEffect(_:value:) modifier:

// Bounce on tap
@State private var bounceCount = 0

Image(systemName: "heart.fill")
    .symbolEffect(.bounce, value: bounceCount)
    .onTapGesture {
        bounceCount += 1
    }

// Wiggle on error
Image(systemName: "exclamationmark.triangle")
    .symbolEffect(.wiggle, value: errorCount)

// Rotate on refresh
Image(systemName: "arrow.clockwise")
    .symbolEffect(.rotate, value: refreshCount)

3. Content Transition (Symbol Swap)

Animate between different symbols using .contentTransition(.symbolEffect(.replace)):

Image(systemName: isPlaying ? "pause.fill" : "play.fill")
    .contentTransition(.symbolEffect(.replace))
    .animation(.smooth, value: isPlaying)

Image(systemName: isMuted ? "speaker.slash.fill" : "speaker.wave.2.fill")
    .contentTransition(.symbolEffect(.replace.downUp))

Replace directions: .replace, .replace.downUp, .replace.upUp, .replace.offUp

Effect Options

Speed and Repeat

Image(systemName: "bell.fill")
    .symbolEffect(.bounce, options: .speed(2.0), value: trigger)

Image(systemName: "bell.fill")
    .symbolEffect(.bounce, options: .repeat(3), value: trigger)

// Combine options
Image(systemName: "bell.fill")
    .symbolEffect(.bounce, options: .speed(1.5).repeat(2), value: trigger)

Non-Repeating (for continuous effects)

// Pulse exactly once, then stop
Image(systemName: "heart.fill")
    .symbolEffect(.pulse, options: .nonRepeating, value: trigger)

Variable Color Modes

// Iterative — layers animate one by one
.symbolEffect(.variableColor.iterative)

// Cumulative — layers build up
.symbolEffect(.variableColor.cumulative)

// Reversing — forward then backward
.symbolEffect(.variableColor.iterative.reversing)

// Hide inactive layers (instead of dimming)
.symbolEffect(.variableColor.iterative.hideInactiveLayers)

Anti-Patterns

// ❌ WRONG: Using withAnimation for symbol effects
withAnimation(.spring) {
    Image(systemName: "star.fill")
}
// Symbol effects are NOT driven by withAnimation — they have their own timing

// ✅ RIGHT: Use .symbolEffect modifier
Image(systemName: "star.fill")
    .symbolEffect(.bounce, value: trigger)

// ❌ WRONG: Using .animation() modifier for symbol swap
Image(systemName: isPlaying ? "pause.fill" : "play.fill")
    .animation(.spring, value: isPlaying)
// This animates the IMAGE view, not the SYMBOL content

// ✅ RIGHT: Use contentTransition for symbol swap
Image(systemName: isPlaying ? "pause.fill" : "play.fill")
    .contentTransition(.symbolEffect(.replace))

// ❌ WRONG: Applying symbolEffect to non-symbol views
Text("Hello")
    .symbolEffect(.bounce, value: trigger)  // No effect on Text
// symbolEffect only works on Image views with SF Symbols

Accessibility — Reduce Motion

Symbol effects automatically respect the system's Reduce Motion setting:

• Bounce, wiggle, rotate — suppressed entirely when Reduce Motion is on
• Pulse, breathe — reduced to opacity-only change
• Variable color — still plays (it's informational, not decorative)
• Replace — falls back to cross-fade

No manual handling needed for symbol effects — the system manages this automatically. However, if you use isActive: to show ongoing state, ensure the state is also communicated through non-motion means (label, color, VoiceOver):

Image(systemName: "wifi")
    .symbolEffect(.variableColor.iterative, isActive: isSearching)
    .accessibilityLabel(isSearching ? "Searching for networks" : "Wi-Fi")

Transitions

View insertion/removal transitions, matched geometry effects, navigation transitions, and content transitions.

View Transitions

Transitions define how a view appears and disappears when added to or removed from the view hierarchy via conditional rendering (if, switch, ForEach).

Built-in Transitions

.transition(.opacity)                   // Fade in/out (iOS 13+)
.transition(.slide)                     // Slide from leading edge (iOS 13+)
.transition(.scale)                     // Scale from center (iOS 13+)
.transition(.scale(scale: 0.5))         // Scale from 50%
.transition(.scale(scale: 0, anchor: .bottom))  // Scale from bottom
.transition(.move(edge: .bottom))       // Slide from specific edge (iOS 13+)
.transition(.move(edge: .trailing))
.transition(.offset(x: 0, y: 50))      // Move from offset position (iOS 13+)
.transition(.push(from: .bottom))       // Push from edge with depth (iOS 16+)
.transition(.blurReplace)               // Blur out old, blur in new (iOS 17+)
.transition(.blurReplace(.downUp))      // Directional blur replace
.transition(.blurReplace(.upUp))

Combined Transitions

// Both effects applied simultaneously
.transition(.opacity.combined(with: .scale))
.transition(.move(edge: .bottom).combined(with: .opacity))

Asymmetric Transitions

Different animation for insertion vs removal:

.transition(.asymmetric(
    insertion: .push(from: .bottom),
    removal: .opacity
))

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

Usage with Conditional Views

Transitions only work on views that are conditionally rendered:

VStack {
    if showDetail {
        DetailView()
            .transition(.slide)  // ✅ Works — view is added/removed
    }
}

VStack {
    DetailView()
        .opacity(showDetail ? 1 : 0)  // This is NOT a transition — it's an animation
        .transition(.slide)             // ❌ No effect — view is always present
}

Animate the state change to see the transition:

Button("Toggle") {
    withAnimation(.spring) {
        showDetail.toggle()
    }
}

Custom Transitions

Build custom transitions using ViewModifier:

struct SlideAndFade: ViewModifier {
    let isActive: Bool

    func body(content: Content) -> some View {
        content
            .offset(y: isActive ? 30 : 0)
            .opacity(isActive ? 0 : 1)
            .scaleEffect(isActive ? 0.9 : 1)
    }
}

extension AnyTransition {
    static var slideAndFade: AnyTransition {
        .modifier(
            active: SlideAndFade(isActive: true),
            identity: SlideAndFade(isActive: false)
        )
    }
}

// Usage
DetailView()
    .transition(.slideAndFade)

matchedGeometryEffect (iOS 14+)

Creates a visual connection between two views by matching their geometry (position, size). Used for shared element transitions within the same view hierarchy.

How It Works

Two views share an id and namespace. When one disappears and the other appears, SwiftUI animates the geometry change.

struct ExpandableCard: View {
    @Namespace private var animation
    @State private var isExpanded = false

    var body: some View {
        if isExpanded {
            ExpandedView()
                .matchedGeometryEffect(id: "card", in: animation)
                .onTapGesture {
                    withAnimation(.spring) {
                        isExpanded = false
                    }
                }
        } else {
            CompactView()
                .matchedGeometryEffect(id: "card", in: animation)
                .onTapGesture {
                    withAnimation(.spring) {
                        isExpanded = true
                    }
                }
        }
    }
}

Rules

1. @Namespace — must declare a namespace with @Namespace private var animation 2. Same id, same namespace — both views use the same id and in: namespace 3. Only one view at a time — at any given moment, only one view with a given id should be in the hierarchy (use if/else, not showing both) 4. isSource parameter — when both views exist simultaneously (e.g., overlay), set isSource: true on the source and isSource: false on the target

// When both views coexist — source dictates geometry
SmallPhoto()
    .matchedGeometryEffect(id: "photo", in: ns, isSource: true)

LargePhoto()
    .matchedGeometryEffect(id: "photo", in: ns, isSource: false)

Anti-Patterns

// ❌ WRONG: Both set isSource: true
view1.matchedGeometryEffect(id: "x", in: ns, isSource: true)
view2.matchedGeometryEffect(id: "x", in: ns, isSource: true)
// ✅ Only ONE should be isSource: true

// ❌ WRONG: Forgetting @Namespace
let animation = Namespace()  // This is wrong
// ✅ @Namespace private var animation

// ❌ WRONG: Using for NavigationStack push/pop transitions
NavigationLink { DetailView().matchedGeometryEffect(id: "item", in: ns) }
// matchedGeometryEffect does NOT work across NavigationStack push/pop
// ✅ Use matchedTransitionSource (iOS 18+) instead — see below

Navigation Transitions (iOS 18+)

matchedTransitionSource + navigationTransition(.zoom)

The correct way to create hero/zoom transitions with NavigationStack. Do not use matchedGeometryEffect for this.

struct GalleryView: View {
    @Namespace private var namespace
    let photos: [Photo]

    var body: some View {
        NavigationStack {
            ScrollView {
                LazyVGrid(columns: [GridItem(.adaptive(minimum: 100))]) {
                    ForEach(photos) { photo in
                        NavigationLink(value: photo) {
                            PhotoThumbnail(photo: photo)
                                .matchedTransitionSource(id: photo.id, in: namespace)
                        }
                    }
                }
            }
            .navigationDestination(for: Photo.self) { photo in
                PhotoDetailView(photo: photo)
                    .navigationTransition(.zoom(sourceID: photo.id, in: namespace))
            }
        }
    }
}

How It Differs from matchedGeometryEffect

Other Navigation Transitions

// Slide transition (default NavigationStack behavior)
.navigationTransition(.slide)

// Zoom from a source
.navigationTransition(.zoom(sourceID: id, in: namespace))

// Automatic — system chooses based on context
.navigationTransition(.automatic)

Customizing Zoom Appearance

PhotoThumbnail(photo: photo)
    .matchedTransitionSource(id: photo.id, in: namespace) { source in
        source
            .clipShape(.rect(cornerRadius: 12))
            .shadow(radius: 5)
    }

PhotoDetailView(photo: photo)
    .navigationTransition(.zoom(sourceID: photo.id, in: namespace))

Content Transitions

Animate the content inside a view without adding/removing the view itself.

Numeric Text (iOS 16+)

Animates number changes digit-by-digit:

Text(score, format: .number)
    .contentTransition(.numericText())
    .animation(.snappy, value: score)

With counting direction:

Text(value, format: .number)
    .contentTransition(.numericText(countsDown: value < previousValue))

Interpolate (iOS 16+)

Smoothly interpolates between text styles (color, size):

Text("Status")
    .foregroundStyle(isActive ? .green : .red)
    .fontWeight(isActive ? .bold : .regular)
    .contentTransition(.interpolate)
    .animation(.smooth, value: isActive)

Symbol Effect Replace (iOS 17+)

Animate SF Symbol changes:

Image(systemName: isPlaying ? "pause.fill" : "play.fill")
    .contentTransition(.symbolEffect(.replace))
    .animation(.smooth, value: isPlaying)

With direction:

.contentTransition(.symbolEffect(.replace.downUp))
.contentTransition(.symbolEffect(.replace.upUp))
.contentTransition(.symbolEffect(.replace.offUp))

Identity (No Transition)

Opt out of content transitions:

.contentTransition(.identity)

Accessibility — Reduce Motion

Always provide alternatives for users with reduced motion enabled.

Check Reduce Motion

@Environment(\.accessibilityReduceMotion) var reduceMotion

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

Conditional Animation

@Environment(\.accessibilityReduceMotion) var reduceMotion

func toggleDetail() {
    if reduceMotion {
        showDetail.toggle()  // No animation
    } else {
        withAnimation(.spring) {
            showDetail.toggle()
        }
    }
}

Simplified Transitions

Replace complex multi-step transitions with simple fades:

@Environment(\.accessibilityReduceMotion) var reduceMotion

var transition: AnyTransition {
    if reduceMotion {
        .opacity
    } else {
        .asymmetric(
            insertion: .push(from: .bottom).combined(with: .opacity),
            removal: .push(from: .top).combined(with: .opacity)
        )
    }
}