swiftui-debugging

SwiftUI Performance Debugging

Systematic guide for diagnosing and fixing SwiftUI performance problems: unnecessary view re-evaluations, identity issues, expensive body computations, and lazy loading mistakes.

When This Skill Activates

Use this skill when the user:

• Reports slow or janky SwiftUI views
• Sees excessive view re-renders or body re-evaluations
• Asks about Self._printChanges() or view debugging
• Has scrolling performance issues with lists or grids
• Asks why a view keeps updating when nothing changed
• Mentions @Observable or ObservableObject performance differences
• Wants to understand SwiftUI view identity or diffing
• Uses AnyView and asks about performance implications
• Has a hang or stutter traced to SwiftUI rendering

Decision Tree

What SwiftUI performance problem are you seeing?
|
+- Views re-render when they should not
|  +- Read body-reevaluation.md
|     +- Self._printChanges() to identify which property changed
|     +- @Observable vs ObservableObject observation differences
|     +- Splitting views to narrow observation scope
|
+- Scrolling is slow / choppy (lists, grids)
|  +- Read lazy-loading.md
|     +- VStack vs LazyVStack, ForEach without lazy container
|     +- List prefetching, grid cell reuse
|
+- Views lose state unexpectedly / animate when they should not
|  +- Read view-identity.md
|     +- Structural vs explicit identity
|     +- .id() misuse, conditional view branching
|
+- Known pitfall (AnyView, DateFormatter in body, etc.)
|  +- Read common-pitfalls.md
|     +- AnyView type erasure, object creation in body
|     +- Over-observation, expensive computations
|
+- General "my SwiftUI app is slow" (unknown cause)
|  +- Start with body-reevaluation.md, then common-pitfalls.md
|  +- Use Instruments SwiftUI template (see Debugging Tools below)

API Availability

API / Technique	Minimum Version	Reference
Self._printChanges()	iOS 15	body-reevaluation.md
@Observable	iOS 17 / macOS 14	body-reevaluation.md
@ObservableObject	iOS 13	body-reevaluation.md
LazyVStack / LazyHStack	iOS 14	lazy-loading.md
LazyVGrid / LazyHGrid	iOS 14	lazy-loading.md
.id() modifier	iOS 13	view-identity.md
Instruments SwiftUI template	Xcode 14+	SKILL.md
os_signpost	iOS 12	SKILL.md

Top 5 Mistakes -- Quick Reference

#	Mistake	Fix	Details
1	Large ForEach inside VStack or ScrollView without lazy container	Wrap in LazyVStack -- eager VStack creates all views upfront	lazy-loading.md
2	Using AnyView to erase types	Use @ViewBuilder, Group, or concrete generic types -- AnyView defeats diffing	common-pitfalls.md
3	Creating objects in body (DateFormatter(), NumberFormatter())	Use static let shared instances or @State for mutable objects	common-pitfalls.md
4	Observing entire model when only one property is needed	Split into smaller @Observable objects or extract subviews	body-reevaluation.md
5	Unstable .id() values causing full view recreation every render	Use stable identifiers (database IDs, UUIDs), never array indices or random values	view-identity.md

Debugging Tools

Self._printChanges()

Add to any view body to see what triggered re-evaluation:

var body: some View {
    let _ = Self._printChanges()
    // ... view content
}

Output reads: ViewName: @self, @identity, _propertyName changed. See body-reevaluation.md for full interpretation guide.

Instruments SwiftUI Template

1. Xcode > Product > Profile (Cmd+I)
2. Choose SwiftUI template (includes View Body, View Properties, Core Animation Commits)
3. Record, reproduce the slow interaction, stop
4. View Body lane shows which views had their body evaluated and how often
5. View Properties lane shows which properties changed

os_signpost for Custom Measurement

import os

private let perfLog = OSLog(subsystem: "com.app.perf", category: "SwiftUI")

var body: some View {
    let _ = os_signpost(.event, log: perfLog, name: "MyView.body")
    // ... view content
}

View in Instruments with the os_signpost instrument to count body evaluations per second.

Review Checklist

View Identity

• No unstable .id() values (random, Date(), array index on mutable arrays)
• Conditional branches (if/else) do not cause unnecessary view destruction
• ForEach uses stable, unique identifiers from the model

Body Re-evaluation

• Views observe only the properties they actually use
• @Observable classes preferred over ObservableObject (iOS 17+)
• No unnecessary @State changes that trigger body re-evaluation
• Large views split into smaller subviews to narrow observation scope

Lazy Loading

• Large collections use LazyVStack / LazyHStack, not VStack / HStack
• List or lazy stack used for 50+ items
• No .frame(maxHeight: .infinity) on children inside lazy containers (defeats laziness)

Common Pitfalls

• No AnyView type erasure (use @ViewBuilder or Group)
• No object allocation in body (DateFormatter, NSPredicate, view models)
• Expensive computations moved to background with task { } or Task.detached
• Images use AsyncImage or .resizable() with proper sizing, not raw UIImage decoding in body

Reference Files

File	Content
view-identity.md	Structural vs explicit identity, .id() usage, conditional branching
body-reevaluation.md	What triggers body, _printChanges(), @Observable vs ObservableObject
lazy-loading.md	Lazy vs eager containers, List, ForEach, grid performance
common-pitfalls.md	AnyView, object creation in body, over-observation, expensive computations
../profiling/SKILL.md	General Instruments profiling (Time Profiler, Memory, Energy)