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

Top 5 Mistakes -- Quick Reference

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

Body Re-evaluation

Understanding what triggers SwiftUI to call a view's body property, how to diagnose unnecessary re-evaluations, and how to minimize wasted work.

What Triggers body Re-evaluation

SwiftUI calls body when it detects that a view's dependencies have changed. Dependencies include:

Key insight: body being called does not necessarily mean the view re-renders on screen. SwiftUI diffs the output of body against the previous output and only updates what changed. However, calling body itself has a cost -- especially for complex view hierarchies.

Self._printChanges()

The most important debugging tool for re-evaluation. Add it as the first line in body:

struct ItemDetailView: View {
    let item: Item
    @State private var isEditing = false
    @Environment(\.colorScheme) private var colorScheme

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

Reading the Output

Output format: ViewName: _dependency1, _dependency2 changed.

@self changed -- What It Means

@self changed means the parent view's body was called, which recreated this view's struct. Even if all property values are identical, SwiftUI may still call body because the struct was freshly allocated.

This is the most common source of "unnecessary" re-evaluations. Fix it by ensuring the parent does not needlessly recreate child views.

Reducing @self Changes

// ❌ Parent rebuilds child every time its own body runs
struct ParentView: View {
    @State private var counter = 0

    var body: some View {
        VStack {
            Text("Count: \(counter)")
            Button("+1") { counter += 1 }
            ExpensiveChildView()  // @self changes every time counter changes
        }
    }
}

// ✅ Extract child so its body only runs when its own deps change
struct ParentView: View {
    @State private var counter = 0

    var body: some View {
        VStack {
            CounterSection(counter: $counter)
            ExpensiveChildView()  // Now in its own struct, isolated from counter
        }
    }
}

struct CounterSection: View {
    @Binding var counter: Int

    var body: some View {
        VStack {
            Text("Count: \(counter)")
            Button("+1") { counter += 1 }
        }
    }
}

@Observable vs ObservableObject

This is the single largest performance improvement available in modern SwiftUI.

ObservableObject: Whole-Object Observation (iOS 13+)

ObservableObject notifies all observing views when any @Published property changes:

// Every view observing this object re-evaluates when ANY property changes
class UserStore: ObservableObject {
    @Published var name = ""           // Change triggers all observers
    @Published var email = ""          // Change triggers all observers
    @Published var avatarURL: URL?     // Change triggers all observers
    @Published var preferences = Preferences()  // Change triggers all observers
}

struct NameLabel: View {
    @ObservedObject var store: UserStore

    var body: some View {
        let _ = Self._printChanges()
        // This body runs when email, avatarURL, or preferences change too!
        Text(store.name)
    }
}

@Observable: Per-Property Observation (iOS 17+)

@Observable tracks which properties each view's body actually reads and only notifies when those specific properties change:

@Observable
class UserStore {
    var name = ""
    var email = ""
    var avatarURL: URL?
    var preferences = Preferences()
}

struct NameLabel: View {
    var store: UserStore

    var body: some View {
        let _ = Self._printChanges()
        // Only re-evaluates when store.name changes
        // Changes to email, avatarURL, preferences do NOT trigger this view
        Text(store.name)
    }
}

Migration Benefit

@Observable Gotchas

Reading a property outside body does not create observation:

@Observable class Model {
    var value = 0
}

struct MyView: View {
    var model: Model

    // ❌ This read happens in init, not body -- no observation established
    var label: String { "Value: \(model.value)" }

    var body: some View {
        // ✅ Must read model.value inside body (directly or via computed property called from body)
        Text("Value: \(model.value)")
    }
}

Computed properties that read observed properties do establish observation when called from body:

@Observable class Model {
    var firstName = ""
    var lastName = ""

    var fullName: String { "\(firstName) \(lastName)" }
}

struct NameView: View {
    var model: Model

