1# SwiftUI Transitions
2 
3Transitions for view insertion/removal, custom transitions, and the Animatable protocol.
4 
5## Table of Contents
6- [Property Animations vs Transitions](#property-animations-vs-transitions)
7- [Basic Transitions](#basic-transitions)
8- [Asymmetric Transitions](#asymmetric-transitions)
9- [Custom Transitions](#custom-transitions)
10- [Identity and Transitions](#identity-and-transitions)
11- [The Animatable Protocol](#the-animatable-protocol)
12 
13---
14 
15## Property Animations vs Transitions
16 
17**Property animations**: Interpolate values on views that exist before AND after state change.
18 
19**Transitions**: Animate views being inserted or removed from the render tree.
20 
21```swift
22// Property animation - same view, different properties
23Rectangle()
24    .frame(width: isExpanded ? 200 : 100, height: 50)
25    .animation(.spring, value: isExpanded)
26 
27// Transition - view inserted/removed
28if showDetail {
29    DetailView()
30        .transition(.scale)
31}
32```
33 
34---
35 
36## Basic Transitions
37 
38### Critical: Transitions Require Animation Context
39 
40```swift
41// GOOD - animation outside conditional
42VStack {
43    Button("Toggle") { showDetail.toggle() }
44    if showDetail {
45        DetailView()
46            .transition(.slide)
47    }
48}
49.animation(.spring, value: showDetail)
50 
51// GOOD - explicit animation
52Button("Toggle") {
53    withAnimation(.spring) {
54        showDetail.toggle()
55    }
56}
57if showDetail {
58    DetailView()
59        .transition(.scale.combined(with: .opacity))
60}
61 
62// BAD - animation inside conditional (removed with view!)
63if showDetail {
64    DetailView()
65        .transition(.slide)
66        .animation(.spring, value: showDetail)  // Won't work on removal!
67}
68 
69// BAD - no animation context
70Button("Toggle") {
71    showDetail.toggle()  // No animation
72}
73if showDetail {
74    DetailView()
75        .transition(.slide)  // Ignored - just appears/disappears
76}
77```
78 
79### Built-in Transitions
80 
81| Transition | Effect |
82|------------|--------|
83| `.opacity` | Fade in/out (default) |
84| `.scale` | Scale up/down |
85| `.slide` | Slide from leading edge |
86| `.move(edge:)` | Move from specific edge |
87| `.offset(x:y:)` | Move by offset amount |
88 
89### Combining Transitions
90 
91```swift
92// Parallel - both simultaneously
93.transition(.slide.combined(with: .opacity))
94 
95// Chained
96.transition(.scale.combined(with: .opacity).combined(with: .offset(y: 20)))
97```
98 
99---
100 
101## Asymmetric Transitions
102 
103Different animations for insertion vs removal.
104 
105```swift
106// GOOD - different animations for insert/remove
107if showCard {
108    CardView()
109        .transition(
110            .asymmetric(
111                insertion: .scale.combined(with: .opacity),
112                removal: .move(edge: .bottom).combined(with: .opacity)
113            )
114        )
115}
116 
117// BAD - same transition when different behaviors needed
118if showCard {
119    CardView()
120        .transition(.slide)  // Same both ways - may feel awkward
121}
122```
123 
124---
125 
126## Custom Transitions
127 
128### Pre-iOS 17
129 
130```swift
131struct BlurModifier: ViewModifier {
132    var radius: CGFloat
133    func body(content: Content) -> some View {
134        content.blur(radius: radius)
135    }
136}
137 
138extension AnyTransition {
139    static func blur(radius: CGFloat) -> AnyTransition {
140        .modifier(
141            active: BlurModifier(radius: radius),
142            identity: BlurModifier(radius: 0)
143        )
144    }
145}
146 
147// Usage
148.transition(.blur(radius: 10))
149```
150 
151### iOS 17+ (Transition Protocol)
152 
153```swift
154struct BlurTransition: Transition {
155    var radius: CGFloat
156 
157    func body(content: Content, phase: TransitionPhase) -> some View {
158        content
159            .blur(radius: phase.isIdentity ? 0 : radius)
160            .opacity(phase.isIdentity ? 1 : 0)
161    }
162}
163 
164// Usage
165.transition(BlurTransition(radius: 10))
166```
167 
168### Good vs Bad Custom Transitions
169 
170```swift
171// GOOD - reusable transition
172if showContent {
173    ContentView()
174        .transition(BlurTransition(radius: 10))
175}
176 
177// BAD - inline logic (won't animate on removal!)
178if showContent {
179    ContentView()
180        .blur(radius: showContent ? 0 : 10)  // Not a transition
181        .opacity(showContent ? 1 : 0)
182}
183```
184 
185---
186 
187## Identity and Transitions
188 
189View identity changes trigger transitions, not property animations.
190 
191```swift
192// Triggers transition - different branches have different identities
193if isExpanded {
194    Rectangle().frame(width: 200, height: 50)
195} else {
196    Rectangle().frame(width: 100, height: 50)
197}
198 
199// Triggers transition - .id() changes identity
200Rectangle()
201    .id(flag)  // Different identity when flag changes
202    .transition(.scale)
203 
204// Property animation - same view, same identity
205Rectangle()
206    .frame(width: isExpanded ? 200 : 100, height: 50)
207    .animation(.spring, value: isExpanded)
208```
209 
210---
211 
212## The Animatable Protocol
213 
214Enables custom property interpolation during animations.
215 
216### Protocol Definition
217 
218```swift
219protocol Animatable {
220    associatedtype AnimatableData: VectorArithmetic
221    var animatableData: AnimatableData { get set }
222}
223```
224 
225### Basic Implementation
226 
227```swift
228// GOOD - explicit animatableData
229struct ShakeModifier: ViewModifier, Animatable {
230    var shakeCount: Double
231 
232    var animatableData: Double {
233        get { shakeCount }
234        set { shakeCount = newValue }
235    }
236 
237    func body(content: Content) -> some View {
238        content.offset(x: sin(shakeCount * .pi * 2) * 10)
239    }
240}
241 
242extension View {
243    func shake(count: Int) -> some View {
244        modifier(ShakeModifier(shakeCount: Double(count)))
245    }
246}
247 
248// Usage
249Button("Shake") { shakeCount += 3 }
250    .shake(count: shakeCount)
251    .animation(.default, value: shakeCount)
252 
253// BAD - missing animatableData (silent failure!)
254struct BadShakeModifier: ViewModifier {
255    var shakeCount: Double
256    // Missing animatableData! Uses EmptyAnimatableData
257 
258    func body(content: Content) -> some View {
259        content.offset(x: sin(shakeCount * .pi * 2) * 10)
260    }
261}
262// Animation jumps to final value instead of interpolating
263```
264 
265### Multiple Properties with AnimatablePair
266 
267```swift
268// GOOD - AnimatablePair for two properties
269struct ComplexModifier: ViewModifier, Animatable {
270    var scale: CGFloat
271    var rotation: Double
272 
273    var animatableData: AnimatablePair<CGFloat, Double> {
274        get { AnimatablePair(scale, rotation) }
275        set {
276            scale = newValue.first
277            rotation = newValue.second
278        }
279    }
280 
281    func body(content: Content) -> some View {
282        content
283            .scaleEffect(scale)
284            .rotationEffect(.degrees(rotation))
285    }
286}
287 
288// GOOD - nested AnimatablePair for 3+ properties
289struct ThreePropertyModifier: ViewModifier, Animatable {
290    var x: CGFloat
291    var y: CGFloat
292    var rotation: Double
293 
294    var animatableData: AnimatablePair<AnimatablePair<CGFloat, CGFloat>, Double> {
295        get { AnimatablePair(AnimatablePair(x, y), rotation) }
296        set {
297            x = newValue.first.first
298            y = newValue.first.second
299            rotation = newValue.second
300        }
301    }
302 
303    func body(content: Content) -> some View {
304        content
305            .offset(x: x, y: y)
306            .rotationEffect(.degrees(rotation))
307    }
308}
309```
310 
311---
312 
313## Quick Reference
314 
315### Do
316- Place transitions outside conditional structures
317- Use `withAnimation` or `.animation` outside the `if`
318- Implement `animatableData` explicitly for custom Animatable
319- Use `AnimatablePair` for multiple animated properties
320- Use asymmetric transitions when insert/remove need different effects
321 
322### Don't
323- Put animation modifiers inside conditionals for transitions
324- Forget `animatableData` implementation (silent failure)
325- Use inline blur/opacity instead of proper transitions
326- Expect property animation when view identity changes
327