1# SwiftUI Advanced Animations
2 
3Transactions, phase animations (iOS 17+), keyframe animations (iOS 17+), completion handlers (iOS 17+), and `@Animatable` macro (iOS 26+).
4 
5## Table of Contents
6- [Transactions](#transactions)
7- [Phase Animations (iOS 17+)](#phase-animations-ios-17)
8- [Keyframe Animations (iOS 17+)](#keyframe-animations-ios-17)
9- [Animation Completion Handlers (iOS 17+)](#animation-completion-handlers-ios-17)
10- [@Animatable Macro (iOS 26+)](#animatable-macro-ios-26)
11 
12---
13 
14## Transactions
15 
16The underlying mechanism for all animations in SwiftUI.
17 
18### Basic Usage
19 
20```swift
21// withAnimation is shorthand for withTransaction
22withAnimation(.default) { flag.toggle() }
23 
24// Equivalent explicit transaction
25var transaction = Transaction(animation: .default)
26withTransaction(transaction) { flag.toggle() }
27```
28 
29### The .transaction Modifier
30 
31```swift
32Rectangle()
33    .frame(width: flag ? 100 : 50, height: 50)
34    .transaction { t in
35        t.animation = .default
36    }
37```
38 
39**Note:** This behaves like the deprecated `.animation(_:)` without value parameter - it animates on every state change.
40 
41### Animation Precedence
42 
43**Implicit animations override explicit animations** (later in view tree wins).
44 
45```swift
46Button("Tap") {
47    withAnimation(.linear) { flag.toggle() }
48}
49.animation(.bouncy, value: flag)  // .bouncy wins!
50```
51 
52### Disabling Animations
53 
54```swift
55// Prevent implicit animations from overriding
56.transaction { t in
57    t.disablesAnimations = true
58}
59 
60// Remove animation entirely
61.transaction { $0.animation = nil }
62```
63 
64### Custom Transaction Keys (iOS 17+)
65 
66Pass metadata through transactions.
67 
68```swift
69struct ChangeSourceKey: TransactionKey {
70    static let defaultValue: String = "unknown"
71}
72 
73extension Transaction {
74    var changeSource: String {
75        get { self[ChangeSourceKey.self] }
76        set { self[ChangeSourceKey.self] = newValue }
77    }
78}
79 
80// Set source
81var transaction = Transaction(animation: .default)
82transaction.changeSource = "server"
83withTransaction(transaction) { flag.toggle() }
84 
85// Read in view tree
86.transaction { t in
87    if t.changeSource == "server" {
88        t.animation = .smooth
89    } else {
90        t.animation = .bouncy
91    }
92}
93```
94 
95---
96 
97## Phase Animations (iOS 17+)
98 
99Cycle through discrete phases automatically. Each phase change is a separate animation.
100 
101### Basic Usage
102 
103```swift
104// GOOD - triggered phase animation
105Button("Shake") { trigger += 1 }
106    .phaseAnimator(
107        [0.0, -10.0, 10.0, -5.0, 5.0, 0.0],
108        trigger: trigger
109    ) { content, offset in
110        content.offset(x: offset)
111    }
112 
113// Infinite loop (no trigger)
114Circle()
115    .phaseAnimator([1.0, 1.2, 1.0]) { content, scale in
116        content.scaleEffect(scale)
117    }
118```
119 
120### Enum Phases (Recommended for Clarity)
121 
122```swift
123// GOOD - enum phases are self-documenting
124enum BouncePhase: CaseIterable {
125    case initial, up, down, settle
126 
127    var scale: CGFloat {
128        switch self {
129        case .initial: 1.0
130        case .up: 1.2
131        case .down: 0.9
132        case .settle: 1.0
133        }
134    }
135}
136 
137Circle()
138    .phaseAnimator(BouncePhase.allCases, trigger: trigger) { content, phase in
139        content.scaleEffect(phase.scale)
140    }
141```
142 
143### Custom Timing Per Phase
144 
145```swift
146.phaseAnimator([0, -20, 20], trigger: trigger) { content, offset in
147    content.offset(x: offset)
148} animation: { phase in
149    switch phase {
150    case -20: .bouncy
151    case 20: .linear
152    default: .smooth
153    }
154}
155```
156 
157### Good vs Bad
158 
159```swift
160// GOOD - use phaseAnimator for multi-step sequences
161.phaseAnimator([0, -10, 10, 0], trigger: trigger) { content, offset in
162    content.offset(x: offset)
163}
164 
165// BAD - manual DispatchQueue sequencing
166Button("Animate") {
167    withAnimation(.easeOut(duration: 0.1)) { offset = -10 }
168    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
169        withAnimation { offset = 10 }
170    }
171    DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
172        withAnimation { offset = 0 }
173    }
174}
175```
176 
177---
178 
179## Keyframe Animations (iOS 17+)
180 
181Precise timing control with exact values at specific times.
182 
183### Basic Usage
184 
185```swift
186Button("Bounce") { trigger += 1 }
187    .keyframeAnimator(
188        initialValue: AnimationValues(),
189        trigger: trigger
190    ) { content, value in
191        content
192            .scaleEffect(value.scale)
193            .offset(y: value.verticalOffset)
194    } keyframes: { _ in
195        KeyframeTrack(\.scale) {
196            SpringKeyframe(1.2, duration: 0.15)
197            SpringKeyframe(0.9, duration: 0.1)
198            SpringKeyframe(1.0, duration: 0.15)
199        }
200        KeyframeTrack(\.verticalOffset) {
201            LinearKeyframe(-20, duration: 0.15)
202            LinearKeyframe(0, duration: 0.25)
203        }
204    }
205 
206struct AnimationValues {
207    var scale: CGFloat = 1.0
208    var verticalOffset: CGFloat = 0
209}
210```
211 
212### Keyframe Types
213 
214| Type | Behavior |
215|------|----------|
216| `CubicKeyframe` | Smooth interpolation |
217| `LinearKeyframe` | Straight-line interpolation |
218| `SpringKeyframe` | Spring physics |
219| `MoveKeyframe` | Instant jump (no interpolation) |
220 
221### Multiple Synchronized Tracks
222 
223Tracks run **in parallel**, each animating one property.
224 
225```swift
226// GOOD - bell shake with synchronized rotation and scale
227struct BellAnimation {
228    var rotation: Double = 0
229    var scale: CGFloat = 1.0
230}
231 
232Image(systemName: "bell.fill")
233    .keyframeAnimator(
234        initialValue: BellAnimation(),
235        trigger: trigger
236    ) { content, value in
237        content
238            .rotationEffect(.degrees(value.rotation))
239            .scaleEffect(value.scale)
240    } keyframes: { _ in
241        KeyframeTrack(\.rotation) {
242            CubicKeyframe(15, duration: 0.1)
243            CubicKeyframe(-15, duration: 0.1)
244            CubicKeyframe(10, duration: 0.1)
245            CubicKeyframe(-10, duration: 0.1)
246            CubicKeyframe(0, duration: 0.1)
247        }
248        KeyframeTrack(\.scale) {
249            CubicKeyframe(1.1, duration: 0.25)
250            CubicKeyframe(1.0, duration: 0.25)
251        }
252    }
253 
254// BAD - manual timer-based animation
255Image(systemName: "bell.fill")
256    .onTapGesture {
257        withAnimation(.easeOut(duration: 0.1)) { rotation = 15 }
258        DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
259            withAnimation { rotation = -15 }
260        }
261        // ... more manual timing - error prone
262    }
263```
264 
265### KeyframeTimeline (iOS 17+)
266 
267Query animation values directly for testing or non-SwiftUI use.
268 
269```swift
270let timeline = KeyframeTimeline(initialValue: AnimationValues()) {
271    KeyframeTrack(\.scale) {
272        CubicKeyframe(1.2, duration: 0.25)
273        CubicKeyframe(1.0, duration: 0.25)
274    }
275}
276 
277let midpoint = timeline.value(time: 0.25)
278print(midpoint.scale)  // Value at 0.25 seconds
279```
280 
281---
282 
283## Animation Completion Handlers (iOS 17+)
284 
285Execute code when animations finish.
286 
287### With withAnimation
288 
289```swift
290// GOOD - completion with withAnimation
291Button("Animate") {
292    withAnimation(.spring) {
293        isExpanded.toggle()
294    } completion: {
295        showNextStep = true
296    }
297}
298```
299 
300### With Transaction (For Reexecution)
301 
302```swift
303// GOOD - completion fires on every trigger change
304Circle()
305    .scaleEffect(bounceCount % 2 == 0 ? 1.0 : 1.2)
306    .transaction(value: bounceCount) { transaction in
307        transaction.animation = .spring
308        transaction.addAnimationCompletion {
309            message = "Bounce \(bounceCount) complete"
310        }
311    }
312 
313// BAD - completion only fires ONCE (no value parameter)
314Circle()
315    .scaleEffect(bounceCount % 2 == 0 ? 1.0 : 1.2)
316    .animation(.spring, value: bounceCount)
317    .transaction { transaction in  // No value!
318        transaction.addAnimationCompletion {
319            completionCount += 1  // Only fires once, ever
320        }
321    }
322```
323 
324---
325 
326## @Animatable Macro (iOS 26+)
327 
328The `@Animatable` macro auto-synthesizes `animatableData` from all animatable stored properties, eliminating verbose manual conformance. Use `@AnimatableIgnored` to exclude properties that should not animate.
329 
330### Before (Manual)
331 
332```swift
333struct Wedge: Shape {
334    var startAngle: Angle
335    var endAngle: Angle
336    var drawClockwise: Bool
337 
338    var animatableData: AnimatablePair<Double, Double> {
339        get { AnimatablePair(startAngle.radians, endAngle.radians) }
340        set {
341            startAngle = .radians(newValue.first)
342            endAngle = .radians(newValue.second)
343        }
344    }
345 
346    func path(in rect: CGRect) -> Path { /* ... */ }
347}
348```
349 
350### After (@Animatable)
351 
352```swift
353@Animatable
354struct Wedge: Shape {
355    var startAngle: Angle
356    var endAngle: Angle
357    @AnimatableIgnored var drawClockwise: Bool
358 
359    func path(in rect: CGRect) -> Path { /* ... */ }
360}
361```
362 
363### When to Use
364- **Prefer `@Animatable`** for any custom `Shape`, `AnimatableModifier`, or type conforming to `Animatable` with multiple properties
365- **Use `@AnimatableIgnored`** for properties that control behavior but should not interpolate (e.g., directions, flags, identifiers)
366- The macro works with any type conforming to `Animatable`, not just `Shape`
367 
368> Source: "What's new in SwiftUI" (WWDC25, session 256)
369 
370---
371 
372## Quick Reference
373 
374### Transactions (All iOS versions)
375- `withTransaction` is the explicit form of `withAnimation`
376- Implicit animations override explicit (later in view tree wins)
377- Use `disablesAnimations` to prevent override
378- Use `.transaction { $0.animation = nil }` to remove animation
379 
380### Custom Transaction Keys (iOS 17+)
381- Pass metadata through animation system via `TransactionKey`
382 
383### Phase Animations (iOS 17+)
384- Use for multi-step sequences returning to start
385- Prefer enum phases for clarity
386- Each phase change is a separate animation
387- Use `trigger` parameter for one-shot animations
388 
389### Keyframe Animations (iOS 17+)
390- Use for precise timing control
391- Tracks run in parallel
392- Use `KeyframeTimeline` for testing/advanced use
393- Prefer over manual DispatchQueue timing
394 
395### Completion Handlers (iOS 17+)
396- Use `withAnimation(.animation) { } completion: { }` for one-shot completion handlers
397- Use `.transaction(value:)` for handlers that should refire on every value change
398- Without `value:` parameter, completion only fires once
399 
400### @Animatable Macro (iOS 26+)
401- Use `@Animatable` to auto-synthesize `animatableData` from stored properties
402- Use `@AnimatableIgnored` to exclude non-animatable properties
403- Replaces verbose manual `animatableData` getters/setters
404