    var body: some View {
        // ✅ This observes both firstName and lastName
        // because fullName reads them, and fullName is called from body
        Text(model.fullName)
    }
}

Minimizing Re-evaluations

Strategy 1: Extract Subviews

The most effective technique. Each extracted subview only re-evaluates when its own dependencies change:

// ❌ Monolithic: entire view re-evaluates when any state changes
struct ProfileView: View {
    @State private var isEditingName = false
    @State private var isEditingBio = false
    var user: User

    var body: some View {
        VStack {
            // All of this re-evaluates when isEditingBio changes
            HStack {
                Text(user.name)
                Button("Edit") { isEditingName.toggle() }
            }
            // All of this re-evaluates when isEditingName changes
            HStack {
                Text(user.bio)
                Button("Edit") { isEditingBio.toggle() }
            }
        }
    }
}

// ✅ Split: each section only re-evaluates for its own state
struct ProfileView: View {
    var user: User

    var body: some View {
        VStack {
            NameSection(name: user.name)
            BioSection(bio: user.bio)
        }
    }
}

struct NameSection: View {
    let name: String
    @State private var isEditing = false

    var body: some View {
        HStack {
            Text(name)
            Button("Edit") { isEditing.toggle() }
        }
    }
}

struct BioSection: View {
    let bio: String
    @State private var isEditing = false

    var body: some View {
        HStack {
            Text(bio)
            Button("Edit") { isEditing.toggle() }
        }
    }
}

Strategy 2: Use EquatableView or Equatable Conformance

Tell SwiftUI to skip body if properties are equal:

struct ExpensiveView: View, Equatable {
    let data: LargeDataSet

    static func == (lhs: Self, rhs: Self) -> Bool {
        lhs.data.id == rhs.data.id && lhs.data.version == rhs.data.version
    }

    var body: some View {
        // Complex rendering that should only happen when data truly changes
        ComplexChart(data: data)
    }
}

// Usage: .equatable() tells SwiftUI to use the Equatable conformance
ExpensiveView(data: chartData)
    .equatable()

Strategy 3: Move State Down

Keep @State as close to the view that uses it as possible:

// ❌ State at the top causes the entire tree to re-evaluate
struct ContentView: View {
    @State private var searchText = ""  // Every keystroke re-evaluates everything

    var body: some View {
        NavigationStack {
            VStack {
                SearchBar(text: $searchText)
                ResultsList(query: searchText)
                // ... many other views that don't need searchText
                SidePanel()
                Footer()
            }
        }
    }
}

// ✅ Encapsulate search state in a dedicated view
struct ContentView: View {
    var body: some View {
        NavigationStack {
            VStack {
                SearchSection()  // Owns its own @State
                SidePanel()      // Not affected by search keystrokes
                Footer()         // Not affected by search keystrokes
            }
        }
    }
}

struct SearchSection: View {
    @State private var searchText = ""

    var body: some View {
        VStack {
            SearchBar(text: $searchText)
            ResultsList(query: searchText)
        }
    }
}

Counting Body Evaluations

Instruments SwiftUI Template

The View Body instrument counts how many times each view type's body is called:

1. Xcode > Product > Profile (Cmd+I) 2. Choose SwiftUI template 3. Record while reproducing the slow interaction 4. The View Body lane shows evaluation counts per view type 5. Sort by count to find views that evaluate most frequently

Manual Counting with os_signpost

import os

private let logger = Logger(subsystem: "com.app", category: "ViewBody")

struct MyView: View {
    var body: some View {
        let _ = logger.debug("MyView.body evaluated")
        // ... view content
    }
}

Filter Console output by your subsystem to see evaluation frequency.

What Counts Are Acceptable

Environment Changes

Environment values like colorScheme, dynamicTypeSize, and locale affect every view in the subtree. When they change, a large portion of the view tree re-evaluates.

This is normal and expected -- but avoid reading environment values in views that do not need them:

// ❌ Reads colorScheme even though it does not use it
struct ItemRow: View {
    @Environment(\.colorScheme) private var colorScheme
    let item: Item

    var body: some View {
        Text(item.title)  // Does not actually use colorScheme
    }
}

// ✅ Only read environment values you actually use in body
struct ItemRow: View {
    let item: Item

