1# SwiftUI Animation Basics
2 
3Core animation concepts, implicit vs explicit animations, timing curves, and performance patterns.
4 
5## Table of Contents
6- [Core Concepts](#core-concepts)
7- [Implicit Animations](#implicit-animations)
8- [Explicit Animations](#explicit-animations)
9- [Animation Placement](#animation-placement)
10- [Selective Animation](#selective-animation)
11- [Timing Curves](#timing-curves)
12- [Animation Performance](#animation-performance)
13- [Disabling Animations](#disabling-animations)
14- [Debugging](#debugging)
15 
16---
17 
18## Core Concepts
19 
20State changes trigger view updates. SwiftUI provides mechanisms to animate these changes.
21 
22**Animation Process:**
231. State change triggers view tree re-evaluation
242. SwiftUI compares new tree to current render tree
253. Animatable properties are identified and interpolated (~60 fps)
26 
27**Key Characteristics:**
28- Animations are additive and cancelable
29- Always start from current render tree state
30- Blend smoothly when interrupted
31 
32---
33 
34## Implicit Animations
35 
36Use `.animation(_:value:)` to animate when a specific value changes.
37 
38```swift
39// GOOD - uses value parameter
40Rectangle()
41    .frame(width: isExpanded ? 200 : 100, height: 50)
42    .animation(.spring, value: isExpanded)
43    .onTapGesture { isExpanded.toggle() }
44 
45// BAD - deprecated, animates all changes unexpectedly
46Rectangle()
47    .frame(width: isExpanded ? 200 : 100, height: 50)
48    .animation(.spring)  // Deprecated!
49```
50 
51---
52 
53## Explicit Animations
54 
55Use `withAnimation` for event-driven state changes.
56 
57```swift
58// GOOD - explicit animation
59Button("Toggle") {
60    withAnimation(.spring) {
61        isExpanded.toggle()
62    }
63}
64 
65// BAD - no animation context
66Button("Toggle") {
67    isExpanded.toggle()  // Abrupt change
68}
69```
70 
71**When to use which:**
72- **Implicit**: Animations tied to specific value changes, precise view tree scope
73- **Explicit**: Event-driven animations (button taps, gestures)
74 
75---
76 
77## Animation Placement
78 
79Place animation modifiers after the properties they should animate.
80 
81```swift
82// GOOD - animation after properties
83Rectangle()
84    .frame(width: isExpanded ? 200 : 100, height: 50)
85    .foregroundStyle(isExpanded ? .blue : .red)
86    .animation(.default, value: isExpanded)  // Animates both
87 
88// BAD - animation before properties
89Rectangle()
90    .animation(.default, value: isExpanded)  // Too early!
91    .frame(width: isExpanded ? 200 : 100, height: 50)
92```
93 
94---
95 
96## Selective Animation
97 
98Animate only specific properties using multiple animation modifiers or scoped animations.
99 
100```swift
101// GOOD - selective animation
102Rectangle()
103    .frame(width: isExpanded ? 200 : 100, height: 50)
104    .animation(.spring, value: isExpanded)  // Animate size
105    .foregroundStyle(isExpanded ? .blue : .red)
106    .animation(nil, value: isExpanded)  // Don't animate color
107 
108// iOS 17+ scoped animation
109Rectangle()
110    .foregroundStyle(isExpanded ? .blue : .red)  // Not animated
111    .animation(.spring) {
112        $0.frame(width: isExpanded ? 200 : 100, height: 50)  // Animated
113    }
114```
115 
116---
117 
118## Timing Curves
119 
120### Built-in Curves
121 
122| Curve | Use Case |
123|-------|----------|
124| `.spring` | Interactive elements, most UI |
125| `.easeInOut` | Appearance changes |
126| `.bouncy` | Playful feedback (iOS 17+) |
127| `.linear` | Progress indicators only |
128 
129### Modifiers
130 
131```swift
132.animation(.default.speed(2.0), value: flag)  // 2x faster
133.animation(.default.delay(0.5), value: flag)  // Delayed start
134.animation(.default.repeatCount(3, autoreverses: true), value: flag)
135```
136 
137### Good vs Bad Timing
138 
139```swift
140// GOOD - appropriate timing for interaction type
141Button("Tap") {
142    withAnimation(.spring(response: 0.3, dampingFraction: 0.7)) {
143        isActive.toggle()
144    }
145}
146.scaleEffect(isActive ? 0.95 : 1.0)
147 
148// BAD - too slow for button feedback
149Button("Tap") {
150    withAnimation(.easeInOut(duration: 1.0)) {  // Way too slow!
151        isActive.toggle()
152    }
153}
154 
155// BAD - linear feels robotic
156Rectangle()
157    .animation(.linear(duration: 0.5), value: isActive)  // Mechanical
158```
159 
160---
161 
162## Animation Performance
163 
164### Prefer Transforms Over Layout
165 
166```swift
167// GOOD - GPU accelerated transforms
168Rectangle()
169    .frame(width: 100, height: 100)
170    .scaleEffect(isActive ? 1.5 : 1.0)  // Fast
171    .offset(x: isActive ? 50 : 0)        // Fast
172    .rotationEffect(.degrees(isActive ? 45 : 0))  // Fast
173    .animation(.spring, value: isActive)
174 
175// BAD - layout changes are expensive
176Rectangle()
177    .frame(width: isActive ? 150 : 100, height: isActive ? 150 : 100)  // Expensive
178    .padding(isActive ? 50 : 0)  // Expensive
179```
180 
181### Narrow Animation Scope
182 
183```swift
184// GOOD - animation scoped to specific subview
185VStack {
186    HeaderView()  // Not affected
187    ExpandableContent(isExpanded: isExpanded)
188        .animation(.spring, value: isExpanded)  // Only this
189    FooterView()  // Not affected
190}
191 
192// BAD - animation at root
193VStack {
194    HeaderView()
195    ExpandableContent(isExpanded: isExpanded)
196    FooterView()
197}
198.animation(.spring, value: isExpanded)  // Animates everything
199```
200 
201### Avoid Animation in Hot Paths
202 
203```swift
204// GOOD - gate by threshold
205.onPreferenceChange(ScrollOffsetKey.self) { offset in
206    let shouldShow = offset.y < -50
207    if shouldShow != showTitle {  // Only when crossing threshold
208        withAnimation(.easeOut(duration: 0.2)) {
209            showTitle = shouldShow
210        }
211    }
212}
213 
214// BAD - animating every scroll change
215.onPreferenceChange(ScrollOffsetKey.self) { offset in
216    withAnimation {  // Fires constantly!
217        self.offset = offset.y
218    }
219}
220```
221 
222---
223 
224## Disabling Animations
225 
226```swift
227// GOOD - disable with transaction
228Text("Count: \(count)")
229    .transaction { $0.animation = nil }
230 
231// GOOD - disable from parent context
232DataView()
233    .transaction { $0.disablesAnimations = true }
234 
235// BAD - hacky zero duration
236Text("Count: \(count)")
237    .animation(.linear(duration: 0), value: count)  // Hacky
238```
239 
240---
241 
242## Debugging
243 
244```swift
245// Slow down for inspection
246#if DEBUG
247.animation(.linear(duration: 3.0).speed(0.2), value: isExpanded)
248#else
249.animation(.spring, value: isExpanded)
250#endif
251 
252// Debug modifier to log values
253struct AnimationDebugModifier: ViewModifier, Animatable {
254    var value: Double
255    var animatableData: Double {
256        get { value }
257        set {
258            value = newValue
259            print("Animation: \(newValue)")
260        }
261    }
262    func body(content: Content) -> some View {
263        content.opacity(value)
264    }
265}
266```
267 
268---
269 
270## Quick Reference
271 
272### Do
273- Use `.animation(_:value:)` with value parameter
274- Use `withAnimation` for event-driven animations
275- Prefer transforms over layout changes
276- Scope animations narrowly
277- Choose appropriate timing curves
278 
279### Don't
280- Use deprecated `.animation(_:)` without value
281- Animate layout properties in hot paths
282- Apply broad animations at root level
283- Use linear timing for UI (feels robotic)
284- Animate on every frame in scroll handlers
285