Common iOS & SwiftUI Pitfalls
Most SwiftUI bugs trace back to a small set of conceptual misunderstandings: treating a view struct like a persistent object, misplacing where state should be owned, breaking collection identity, or fighting the main-actor/concurrency model instead of working with it. None of these are exotic — they show up in production codebases at every experience level — which is exactly why recognizing them quickly is a high-leverage skill. This topic walks through the pitfalls that recur most often, why the underlying mechanism causes them, and the idiomatic fix for each.
Cricket analogy: Just as new cricketers often mistake a single over for a whole spell, misjudge who should set the field, mix up player identities during a substitution, or fight the DRS system instead of using it, SwiftUI newcomers repeat the same handful of conceptual errors — recognizing the pattern quickly separates good coaches from great ones.
Misplacing state ownership
A common mistake is declaring @State in a child view for data that a parent also needs, then trying to sync the two with onChange callbacks that pass values back up. SwiftUI's model expects a single source of truth: the parent (or a shared @Observable model) should own the state, and the child should receive a @Binding to it. Duplicating state and syncing it manually invites the two copies to drift out of sync and adds indirection that makes the data flow hard to follow. The fix is almost always to hoist the @State up to the nearest common owner and pass a binding down.
Cricket analogy: A fielding captain shouldn't let both himself and the wicketkeeper independently decide the field placement and then shout corrections back and forth; one person (the parent) should own the field plan and simply instruct (bind) the wicketkeeper's positioning.
// Pitfall: duplicated state that drifts
struct BadFilterRow: View {
@State private var isOn = false // shadow copy
let externalIsOn: Bool
let onToggle: (Bool) -> Void
var body: some View {
Toggle("Show archived", isOn: $isOn)
.onChange(of: isOn) { _, new in onToggle(new) }
}
}
// Fix: single source of truth via @Binding
struct FilterRow: View {
@Binding var isOn: Bool
var body: some View {
Toggle("Show archived", isOn: $isOn)
}
}Breaking List/ForEach identity
SwiftUI diffs ForEach and List content by identity, not by position. Using array index as the id (ForEach(0..<items.count)) or supplying a non-unique id causes SwiftUI to misattribute a row's local state — like a text field's cursor position or an expanded/collapsed flag — to the wrong logical item after an insertion, deletion, or reorder. The fix is to conform the model to Identifiable with a stable unique id (often a persisted UUID or a database primary key) and let ForEach infer identity from that, rather than fabricating an id from mutable data like index or display order.
Cricket analogy: Tracking players by their batting-order slot number instead of their actual player ID causes chaos the moment the order changes — SwiftUI's ForEach needs a stable id like a player's registration number, not a position that shifts every time the lineup is reshuffled.
Fighting the main-actor and concurrency model
SwiftUI's view bodies and most UI-facing property wrappers are main-actor-isolated. A frequent pitfall is performing a network call inside a Task, then mutating @State or an @Observable property directly from a background continuation without hopping back to the main actor — this can produce runtime warnings or, worse, subtle UI glitches from off-main mutation. The idiomatic fix is to mark the updating function or type @MainActor, or to structure the async function so UI-state mutation happens after an await point that's implicitly resumed on the main actor (which .task and most SwiftUI-invoked async closures already guarantee).
Cricket analogy: Only the on-field umpire (main actor) is authorized to signal a boundary or wicket; a spectator shouting from the stands (background thread) can't directly update the scoreboard — the call has to be relayed back through the umpire before it counts.
A helpful diagnostic habit: whenever you see manual boolean flags syncing two pieces of state, or an id: closure that references index, pause and ask 'what is the single source of truth here, and is my identity actually stable?' — most SwiftUI bugs answer themselves once you name those two things explicitly.
Retain cycles are still possible in SwiftUI apps: an @Observable class holding a closure that captures self strongly, stored on a view that's captured back by that same object (e.g., via a delegate-style callback), can leak. Use [weak self] in closures stored long-term on reference-type models, the same as you would in UIKit.
Overusing AnyView and type erasure
Reaching for AnyView to unify branches with different concrete view types is a common early habit, but it defeats SwiftUI's ability to diff and animate transitions efficiently, because AnyView hides the underlying type identity SwiftUI relies on. In almost all cases, @ViewBuilder with if/else or a switch, or a generic function/view constrained by the View protocol, expresses the same logic without erasing type information — reserve AnyView for genuine heterogeneous collections where no other option works.
Cricket analogy: Announcing every player generically as just "a cricketer" instead of naming them (batsman, bowler, all-rounder) makes it impossible for the broadcast graphics to show role-specific stats — SwiftUI's @ViewBuilder if/else keeps each branch's specific type known, the way naming a player's actual role does.
- Hoist duplicated state to a single owner and pass @Binding down rather than manually syncing two copies.
- Never use array index as List/ForEach identity for mutable collections — conform models to Identifiable with a stable id.
- UI-facing state must be mutated on the main actor; hopping back from a background continuation is required otherwise.
- Overusing AnyView erases type identity and hurts SwiftUI's diffing and animation performance.
- Retain cycles can still occur with @Observable reference types capturing closures strongly — use [weak self].
- Most pitfalls trace back to unclear state ownership or unstable identity.
Practice what you learned
1. What problem arises from a child view keeping its own @State copy of a value that a parent also tracks and syncing them via onChange?
2. Why is using array index as a ForEach id risky for a mutable collection?
3. What is the risk of mutating @State directly from a background thread continuation without returning to the main actor?
4. Why does overusing AnyView hurt SwiftUI performance?
5. How can a retain cycle still occur in a SwiftUI app using @Observable models?
Was this page helpful?
You May Also Like
List Performance in SwiftUI
Learn how SwiftUI's List actually renders and recycles rows, and the concrete techniques for keeping scrolling smooth in large or complex data sets.
@State and @Binding
Understand how @State owns local view state and how @Binding lets child views read and write that state without owning it themselves.
Task and Structured Concurrency
Explore how Swift's Task type creates units of asynchronous work, how structured concurrency establishes parent-child relationships, and how cancellation propagates.
iOS & SwiftUI Interview Questions
A curated set of common iOS and SwiftUI interview questions covering state management, concurrency, architecture, and performance, with clear answers.