    var body: some View {
        Text(item.title)
    }
}

Common SwiftUI Performance Pitfalls

Specific anti-patterns that cause SwiftUI performance problems, with concrete before/after fixes for each.

1. AnyView Type Erasure

The Problem

AnyView wraps a view in a type-erased container. SwiftUI uses type information for its diffing algorithm -- when types are erased, SwiftUI cannot efficiently diff and must do more work:

• Cannot use structural identity (all AnyView instances have the same type)
• Cannot skip diffing subtrees when the type has not changed
• Prevents compile-time optimization of the view hierarchy

Before (Slow)

// ❌ AnyView defeats SwiftUI's diffing optimization
func makeView(for item: Item) -> AnyView {
    switch item.kind {
    case .text:
        return AnyView(TextItemView(item: item))
    case .image:
        return AnyView(ImageItemView(item: item))
    case .video:
        return AnyView(VideoItemView(item: item))
    }
}

// Usage in ForEach compounds the problem
ForEach(items) { item in
    makeView(for: item)  // SwiftUI cannot diff between renders
}

After (Fast)

// ✅ @ViewBuilder preserves type information for the compiler
@ViewBuilder
func makeView(for item: Item) -> some View {
    switch item.kind {
    case .text:
        TextItemView(item: item)
    case .image:
        ImageItemView(item: item)
    case .video:
        VideoItemView(item: item)
    }
}

// ✅ Or better: dedicated view struct (avoids large switch in @ViewBuilder)
struct ItemView: View {
    let item: Item

    var body: some View {
        switch item.kind {
        case .text:
            TextItemView(item: item)
        case .image:
            ImageItemView(item: item)
        case .video:
            VideoItemView(item: item)
        }
    }
}

When AnyView Is Acceptable

AnyView has negligible cost in these cases:

• A single view used once (not in a list or ForEach)
• Prototyping / throwaway code
• Bridging to UIKit hosting controllers where type erasure is required

2. Object Creation in body

The Problem

body can be called frequently (dozens of times per second during animation). Creating objects each time wastes CPU and memory:

// ❌ Creates a new DateFormatter every time body runs
// DateFormatter init is ~50x more expensive than a simple alloc
var body: some View {
    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    Text(formatter.string(from: date))
}

Expensive Objects to Watch For

After (Fast)

// ✅ Static shared formatter -- created once, reused forever
struct DateLabel: View {
    let date: Date

    private static let formatter: DateFormatter = {
        let f = DateFormatter()
        f.dateStyle = .medium
        return f
    }()

    var body: some View {
        Text(Self.formatter.string(from: date))
    }
}

// ✅ Or use the modern formatted() API which handles caching internally
struct DateLabel: View {
    let date: Date

    var body: some View {
        Text(date.formatted(.dateTime.month().day().year()))
    }
}

3. Over-Observation with ObservableObject

The Problem

With ObservableObject, changing any @Published property notifies all observers. If a large view observes a store with many properties, it re-evaluates on every change:

// ❌ All views observing AppState re-evaluate when ANY property changes
class AppState: ObservableObject {
    @Published var user: User?
    @Published var items: [Item] = []
    @Published var searchText = ""        // Typing here re-evaluates everything
    @Published var selectedTab = 0
    @Published var isOnboarding = false
    @Published var notifications: [Notification] = []
}

Fix Option A: Migrate to @Observable (iOS 17+)

// ✅ Per-property observation -- views only update when their dependencies change
@Observable
class AppState {
    var user: User?
    var items: [Item] = []
    var searchText = ""          // Only views reading searchText re-evaluate
    var selectedTab = 0
    var notifications: [Notification] = []
}

Fix Option B: Split Into Focused Stores (Pre-iOS 17)

// ✅ Each store has a narrow scope
class UserStore: ObservableObject {
    @Published var user: User?
}

class SearchStore: ObservableObject {
    @Published var searchText = ""
    @Published var results: [Item] = []
}

class NavigationStore: ObservableObject {
    @Published var selectedTab = 0
}

Fix Option C: Extract Subviews to Narrow Scope

// ❌ Entire view re-evaluates when searchText changes
struct ContentView: View {
    @ObservedObject var store: AppState

