SwiftUI performance
Read references/performance-playbook.md. Use for slow rendering, scrolling hitches, repeated work, memory growth, startup delay, excessive body updates, battery/thermal issues, or performance-focused review.
Workflow
- Reproduce with representative Mac hardware, macOS version, window configuration, data set, and release/debug build as appropriate.
- Record a baseline metric or trace; do not optimise from code appearance alone.
- Use Instruments (SwiftUI, Time Profiler, Allocations/Leaks, Core Animation, Network, Energy) and signposts where appropriate.
- Identify the invalidation source, expensive transform, I/O boundary, allocation, layout cycle, image cost, or task storm.
- Apply the smallest correction while preserving behaviour and accessibility.
- Re-measure under the same conditions and add a regression benchmark/test where stable.
- Build and run on macOS 26 and the lowest-spec supported Mac practical for the product.
Guardrails
- Do not add
EquatableView, caches, manual memoization, or flattened view trees without evidence.
- Do not move work to a background task unless ownership, cancellation, actor isolation, and UI commit are correct.
- Avoid
AnyView, unstable IDs, eager stacks for large data, expensive transforms in body, and formatter creation when format styles work.
- Scope timers/
TimelineView and observation to the smallest subtree.
- Cache only with measured benefit and explicit invalidation/memory bounds.
- Performance changes must not remove labels, text scaling, reduced-motion behaviour, keyboard/focus support, or native macOS semantics.
Output
Report reproduction, baseline, trace/tool, root cause, change, after measurement, variance, tested hardware/macOS/window state, and remaining risks. Separate measured facts from hypotheses.
1---2name: swiftui-performance3description: Diagnose and improve macOS SwiftUI rendering, invalidation, table/list, scrolling, image, task, startup, memory, and energy performance using measurement.4license: MIT5---67# SwiftUI performance89Read `references/performance-playbook.md`. Use for slow rendering, scrolling hitches, repeated work, memory growth, startup delay, excessive body updates, battery/thermal issues, or performance-focused review.1011## Workflow12131. Reproduce with representative Mac hardware, macOS version, window configuration, data set, and release/debug build as appropriate.142. Record a baseline metric or trace; do not optimise from code appearance alone.153. Use Instruments (SwiftUI, Time Profiler, Allocations/Leaks, Core Animation, Network, Energy) and signposts where appropriate.164. Identify the invalidation source, expensive transform, I/O boundary, allocation, layout cycle, image cost, or task storm.175. Apply the smallest correction while preserving behaviour and accessibility.186. Re-measure under the same conditions and add a regression benchmark/test where stable.197. Build and run on macOS 26 and the lowest-spec supported Mac practical for the product.2021## Guardrails2223- Do not add `EquatableView`, caches, manual memoization, or flattened view trees without evidence.24- Do not move work to a background task unless ownership, cancellation, actor isolation, and UI commit are correct.25- Avoid `AnyView`, unstable IDs, eager stacks for large data, expensive transforms in `body`, and formatter creation when format styles work.26- Scope timers/`TimelineView` and observation to the smallest subtree.27- Cache only with measured benefit and explicit invalidation/memory bounds.28- Performance changes must not remove labels, text scaling, reduced-motion behaviour, keyboard/focus support, or native macOS semantics.2930## Output3132Report reproduction, baseline, trace/tool, root cause, change, after measurement, variance, tested hardware/macOS/window state, and remaining risks. Separate measured facts from hypotheses.
rcarmo