/swiftui-performance

name: swiftui-performance
description: "Profile, diagnose, and remediate SwiftUI runtime performance using code review, Instruments, and repeatable measurements. Use when a SwiftUI screen renders slowly, scrolling or animations hitch, view bodies update excessively, list identity churns, layout work spikes, or broad Observation dependencies raise CPU cost. Covers evidence-based triage, SwiftUI Instruments lanes, lazy-container guardrails, state lifetime, and before/after verification."

SwiftUI Performance

Audit SwiftUI view performance from a reproducible symptom to measured remediation. Route animation design to `swiftui-animation`, production telemetry to `metrickit`, ownership/leak analysis to `ios-memgraph-analysis`, navigation behavior to `swiftui-navigation`, state architecture to `swiftui-patterns`, and layout construction to `swiftui-layout-components`.

Contents

• [Workflow Decision Tree](#workflow-decision-tree)
• [1. Code-First Review](#1-code-first-review)
• [2. Guide the User to Profile](#2-guide-the-user-to-profile)
• [3. Analyze and Diagnose](#3-analyze-and-diagnose)
• [4. Remediate](#4-remediate)
• [Common Code Smells (and Fixes)](#common-code-smells-and-fixes)
• [5. Verify](#5-verify)
• [Outputs](#outputs)
• [Instruments Profiling](#instruments-profiling)
• [Identity and Lifetime](#identity-and-lifetime)
• [Lazy Loading Patterns](#lazy-loading-patterns)
• [State and Observation Optimization](#state-and-observation-optimization)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Workflow Decision Tree

• Code supplied: review it first and label findings as hypotheses.
• Symptoms only: collect the smallest relevant view, data flow, reproduction,

device, OS, and build configuration.

• Inconclusive review: collect a trace or lane screenshots before prescribing a

broad refactor.

Use this triage list for both code and trace analysis:

• Broad state dependencies or invalidation storms
• Unstable list identity or root conditional swapping
• Formatting, sorting, decoding, or synchronous I/O in `body`
• Layout/geometry feedback loops and oversized images
• Implicit animation applied to a large hierarchy

1. Code-First Review

Map each suspect from the triage list to exact code. Report likely causes with code references, but label them code-backed hypotheses until a trace confirms cost. Propose a minimal repro or measurement when evidence is missing.

2. Guide the User to Profile

Use the SwiftUI Instruments template on a **Release build** and real device when possible. Reproduce the exact interaction, capturing SwiftUI lanes, Time Profiler, and Hangs/Hitches as relevant. Ask for the trace or screenshots of the lanes and call tree.

3. Analyze and Diagnose

Apply the same triage list to trace evidence. Correlate long or frequent SwiftUI updates with the Time Profiler call tree and the reproduced interaction. Separate trace-backed findings from code-backed hypotheses and name the next measurement that would resolve remaining uncertainty.

4. Remediate

Apply targeted fixes:

• Narrow state scope (`@State`/`@Observable` closer to leaf views).
• Stabilize identities for `ForEach` and lists.
• Move heavy work out of `body` into model-layer precomputation, an explicit derived

value updated when its inputs change, a memoized helper, or background processing. Use `@State` only when the view owns both the value and its update lifecycle; it is not a generic cache for arbitrary computation.

• Use `equatable()` only when equality is cheaper than recomputing the subtree and

the compared inputs have stable value semantics.

• Downsample images before rendering.
• Reduce layout complexity or use fixed sizing where possible.

Common Code Smells (and Fixes)

| Smell | Evidence to seek | Targeted fix | |---|---|---| | Formatter, sort, filter, or decode in `body` | Long/frequent body updates with matching call-tree cost | Recompute when inputs change; downsample/decode off the main actor | | `UUID()` or unstable `id: \.self` | Recreated rows, lost state, excess updates | Use stable model identity | | Root `if`/`else` swaps | State reset or update spikes when toggled | Localize conditional content/modifiers when semantics allow | | Broad model reads | Many unrelated views update together | Pass narrow values or move reads into focused child views | | Geometry writes during layout | Repeating layout/update cycle | Threshold changes or replace the feedback path with stable layout |

5. Verify

Ask the user to re-run the same capture and compare with baseline metrics. Summarize the delta (CPU, frame drops, memory peak) if provided.

Outputs

Provide:

• A short metrics table (before/after if available).
• Top issues (ordered by impact).
• Proposed fixes with estimated effort.

Instruments Profiling

Use the **SwiftUI template** in Instruments (Cmd+I to profile). Current SwiftUI lanes include Update Groups, Long View Body Updates, Long Representable Updates / Representable Updates, Other Long Updates / Other Updates, and the Cause & Effect Graph. Correlate those with Time Profiler and Hangs/Hitches.

Add `Self._printChanges()` in debug builds to log which property triggered a view update:

var body: some View {
    #if DEBUG
    let _ = Self._printChanges()  // "MyView: @self, _count changed."
    #endif
    Text("Count: \(count)")
}

See [references/optimizing-swiftui-performance-instruments.md](references/optimizing-swiftui-performance-instruments.md) for the full profiling workflow.

Identity and Lifetime

Identity controls view lifetime and state. Use stable model IDs in repeated content and reserve `.id(_:)` changes for intentional resets. Prefer `@ViewBuilder` or generic composition over `AnyView` in profiled hot rows. Treat root conditional branches as suspects—not automatic defects—when evidence shows state churn or expensive recreation.

Text(title)
    .foregroun