    var body: some View {
        VStack {
            TextField("Search", text: $store.searchText)
            ItemList(items: store.items)
            UserBadge(user: store.user)
        }
    }
}

// ✅ Each subview only connects to what it needs
struct ContentView: View {
    @ObservedObject var store: AppState

    var body: some View {
        VStack {
            SearchBar(store: store)
            ItemList(items: store.items)
            UserBadge(user: store.user)
        }
    }
}

struct SearchBar: View {
    @ObservedObject var store: AppState  // Re-evaluates often, but it's tiny

    var body: some View {
        TextField("Search", text: $store.searchText)
    }
}

4. Expensive Computation in body

The Problem

body runs on the main thread. Any expensive work directly blocks the UI:

// ❌ Filtering and sorting 10,000 items every time body runs
var body: some View {
    let filtered = items.filter { $0.matchesQuery(searchText) }
    let sorted = filtered.sorted { $0.date > $1.date }

    List(sorted) { item in
        ItemRow(item: item)
    }
}

After: Cache Computed Results

// ✅ Compute on change, not on every body call
struct ItemListView: View {
    let items: [Item]
    @State private var searchText = ""
    @State private var filteredItems: [Item] = []

    var body: some View {
        VStack {
            TextField("Search", text: $searchText)
            List(filteredItems) { item in
                ItemRow(item: item)
            }
        }
        .onChange(of: searchText) { _, newValue in
            filteredItems = items.filter { $0.matchesQuery(newValue) }
                .sorted { $0.date > $1.date }
        }
        .onAppear {
            filteredItems = items.sorted { $0.date > $1.date }
        }
    }
}

After: Offload to Background for Large Data Sets

// ✅ Background computation for expensive operations
struct ItemListView: View {
    let items: [Item]
    @State private var searchText = ""
    @State private var filteredItems: [Item] = []

    var body: some View {
        VStack {
            TextField("Search", text: $searchText)
            List(filteredItems) { item in
                ItemRow(item: item)
            }
        }
        .task(id: searchText) {
            // Runs on a background cooperative thread
            // Automatically cancelled if searchText changes again
            let query = searchText
            let allItems = items
            let results = await Task.detached {
                allItems.filter { $0.matchesQuery(query) }
                    .sorted { $0.date > $1.date }
            }.value
            filteredItems = results
        }
    }
}

5. Large Images Without Proper Sizing

The Problem

Loading full-resolution images in a scrolling list causes memory spikes and decode latency:

// ❌ Loads full resolution, decodes on main thread
List(photos) { photo in
    Image(uiImage: UIImage(contentsOfFile: photo.path)!)
        .resizable()
        .frame(height: 200)
}

After (Fast)

// ✅ AsyncImage handles loading and caching
List(photos) { photo in
    AsyncImage(url: photo.url) { image in
        image.resizable().scaledToFill()
    } placeholder: {
        Color.gray.opacity(0.2)
    }
    .frame(height: 200)
    .clipped()
}

// ✅ For local images: thumbnail generation off main thread
struct ThumbnailView: View {
    let imagePath: String
    @State private var thumbnail: UIImage?

