1# SwiftUI Performance Patterns Reference
2 
3## Table of Contents
4 
5- [Performance Optimization](#performance-optimization)
6- [Anti-Patterns](#anti-patterns)
7- [Summary Checklist](#summary-checklist)
8 
9## Performance Optimization
10 
11### 1. Avoid Redundant State Updates
12 
13SwiftUI doesn't compare values before triggering updates:
14 
15```swift
16// BAD - triggers update even if value unchanged
17.onReceive(publisher) { value in
18    self.currentValue = value  // Always triggers body re-evaluation
19}
20 
21// GOOD - only update when different
22.onReceive(publisher) { value in
23    if self.currentValue != value {
24        self.currentValue = value
25    }
26}
27```
28 
29### 2. Optimize Hot Paths
30 
31Hot paths are frequently executed code (scroll handlers, animations, gestures):
32 
33```swift
34// BAD - updates state on every scroll position change
35.onPreferenceChange(ScrollOffsetKey.self) { offset in
36    shouldShowTitle = offset.y <= -32  // Fires constantly during scroll!
37}
38 
39// GOOD - only update when threshold crossed
40.onPreferenceChange(ScrollOffsetKey.self) { offset in
41    let shouldShow = offset.y <= -32
42    if shouldShow != shouldShowTitle {
43        shouldShowTitle = shouldShow  // Fires only when crossing threshold
44    }
45}
46```
47 
48### 3. Pass Only What Views Need
49 
50**Avoid passing large "config" or "context" objects.** Pass only the specific values each view needs.
51 
52```swift
53// Good - pass specific values
54ThemeSelector(theme: config.theme)
55FontSizeSlider(fontSize: config.fontSize)
56 
57// Avoid - passing entire config (creates broad dependency)
58ThemeSelector(config: config)  // Notified of ALL config changes
59```
60 
61With `ObservableObject`, any `@Published` change triggers all observers. With `@Observable`, views update only when accessed properties change, but passing entire objects still creates broader dependencies than necessary.
62 
63### 4. Use Equatable Views
64 
65For views with expensive bodies, conform to `Equatable`:
66 
67```swift
68struct ExpensiveView: View, Equatable {
69    let data: SomeData
70 
71    static func == (lhs: Self, rhs: Self) -> Bool {
72        lhs.data.id == rhs.data.id  // Custom equality check
73    }
74 
75    var body: some View {
76        // Expensive computation
77    }
78}
79 
80// Usage
81ExpensiveView(data: data)
82    .equatable()  // Use custom equality
83```
84 
85**Caution**: If you add new state or dependencies to your view, remember to update your `==` function!
86 
87### 5. POD Views for Fast Diffing
88 
89**POD (Plain Old Data) views use `memcmp` for fastest diffing.** A view is POD if it only contains simple value types and no property wrappers.
90 
91```swift
92// POD view - fastest diffing
93struct FastView: View {
94    let title: String
95    let count: Int
96    
97    var body: some View {
98        Text("\(title): \(count)")
99    }
100}
101 
102// Non-POD view - uses reflection or custom equality
103struct SlowerView: View {
104    let title: String
105    @State private var isExpanded = false  // Property wrapper makes it non-POD
106    
107    var body: some View {
108        Text(title)
109    }
110}
111```
112 
113**Advanced Pattern**: Wrap expensive non-POD views in POD parent views:
114 
115```swift
116// POD wrapper for fast diffing
117struct ExpensiveView: View {
118    let value: Int
119    
120    var body: some View {
121        ExpensiveViewInternal(value: value)
122    }
123}
124 
125// Internal view with state
126private struct ExpensiveViewInternal: View {
127    let value: Int
128    @State private var item: Item?
129    
130    var body: some View {
131        // Expensive rendering
132    }
133}
134```
135 
136**Why**: The POD parent uses fast `memcmp` comparison. Only when `value` changes does the internal view get diffed.
137 
138### 6. Lazy Loading
139 
140Use lazy containers for large collections:
141 
142```swift
143// BAD - creates all views immediately
144ScrollView {
145    VStack {
146        ForEach(items) { item in
147            ExpensiveRow(item: item)
148        }
149    }
150}
151 
152// GOOD - creates views on demand
153ScrollView {
154    LazyVStack {
155        ForEach(items) { item in
156            ExpensiveRow(item: item)
157        }
158    }
159}
160```
161 
162**iOS 26+ note**: Nested scroll views containing lazy stacks now automatically defer loading their children until they are about to appear, matching the behavior of top-level lazy stacks. This benefits patterns like horizontal photo carousels inside a vertical scroll view.
163 
164> Source: "What's new in SwiftUI" (WWDC25, session 256)
165 
166### 7. Task Cancellation
167 
168Cancel async work when view disappears:
169 
170```swift
171struct DataView: View {
172    @State private var data: [Item] = []
173 
174    var body: some View {
175        List(data) { item in
176            Text(item.name)
177        }
178        .task {
179            // Automatically cancelled when view disappears
180            data = await fetchData()
181        }
182    }
183}
184```
185 
186### 8. Debug View Updates
187 
188**Use `Self._printChanges()` or `Self._logChanges()` to debug unexpected view updates.**
189 
190```swift
191struct DebugView: View {
192    @State private var count = 0
193    @State private var name = ""
194    
195    var body: some View {
196        #if DEBUG
197        let _ = Self._logChanges()  // Xcode 15.1+: logs to com.apple.SwiftUI subsystem
198        #endif
199        
200        VStack {
201            Text("Count: \(count)")
202            Text("Name: \(name)")
203        }
204    }
205}
206```
207 
208- `Self._printChanges()`: Prints which properties changed to standard output.
209- `Self._logChanges()` (iOS 17+): Logs to the `com.apple.SwiftUI` subsystem with category "Changed Body Properties", using `os_log` for structured output.
210 
211Both print `@self` when the view value itself changed and `@identity` when the view's persistent data was recycled.
212 
213**Why**: This helps identify which state changes are causing view updates. Isolating redraw triggers into single-responsibility subviews is often the fix -- extracting a subview means SwiftUI can skip its body when its inputs haven't changed.
214 
215### 9. Eliminate Unnecessary Dependencies
216 
217**Narrow state scope to reduce update fan-out.** Instead of passing an entire `@Observable` model to a row view (which creates a dependency on all accessed properties), pass only the specific values the view needs as `let` properties.
218 
219```swift
220// Bad - broad dependency on entire model
221struct ItemRow: View {
222    @Environment(AppModel.self) private var model
223    let item: Item
224    var body: some View { Text(item.name).foregroundStyle(model.theme.primaryColor) }
225}
226 
227// Good - narrow dependency
228struct ItemRow: View {
229    let item: Item
230    let themeColor: Color
231    var body: some View { Text(item.name).foregroundStyle(themeColor) }
232}
233```
234 
235**Avoid storing frequently-changing values in the environment.** Every write to *any* environment key forces every view that reads *any* key in that subtree to be checked. So a high-frequency value (scroll offset, window/container size, drag translation, per-frame animation progress, timer ticks, hover location) flowing into an `@Entry` or `.environment(\.key, value)` becomes an invalidation storm.
236 
237Instead, hold the value in an `@Observable` model and expose a **coarsened** value — a boolean threshold rather than the raw measurement — so views invalidate only when crossing a meaningful boundary:
238 
239```swift
240@MainActor @Observable
241final class ViewportModel {
242    var width: CGFloat = 0 { didSet { isWide = width > 600 } }
243    private(set) var isWide = false   // readers invalidate only when this flips
244}
245```
246 
247The same shape applies per row in a list: storing the raw offset on a model and having every row read it still invalidates all visible rows every frame. Give each item its own `@Observable` whose properties track only that item's derived state (e.g. `isVisible`), so each row invalidates at most twice (enter/leave) regardless of scroll speed — see item #10 below.
248 
249For purely visual effects driven by scroll position (opacity, scale, rotation), prefer `scrollTransition` or `visualEffect(in:)` — they push the per-frame work to the renderer and skip body re-evaluation entirely. Reach for the `@Observable` + coarsening pattern only when the scroll-derived value must drive non-rendering logic (model updates, prefetches, sibling state).
250 
251> Source: "Optimize SwiftUI performance with Instruments" (WWDC25, session 306)
252 
253### 10. @Observable Dependency Granularity
254 
255**Consider per-item `@Observable` state holders (one per row/item) to narrow update scope.** When multiple list items share a dependency on the same `@Observable` array, changing one element causes all items to re-evaluate their bodies.
256 
257```swift
258// BAD - all item views depend on the full favorites array
259@Observable
260class ModelData {
261    var favorites: [Landmark] = []
262 
263    func isFavorite(_ landmark: Landmark) -> Bool {
264        favorites.contains(landmark)
265    }
266}
267 
268struct LandmarkRow: View {
269    let landmark: Landmark
270    @Environment(ModelData.self) private var model
271 
272    var body: some View {
273        HStack {
274            Text(landmark.name)
275            if model.isFavorite(landmark) {
276                Image(systemName: "heart.fill")
277            }
278        }
279    }
280}
281 
282// GOOD - each item has its own observable view model
283@Observable
284class LandmarkViewModel {
285    var isFavorite: Bool = false
286}
287 
288struct LandmarkRow: View {
289    let landmark: Landmark
290    let viewModel: LandmarkViewModel
291 
292    var body: some View {
293        HStack {
294            Text(landmark.name)
295            if viewModel.isFavorite {
296                Image(systemName: "heart.fill")
297            }
298        }
299    }
300}
301```
302 
303**Why**: With the bad pattern, toggling one favorite marks the entire array as changed, causing every `LandmarkRow` to re-run its body. With per-item view models, only the toggled item's body runs.
304 
305> Source: "Optimize SwiftUI performance with Instruments" (WWDC25, session 306)
306 
307### 11. Off-Main-Thread Closures
308 
309**SwiftUI may call certain closures on a background thread for performance.** These closures must be `Sendable` and should avoid accessing `@MainActor`-isolated state directly. Instead, capture needed values in the closure's capture list.
310 
311Closures that may run off the main thread:
312- `Shape.path(in:)`
313- `visualEffect` closure
314- `Layout` protocol methods
315- `onGeometryChange` transform closure
316 
317```swift
318// BAD - accessing @MainActor state directly
319.visualEffect { content, geometry in
320    content.blur(radius: self.pulse ? 5 : 0)  // Compiler error: @MainActor isolated
321}
322 
323// GOOD - capture the value
324.visualEffect { [pulse] content, geometry in
325    content.blur(radius: pulse ? 5 : 0)
326}
327```
328 
329> Source: "Explore concurrency in SwiftUI" (WWDC25, session 266)
330 
331### 12. Common Performance Issues
332 
333**Be aware of common performance bottlenecks in SwiftUI:**
334 
335- View invalidation storms from broad state changes
336- Unstable identity in lists causing excessive diffing
337- Heavy work in `body` (formatting, sorting, image decoding)
338- Layout thrash from deep stacks or preference chains
339 
340**When performance issues arise**, suggest the user profile with Instruments (SwiftUI template) to identify specific bottlenecks.
341 
342## Anti-Patterns
343 
344### 1. Creating Objects in Body
345 
346```swift
347// BAD - creates new formatter every body call
348var body: some View {
349    let formatter = DateFormatter()
350    formatter.dateStyle = .long
351    return Text(formatter.string(from: date))
352}
353 
354// GOOD - static or stored formatter
355private static let dateFormatter: DateFormatter = {
356    let f = DateFormatter()
357    f.dateStyle = .long
358    return f
359}()
360 
361var body: some View {
362    Text(Self.dateFormatter.string(from: date))
363}
364```
365 
366### 2. Heavy Computation in Body
367 
368**Keep view body simple and pure.** Avoid side effects, dispatching, or complex logic.
369 
370```swift
371// BAD - sorts array every body call
372var body: some View {
373    List(items.sorted { $0.name < $1.name }) { item in Text(item.name) }
374}
375 
376// GOOD - compute once, update via onChange or a computed property in the model
377@State private var sortedItems: [Item] = []
378 
379var body: some View {
380    List(sortedItems) { item in Text(item.name) }
381        .onChange(of: items) { _, newItems in
382            sortedItems = newItems.sorted { $0.name < $1.name }
383        }
384}
385```
386 
387Move sorting, filtering, and formatting into models or computed properties. The `body` should be a pure structural representation of state.
388 
389### 3. Unnecessary State
390 
391```swift
392// BAD - derived state stored separately
393@State private var items: [Item] = []
394@State private var itemCount: Int = 0  // Unnecessary!
395 
396// GOOD - compute derived values
397@State private var items: [Item] = []
398 
399var itemCount: Int { items.count }  // Computed property
400```
401 
402## Summary Checklist
403 
404- [ ] State updates check for value changes before assigning
405- [ ] Hot paths minimize state updates
406- [ ] Pass only needed values to views (avoid large config objects)
407- [ ] Large lists use `LazyVStack`/`LazyHStack`
408- [ ] No object creation in `body`
409- [ ] Heavy computation moved out of `body`
410- [ ] Body kept simple and pure (no side effects)
411- [ ] Derived state computed, not stored
412- [ ] Use `Self._logChanges()` or `Self._printChanges()` to debug unexpected updates
413- [ ] Equatable conformance for expensive views (when appropriate)
414- [ ] Consider POD view wrappers for advanced optimization
415- [ ] Consider using granular @Observable dependencies for list items (smaller observable units per row when it measurably reduces updates)
416- [ ] Frequently-changing values not stored in the environment
417- [ ] Sendable closures (Shape, visualEffect, Layout) capture values instead of accessing @MainActor state
418