---
name: rshankras/swiftui-debugging
source: https://app.decimal.ai/s/rshankras-swiftui-debugging@1/SKILL.md
source_sha256: 0de45178cb7f
---

# 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

## The Performance Loop

Every investigation follows the same loop: **symptom -> measure -> identify -> optimize -> RE-MEASURE**. The last step is the one people skip -- an "optimization" that was never re-measured is a guess, and SwiftUI guesses are wrong often enough (a fix can shift cost elsewhere) that the loop is not optional. Never close a performance issue on the strength of the diff alone.

## 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 |
| Redesigned SwiftUI instrument | Xcode 26 / Instruments 26 | 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 |

## Lists, Tables, and ForEach: Identity Is the Cost Model

`List` and `Table` gather **all identifiers eagerly** at load -- even though row *views* are lazy. Cheap, precomputed IDs mean fast loads; an `id:` key path that computes or hashes something expensive runs for every element before anything renders.

**The row-count equation:** rows = elements x views-per-element, and views-per-element must be a **constant** the framework can read without executing your closures.

- ❌ No `if` filters and no `AnyView` inside `ForEach` -- both make views-per-element non-constant, forcing SwiftUI to run every closure just to count rows (and defeating `List`'s constant-count optimizations).
- ✅ Filter in the data, not the view -- and **cache the filtered collection in the model**: an inline `items.filter { ... }` in `body` re-runs linearly on every single body evaluation.
- ✅ For `Table`, prefer the streamlined `ForEach(collection)` initializer (no `id:`, no per-row closure gymnastics) -- it keeps row counts statically constant.

## Common Slow-Update Causes

When a body or update shows up slow in the profile, it is almost always one of these:

1. **Expensive dynamic-property initialization** -- e.g. a `@StateObject`/`@State` object doing I/O in its initializer
2. **Work in `body`** -- string interpolation/formatting, sorting, filtering
3. **Heap allocations in `body`** -- formatters, predicates, intermediate arrays
4. **Bundle/resource lookups in `body`** -- `Bundle.main` searches, decoding images synchronously

Move loading and expensive derivation to `.task` (or the model), then re-measure.

**Scope dependencies tightly -- but not obsessively.** Pass the child view the `Image` it renders, not the whole model object, so unrelated model changes stop invalidating it. Don't over-rotate: splitting a huge struct into dozens of single-property parameters costs more in plumbing than it saves. `@Observable` already narrows invalidation to the properties a body actually *reads* -- lean on that first.

## Debugging Tools

### Self._printChanges()

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

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

Output reads: `ViewName: @self, @identity, _propertyName changed.` Shorthand: `@self` = the view's *value* changed (parent rebuilt it), a named property = that specific dependency changed. See body-reevaluation.md for the full interpretation guide.

Also callable from LLDB without editing code -- pause in a view context and run:

```
(lldb) expression Self._printChanges()
```

Remove it before shipping -- it has real runtime cost.

### 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

### The Redesigned SwiftUI Instrument (Instruments 26 -- WWDC25 306)

Requires Xcode 26 and recent OS releases on the profiled device (trace-recording support lives in the OS). Cmd+I builds Release and opens Instruments; the **SwiftUI template** bundles the SwiftUI instrument, **Time Profiler**, and **Hangs + Hitches** instruments. Start here when the question is "which body is blowing the frame budget."

**Why body time matters:** each frame, the app handles events, runs the bodies of changed views, and must finish before the frame deadline; a body that overruns delays the whole train and the previous frame stays on screen too long -- a hitch. Two failure shapes blow the deadline the same way: (1) one long body update, (2) many individually-fast but unnecessary updates in one frame (WWDC25 306).

**Top-level lanes:**

| Lane | Meaning |
|------|---------|
| Update Groups | When SwiftUI is doing *any* work. If CPU spikes while this lane is empty, the problem is **outside SwiftUI** -- switch to the general profiling skill |
| Long View Body Updates | `body` properties taking too long |
| Long Representable Updates | UIView/UIViewController/NSView representable updates taking too long |
| Other Long Updates | All other long SwiftUI work |

Color coding: long updates are **orange or red by likelihood of contributing to a hitch or hang -- investigate red first**; normal updates are gray. Long updates at the very start of a trace are launch-time initial hierarchy builds -- expected, they won't hitch; don't chase them (WWDC25 306).

**Workflow for a long body:**
1. Expand the SwiftUI track -> select the **View Body Updates** subtrack; the detail pane summarizes every body that ran (process -> module -> view type)
2. Switch the summary dropdown to **Long View Body Updates** to filter to offenders with counts
3. Hover a view name -> arrow -> **Show Updates** -> right-click one -> **Set Inspection Range and Zoom**
4. Select the **Time Profiler** track to see exactly what the CPU did during that one body run (Option-click expands the main-thread stack; Cmd+F to find your body frame)
5. Fix, re-record, and confirm the view vanished from the Long View Body Updates summary

The classic find (the session's demo): a computed property read in `body` created a `NumberFormatter` + `MeasurementFormatter` and formatted a string on every body run, per visible row. Fix: create formatters **once** (stored property on the model/manager), precompute strings into an **ID-keyed cache**, and let `body` do a dictionary lookup (WWDC25 306). See common-pitfalls.md for the general rule.

### Cause & Effect Graph: Why Did Body Run? (WWDC25 306)

Backtraces explain imperative UIKit updates but not SwiftUI -- a SwiftUI backtrace is recursive AttributeGraph frames and never says why *your* view updated. So "why did body run?" really means "**what marked my body outdated?**" -- which is exactly what the instrument's **Cause & Effect Graph** answers (hover-arrow on a view name -> Show Cause & Effect Graph):

- Nodes are updates, one icon per kind (view body, state change, gesture, `@Observable` change, environment); **blue nodes = your code / your interactions**; the graph reads left (cause) -> right (effect)
- Edges are labeled **"update"** (caused a re-run) or **"Creation"** (made the view first appear)
- A **dimmed icon** = the view was notified and checked but its **body did not run**
- Selecting a state-change node shows a **backtrace of where the value was set**

The demo bug it exposed: every row's `body` called `isFavorite(landmark)`, which read the shared `landmarks` array on an `@Observable` model -- so **every row depended on the whole array**, and one tap re-ran every visible row's body.

```swift
// ❌ Every row reads the shared array -> @Observable makes every row depend on it
func isFavorite(_ landmark: Landmark) -> Bool {
    favoritesCollection.landmarks.contains(landmark)   // whole-array dependency
}

// ✅ Per-item @Observable view model -> each row depends only on its own flag
@Observable class ViewModel { var isFavorite: Bool = false }

@ObservationIgnored private var viewModels: [Landmark.ID: ViewModel] = [:]
// ^ @ObservationIgnored: don't observe the dictionary itself, only each model

func isFavorite(_ landmark: Landmark) -> Bool {
    viewModel(for: landmark).isFavorite   // body's read = narrow dependency
}
func addFavorite(_ landmark: Landmark) {
    favoritesCollection.landmarks.append(landmark)
    viewModel(for: landmark).isFavorite = true
}
```

Verified in the trace: **2 taps = exactly 2 body updates**. Rule: **make data dependencies as granular as the UI that renders them** (WWDC25 306).

**Environment rule:** `EnvironmentValues` is one value-type struct, and every view using `@Environment` depends on the whole struct. Any environment change notifies all such views; each compares its own key's value -- body only re-runs if it changed, but **the comparison itself costs time in every reading view**. Never store rapidly-changing values (geometry, timers) in the environment (WWDC25 306). The graph distinguishes **External Environment** nodes (changed outside SwiftUI, e.g. color scheme) from **EnvironmentWriter** nodes (changed via `.environment(...)`).

### os_signpost for Custom Measurement

```swift
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](view-identity.md) | Structural vs explicit identity, `.id()` usage, conditional branching |
| [body-reevaluation.md](body-reevaluation.md) | What triggers body, `_printChanges()`, `@Observable` vs `ObservableObject` |
| [lazy-loading.md](lazy-loading.md) | Lazy vs eager containers, `List`, `ForEach`, grid performance |
| [common-pitfalls.md](common-pitfalls.md) | `AnyView`, object creation in body, over-observation, expensive computations |
| [../profiling/SKILL.md](../profiling/SKILL.md) | General Instruments profiling (Time Profiler, Memory, Energy) |
| [../../swiftui/data-flow/SKILL.md](../../swiftui/data-flow/SKILL.md) | The identity/lifetime mental model behind all of the above -- read it when fixes feel like guesswork |