    var body: some View {
        Group {
            if let thumbnail {
                Image(uiImage: thumbnail)
                    .resizable()
                    .scaledToFill()
            } else {
                Color.gray.opacity(0.2)
            }
        }
        .frame(height: 200)
        .clipped()
        .task {
            thumbnail = await UIImage(contentsOfFile: imagePath)?
                .byPreparingThumbnail(ofSize: CGSize(width: 400, height: 400))
        }
    }
}

6. Unnecessary @State Updates

The Problem

Setting a @State variable to its current value still triggers a re-evaluation:

// ❌ Triggers re-evaluation even when value hasn't changed
.onReceive(timer) { _ in
    currentTime = Date()  // Always a new value, always triggers body
}

// ❌ Setting state in body (causes infinite loop risk)
var body: some View {
    let _ = { isReady = true }()  // NEVER modify state during body
    Text("Hello")
}

After (Fast)

// ✅ Guard against redundant updates
.onReceive(timer) { _ in
    let newTime = Date()
    // Only update if the displayed value actually changes
    if Calendar.current.component(.second, from: newTime) !=
       Calendar.current.component(.second, from: currentTime) {
        currentTime = newTime
    }
}

// ✅ Use TimelineView for time-based updates (iOS 15+)
TimelineView(.periodic(from: .now, by: 1.0)) { context in
    Text(context.date.formatted(.dateTime.hour().minute().second()))
}

7. Deep View Hierarchies

The Problem

Deeply nested view modifiers create large view trees that are expensive to diff:

// ❌ Each modifier adds a wrapper view to the tree
Text("Hello")
    .padding()
    .background(Color.blue)
    .cornerRadius(8)
    .padding()
    .background(Color.gray)
    .cornerRadius(12)
    .shadow(radius: 4)
    .padding()
    .background(Color.white)
    .cornerRadius(16)

After: Consolidate Modifiers

// ✅ Flatten by using composite modifiers and fewer nesting levels
Text("Hello")
    .padding(8)
    .background(
        RoundedRectangle(cornerRadius: 8)
            .fill(Color.blue)
    )
    .padding(8)
    .background(
        RoundedRectangle(cornerRadius: 12)
            .fill(Color.gray)
            .shadow(radius: 4)
    )
    .padding(8)

Custom ViewModifier for Reusable Combinations

// ✅ Encapsulate common modifier combinations
struct CardStyle: ViewModifier {
    func body(content: Content) -> some View {
        content
            .padding()
            .background(
                RoundedRectangle(cornerRadius: 12)
                    .fill(Color(uiColor: .secondarySystemBackground))
            )
    }
}

extension View {
    func cardStyle() -> some View {
        modifier(CardStyle())
    }
}

// Usage: single modifier instead of three
Text("Hello").cardStyle()

8. Inefficient Conditional Rendering

The Problem

Using opacity(0) or hidden() to hide views still keeps them in the view tree and evaluates their body:

// ❌ View is invisible but still evaluated and in the layout
ExpensiveView()
    .opacity(showExpensive ? 1 : 0)

After: Conditional Inclusion

// ✅ View is not created at all when hidden
if showExpensive {
    ExpensiveView()
}

// ✅ Or use Group with optional for cleaner syntax
Group {
    if showExpensive {
        ExpensiveView()
    }
}

Note: this changes the view's structural identity (see view-identity.md). Use opacity when you need to preserve state; use if when you want to avoid the evaluation cost.

Quick Diagnosis Table

Lazy vs Eager Loading

How SwiftUI loads views in stacks, lists, and grids -- and the performance consequences of choosing the wrong container.

Eager vs Lazy Containers

Eager Containers

VStack, HStack, and ZStack create all child views immediately, regardless of whether they are visible on screen:

// ❌ Creates ALL 10,000 rows immediately -- hangs on appear
ScrollView {
    VStack {
        ForEach(items) { item in  // 10,000 items
            ItemRow(item: item)   // All 10,000 created at once
        }
    }
}

Lazy Containers

LazyVStack, LazyHStack, LazyVGrid, and LazyHGrid create child views on demand as they scroll into the visible area:

// ✅ Only creates visible rows + a small prefetch buffer
ScrollView {
    LazyVStack {
        ForEach(items) { item in  // 10,000 items
            ItemRow(item: item)   // ~20-30 created at a time
        }
    }
}

List

List is always lazy. It manages its own scroll view and creates rows on demand:

// ✅ Always lazy -- handles large data sets efficiently
List(items) { item in
    ItemRow(item: item)
}

When to Use Each Container

Rule of thumb: if you have a ForEach with more than ~50 items inside a ScrollView, use a lazy container.

LazyVStack vs VStack: Performance Comparison

The Cost of Eager Loading

For a list of 1,000 items, each with a moderately complex row:

Practical Threshold

LazyVStack Configuration

Pinned Headers

ScrollView {
    LazyVStack(spacing: 12, pinnedViews: [.sectionHeaders]) {
        ForEach(sections) { section in
            Section {
                ForEach(section.items) { item in
                    ItemRow(item: item)
                }
            } header: {
                SectionHeader(title: section.title)
            }
        }
    }
}

Alignment and Spacing

LazyVStack(alignment: .leading, spacing: 8) {
    ForEach(items) { item in
        ItemRow(item: item)
    }
}

Common Pitfalls with Lazy Containers

Pitfall 1: Child Views That Defeat Laziness

If a child view requests infinite height, the lazy container must measure all children to determine layout, defeating the purpose of laziness:

// ❌ .frame(maxHeight: .infinity) forces the lazy container to measure all children
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item: item)
                .frame(maxHeight: .infinity)  // Defeats laziness!
        }
    }
}

// ✅ Use fixed or intrinsic sizing
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item: item)
                .frame(height: 60)  // Fixed height, laziness preserved
        }
    }
}

Pitfall 2: GeometryReader Inside Lazy Containers

GeometryReader proposes .infinity to its children. Inside a lazy container, this can cause layout issues:

// ❌ GeometryReader inside LazyVStack: layout problems
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            GeometryReader { proxy in
                ItemRow(item: item, width: proxy.size.width)
            }
        }
    }
}

// ✅ Use GeometryReader outside the lazy container
ScrollView {
    GeometryReader { proxy in
        LazyVStack {
            ForEach(items) { item in
                ItemRow(item: item, width: proxy.size.width)
            }
        }
    }
}

// ✅ Or use containerRelativeFrame (iOS 17+)
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item: item)
                .containerRelativeFrame(.horizontal)
        }
    }
}

Pitfall 3: ScrollView With No Lazy Container

A ScrollView does not make its content lazy. It only provides scrolling:

// ❌ ScrollView alone does NOT make content lazy
ScrollView {
    ForEach(items) { item in  // All created immediately!
        ItemRow(item: item)
    }
}

// ✅ Must wrap in LazyVStack
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemRow(item: item)
        }
    }
}

Pitfall 4: Nesting ScrollViews

Nesting scroll views in the same direction causes undefined behavior:

// ❌ Nested vertical scroll views -- inner scroll may not work
ScrollView {
    LazyVStack {
        ForEach(sections) { section in
            ScrollView {  // Nested vertical scroll!
                ForEach(section.items) { item in
                    ItemRow(item: item)
                }
            }
        }
    }
}

// ✅ Use a single scroll view with sections
ScrollView {
    LazyVStack(pinnedViews: [.sectionHeaders]) {
        ForEach(sections) { section in
            Section {
                ForEach(section.items) { item in
                    ItemRow(item: item)
                }
            } header: {
                SectionHeader(title: section.title)
            }
        }
    }
}

Grid Performance

LazyVGrid

let columns = [
    GridItem(.adaptive(minimum: 150, maximum: 200))
]

ScrollView {
    LazyVGrid(columns: columns, spacing: 16) {
        ForEach(items) { item in
            ItemCell(item: item)
        }
    }
    .padding()
}

Fixed vs Adaptive vs Flexible Columns

For large grids (500+ items), prefer .fixed() columns to minimize layout computation.

List Performance

Built-in Optimizations

List provides features that lazy stacks do not:

• Cell reuse (like UITableView)
• Built-in swipe actions
• Separator management
• Edit mode with reordering and deletion

List Optimization Tips

List(items) { item in
    ItemRow(item: item)
        .listRowSeparator(.hidden)  // Slightly faster if you don't need separators
}
.listStyle(.plain)  // .plain is faster than .insetGrouped for large lists

When to Use List vs LazyVStack

Scroll Position and Prefetching

ScrollViewReader for Programmatic Scrolling

ScrollViewReader { proxy in
    ScrollView {
        LazyVStack {
            ForEach(items) { item in
                ItemRow(item: item)
                    .id(item.id)
            }
        }
    }
    .onChange(of: selectedItemID) { _, newID in
        withAnimation {
            proxy.scrollTo(newID, anchor: .center)
        }
    }
}

Data Prefetching for Pagination

Lazy containers do not have built-in prefetch callbacks like UICollectionViewDataSourcePrefetching. Implement manually:

struct PaginatedListView: View {
    @State private var items: [Item] = []
    @State private var isLoadingMore = false

    var body: some View {
        ScrollView {
            LazyVStack {
                ForEach(items) { item in
                    ItemRow(item: item)
                        .onAppear {
                            if item == items.last {
                                loadMoreIfNeeded()
                            }
                        }
                }

                if isLoadingMore {
                    ProgressView()
                }
            }
        }
    }

    private func loadMoreIfNeeded() {
        guard !isLoadingMore else { return }
        isLoadingMore = true
        Task {
            let newItems = await fetchNextPage()
            items.append(contentsOf: newItems)
            isLoadingMore = false
        }
    }
}

Debugging Lazy Loading Issues

Confirming Laziness

Add a print statement to verify views are created lazily:

struct ItemRow: View {
    let item: Item

    init(item: Item) {
        self.item = item
        print("ItemRow created: \(item.id)")  // Should only print for visible rows
    }

    var body: some View {
        Text(item.title)
    }
}

If you see all 1,000 items printed at once, the container is not lazy.

Measuring Scroll Frame Rate

Use CADisplayLink or the Core Animation Commits instrument in Instruments to measure frame rate during scrolling. Dropped frames (below 60fps / 120fps on ProMotion) indicate scroll performance issues.

View Identity

How SwiftUI decides whether two views are the same view (update in place) or different views (destroy and recreate). Getting identity wrong causes lost state, broken animations, and unnecessary work.

Two Kinds of Identity

Structural Identity (Implicit)

SwiftUI assigns identity based on a view's position in the view hierarchy. Two views at the same position in the same parent are considered the same view across renders.

// These two Text views have different structural identities
// because they are at different positions in the VStack
VStack {
    Text("First")   // position 0
    Text("Second")  // position 1
}

Explicit Identity

You override structural identity using .id() or ForEach identifiers. This tells SwiftUI: "this specific value identifies this view."

ForEach(items, id: \.id) { item in
    ItemRow(item: item)  // identity = item.id
}

DetailView(item: selectedItem)
    .id(selectedItem.id)  // identity = selectedItem.id

How SwiftUI Uses Identity

Key consequence: when identity changes, all `@State` is lost and the view is recreated from scratch.

.id() Modifier

When to Use .id()

Force SwiftUI to treat a view as a completely new instance:

// Force recreation when switching between items
// Without .id(), SwiftUI would try to update the same view,
// which can show stale state or skip the appear animation
DetailView(item: selectedItem)
    .id(selectedItem.id)

Stable vs Unstable Identifiers

// ✅ Stable: database ID, UUID, or model-provided unique key
ForEach(items, id: \.databaseID) { item in
    ItemRow(item: item)
}

// ✅ Stable: using Identifiable conformance
ForEach(items) { item in  // uses item.id automatically
    ItemRow(item: item)
}

// ❌ Unstable: array index on a mutable array
// When items are inserted/deleted, indices shift and
// SwiftUI matches the wrong data to the wrong view
ForEach(Array(items.enumerated()), id: \.offset) { index, item in
    ItemRow(item: item)
}

// ❌ Unstable: random value or Date()
// Generates a new identity every render, destroying all state
DetailView(item: item)
    .id(UUID())  // NEVER do this -- recreates view every body call

Performance Impact of Unstable .id()

When .id() changes every render: 1. SwiftUI destroys the entire view subtree (including all child views) 2. All @State and @StateObject are lost 3. onAppear fires again 4. Animations treat it as a new view (insertion transition, not update) 5. Any in-flight async task is cancelled and restarted

This is the single most expensive identity mistake. A view with N children all get destroyed and recreated.

Conditional View Branching

The if/else Identity Problem

if/else branches create different structural identities:

// ❌ Problem: toggling isLoading destroys and recreates ContentView
// because the two branches are different structural positions
if isLoading {
    ProgressView()
} else {
    ContentView()
}

When isLoading changes from true to false:

• ProgressView is destroyed (it existed at the "if-true" branch)
• ContentView is created from scratch (it appears at the "if-else" branch)
• All @State inside ContentView resets

When Destruction Is Acceptable

If the two branches show completely different content (like loading vs loaded), this destruction is fine and expected. The problem arises when you use if/else to toggle modifiers on the same view:

// ❌ Bad: destroys and recreates the same Text view
if isHighlighted {
    Text(item.title)
        .foregroundStyle(.yellow)
        .bold()
} else {
    Text(item.title)
        .foregroundStyle(.primary)
}

// ✅ Good: same structural identity, just different modifier values
Text(item.title)
    .foregroundStyle(isHighlighted ? .yellow : .primary)
    .bold(isHighlighted)

Ternary Expressions vs if/else in View Body

// ✅ Ternary: single structural identity, SwiftUI diffs the values
RoundedRectangle(cornerRadius: 12)
    .fill(isSelected ? Color.blue : Color.gray)
    .frame(height: isExpanded ? 200 : 80)

// ❌ if/else: two different structural identities
if isSelected {
    RoundedRectangle(cornerRadius: 12).fill(.blue)
} else {
    RoundedRectangle(cornerRadius: 12).fill(.gray)
}

AnyView and Identity

AnyView erases type information, which breaks structural identity tracking:

// ❌ AnyView: SwiftUI cannot track structural identity across renders
func makeView() -> AnyView {
    if condition {
        return AnyView(ViewA())
    } else {
        return AnyView(ViewB())
    }
}

// ✅ @ViewBuilder: preserves structural identity
@ViewBuilder
func makeView() -> some View {
    if condition {
        ViewA()
    } else {
        ViewB()
    }
}

See common-pitfalls.md for more on AnyView performance costs.

ForEach Identity

How ForEach Uses Identifiers

ForEach maps each data element to a view using the id key path. SwiftUI uses these identifiers to:

• Match existing views to updated data (minimizing recreations)
• Animate insertions, removals, and reorderings
• Preserve @State in each row

// ✅ Identifiable conformance (cleanest)
struct Item: Identifiable {
    let id: UUID
    var title: String
}
ForEach(items) { item in
    ItemRow(item: item)
}

// ✅ Explicit id key path
ForEach(items, id: \.uniqueKey) { item in
    ItemRow(item: item)
}

Duplicate Identifiers

If two items share the same id, SwiftUI behavior is undefined -- it may show duplicates, skip items, or crash:

// ❌ Dangerous: if two items have the same title, behavior is undefined
ForEach(items, id: \.title) { item in
    ItemRow(item: item)
}

// ✅ Always use a truly unique identifier
ForEach(items, id: \.id) { item in
    ItemRow(item: item)
}

Debugging Identity Issues

Symptoms of Identity Problems

Using _printChanges to Detect Recreation

var body: some View {
    let _ = Self._printChanges()
    // If you see "@identity changed" in the output,
    // SwiftUI considers this a brand-new view instance
    Text("Content")
}

Output @identity changed means the view was destroyed and recreated, not updated in place. This usually means an unstable .id() or a structural identity change from if/else branching.

Verifying with onAppear / onDisappear

DetailView(item: item)
    .id(item.id)
    .onAppear { print("DetailView appeared: \(item.id)") }
    .onDisappear { print("DetailView disappeared") }

If you see rapid appear/disappear cycles for the same content, the identity is unstable.

Fix Patterns Summary