1# SwiftUI State Management Reference
2 
3## Table of Contents
4 
5- [Property Wrapper Selection Guide](#property-wrapper-selection-guide)
6- [@State](#state)
7- [Property Wrappers Inside @Observable Classes](#property-wrappers-inside-observable-classes)
8- [Make @Observable Property Types Equatable](#make-observable-property-types-equatable)
9- [@Observable Dependency Granularity](#observable-dependency-granularity)
10- [@Binding](#binding)
11- [@FocusState](#focusstate)
12- [@StateObject vs @ObservedObject (Legacy - Pre-iOS 17)](#stateobject-vs-observedobject-legacy---pre-ios-17)
13- [Don't Pass Values as @State](#dont-pass-values-as-state)
14- [@Bindable (iOS 17+)](#bindable-ios-17)
15- [let vs var for Passed Values](#let-vs-var-for-passed-values)
16- [Environment and Preferences](#environment-and-preferences)
17- [Decision Flowchart](#decision-flowchart)
18- [State Privacy Rules](#state-privacy-rules)
19- [Avoid Nested ObservableObject](#avoid-nested-observableobject)
20- [Key Principles](#key-principles)
21 
22## Property Wrapper Selection Guide
23 
24| Wrapper | Use When | Notes |
25|---------|----------|-------|
26| `@State` | Internal view state that triggers updates | Must be `private` |
27| `@Binding` | Child view needs to modify parent's state | Don't use for read-only |
28| `@Bindable` | iOS 17+: View receives `@Observable` object and needs bindings | For injected observables |
29| `let` | Read-only value passed from parent | Simplest option |
30| `var` | Read-only value that child observes via `.onChange()` | For reactive reads |
31 
32**Legacy (Pre-iOS 17):**
33| Wrapper | Use When | Notes |
34|---------|----------|-------|
35| `@StateObject` | View owns an `ObservableObject` instance | Use `@State` with `@Observable` instead |
36| `@ObservedObject` | View receives an `ObservableObject` from outside | Never create inline |
37 
38## @State
39 
40Always mark `@State` properties as `private`. Use for internal view state that triggers UI updates.
41 
42```swift
43// Correct
44@State private var isAnimating = false
45@State private var selectedTab = 0
46```
47 
48**Why Private?** Marking state as `private` makes it clear what's created by the view versus what's passed in. It also prevents accidentally passing initial values that will be ignored (see "Don't Pass Values as @State" below).
49 
50### iOS 17+ with @Observable (Preferred)
51 
52**Always prefer `@Observable` over `ObservableObject`.** With iOS 17's `@Observable` macro, use `@State` instead of `@StateObject`:
53 
54```swift
55@Observable
56@MainActor  // Always mark @Observable classes with @MainActor
57final class DataModel {
58    var name = "Some Name"
59    var count = 0
60}
61 
62struct MyView: View {
63    @State private var model = DataModel()  // Use @State, not @StateObject
64 
65    var body: some View {
66        VStack {
67            TextField("Name", text: $model.name)
68            Stepper("Count: \(model.count)", value: $model.count)
69        }
70    }
71}
72```
73 
74**Critical**: When a view *owns* an `@Observable` object, always use `@State` -- not `let`. Without `@State`, SwiftUI may recreate the instance when a parent view redraws, losing accumulated state. `@State` tells SwiftUI to preserve the instance across view redraws. Using `@State` also provides bindings directly (no need for `@Bindable`).
75 
76**Note**: You may want to mark `@Observable` classes with `@MainActor` to ensure thread safety with SwiftUI, unless your project or package uses Default Actor Isolation set to `MainActor`—in which case, the explicit attribute is redundant and can be omitted.
77 
78## Property Wrappers Inside @Observable Classes
79 
80**Critical**: The `@Observable` macro transforms stored properties to add observation tracking. Property wrappers (like `@AppStorage`, `@SceneStorage`, `@Query`) also transform properties with their own storage. These two transformations conflict, causing a compiler error.
81 
82**Always annotate property-wrapper properties with `@ObservationIgnored` inside `@Observable` classes.**
83 
84```swift
85@Observable
86@MainActor
87final class SettingsModel {
88    // WRONG - compiler error: property wrappers conflict with @Observable
89    // @AppStorage("username") var username = ""
90 
91    // CORRECT - @ObservationIgnored prevents the conflict
92    @ObservationIgnored @AppStorage("username") var username = ""
93    @ObservationIgnored @AppStorage("isDarkMode") var isDarkMode = false
94 
95    // Regular stored properties work fine with @Observable
96    var isLoading = false
97}
98```
99 
100This applies to **any** property wrapper used inside an `@Observable` class, including but not limited to:
101- `@AppStorage`
102- `@SceneStorage`
103- `@Query` (SwiftData)
104 
105**Note**: Since `@ObservationIgnored` disables observation tracking for that property, SwiftUI won't detect changes through the Observation framework. However, property wrappers like `@AppStorage` already notify SwiftUI of changes through their own mechanisms (e.g., UserDefaults KVO), so views still update correctly.
106 
107**Never remove `@ObservationIgnored`** from property-wrapper properties in `@Observable` classes — doing so causes a compiler error.
108 
109## Make @Observable Property Types Equatable
110 
111The `@Observable` macro generates a setter that **skips invalidation when the new value equals the current one** — but only when it can compare them, which means only when the property's type is `Equatable`. Without that conformance, every assignment notifies observing views, even when the value is identical. This is an easy win for properties written frequently with the same value (polling, streaming updates, timers).
112 
113```swift
114// AVOID: not Equatable — every assignment invalidates, even no-op writes
115enum DeliveryStatus { case placed, preparing, shipped, delivered }
116 
117// PREFER: Equatable lets the generated setter short-circuit redundant writes
118enum DeliveryStatus: Equatable { case placed, preparing, shipped, delivered }
119```
120 
121This applies to collection properties too: an `Array`/`Set`/`Dictionary` is only `Equatable` when its element type is, so a non-`Equatable` element defeats the short-circuit for the whole collection. (The check is emitted into the generated setter as user code, so it applies on every OS that supports `@Observable` when built with current Xcode.)
122 
123This is distinct from `Equatable` *views* (see `references/performance-patterns.md`): that conformance lets SwiftUI skip a view's body; this one lets the model skip notifying observers in the first place.
124 
125## @Observable Dependency Granularity
126 
127Observation tracks reads at the **property** level, not the field level — so reading any part of a compound property establishes a dependency on the whole thing. Three common traps and their fixes:
128 
129- **A computed property establishes dependencies transitively.** `var currentUser: User? { users.first { $0.id == currentID } }` reads `users` in its body, so any view reading `currentUser` depends on the entire `users` array. Renaming the access doesn't change what observation tracks.
130- **A struct-typed stored property drags the whole struct.** A view reading `session.user.name` depends on `session.user`; editing any other field of `user` invalidates it.
131- **An array/collection read drags the whole collection.** Reading one element establishes a dependency on the entire stored collection.
132 
133```swift
134// PREFER: cache derived values as stored properties, kept in sync in didSet
135@MainActor @Observable
136final class AppState {
137    var users: [User] = [] { didSet { recomputeCurrentUser() } }
138    var currentID: User.ID? { didSet { recomputeCurrentUser() } }
139 
140    private(set) var currentUser: User?
141    private func recomputeCurrentUser() { currentUser = users.first { $0.id == currentID } }
142}
143```
144 
145For struct-typed properties, expose the fields the views actually read as individual properties on the model (each is then tracked separately). When many rows each observe several fields of their element, model each element as its own `@Observable` and have the parent **persist** the instances — see the per-item view model pattern in `references/performance-patterns.md`. Reading several already-narrow properties from one model is fine and does not need splitting.
146 
147## @Binding
148 
149Use only when child view needs to **modify** parent's state. If child only reads the value, use `let` instead.
150 
151```swift
152// Parent
153struct ParentView: View {
154    @State private var isSelected = false
155 
156    var body: some View {
157        ChildView(isSelected: $isSelected)
158    }
159}
160 
161// Child - will modify the value
162struct ChildView: View {
163    @Binding var isSelected: Bool
164 
165    var body: some View {
166        Button("Toggle") {
167            isSelected.toggle()
168        }
169    }
170}
171```
172 
173### When NOT to use @Binding
174 
175- **Don't use `@Binding` for read-only values.** If the child only displays the value and never modifies it, use `let` instead. `@Binding` adds unnecessary overhead and implies a write contract that doesn't exist.
176 
177### Prefer KeyPath Bindings Over Closure Bindings
178 
179When you need a binding into a model, prefer a KeyPath/subscript-based binding over a hand-written `Binding(get:set:)` closure. A closure binding allocates a new closure each time `body` runs and can't be compared, which can trigger unnecessary invalidations.
180 
181```swift
182// BAD - closure binding: heap allocation each body pass, defeats comparison
183let binding = Binding(
184    get: { model[scoreFor: player] },
185    set: { model[scoreFor: player] = $0 }
186)
187PlayerScoreRow(player: player, score: binding)
188 
189// GOOD - project through a subscript with @Bindable
190@Bindable var model = model
191PlayerScoreRow(player: player, score: $model[scoreFor: player])
192```
193 
194If no suitable subscript exists, add one (a labeled subscript reads as a clean projection into the model). Reserve closure bindings for cases where no key path or subscript can express the transform.
195 
196## @FocusState
197 
198See `references/focus-patterns.md` for comprehensive focus management guidance including `@FocusState`, `@FocusedValue`, `.focusable()`, default focus, and common pitfalls.
199 
200Always mark `@FocusState` as `private`.
201 
202## @StateObject vs @ObservedObject (Legacy - Pre-iOS 17)
203 
204**Note**: Always prefer `@Observable` with `@State` for iOS 17+.
205 
206The key distinction is **ownership**: `@StateObject` when the view **creates and owns** the object; `@ObservedObject` when the view **receives** it from outside.
207 
208```swift
209// View creates it → @StateObject
210@StateObject private var viewModel = MyViewModel()
211 
212// View receives it → @ObservedObject
213@ObservedObject var viewModel: MyViewModel
214```
215 
216**Never** create an `ObservableObject` inline with `@ObservedObject` -- it recreates the instance on every view update.
217 
218### @StateObject instantiation in View's initializer
219 
220Prefer storing the `@StateObject` in the parent view and passing it down. If you must create one in a custom initializer, pass the expression directly to `StateObject(wrappedValue:)` so the `@autoclosure` prevents redundant allocations:
221 
222```swift
223// Inside a View's init(movie:):
224// WRONG — assigning to a local first defeats @autoclosure
225let vm = MovieDetailsViewModel(movie: movie)
226_viewModel = StateObject(wrappedValue: vm)
227 
228// CORRECT — inline expression defers creation
229_viewModel = StateObject(wrappedValue: MovieDetailsViewModel(movie: movie))
230```
231 
232**Modern Alternative**: Use `@Observable` with `@State` instead.
233 
234## Don't Pass Values as @State
235 
236**Critical**: Never declare passed values as `@State` or `@StateObject`. They only accept an initial value and ignore subsequent updates from the parent.
237 
238```swift
239// WRONG - child ignores parent updates
240struct ChildView: View {
241    @State var item: Item  // Shows initial value forever!
242    var body: some View { Text(item.name) }
243}
244 
245// CORRECT - child receives updates
246struct ChildView: View {
247    let item: Item  // Or @Binding if child needs to modify
248    var body: some View { Text(item.name) }
249}
250```
251 
252**Prevention**: Always mark `@State` and `@StateObject` as `private`. This prevents them from appearing in the generated initializer.
253 
254## @Bindable (iOS 17+)
255 
256Use when receiving an `@Observable` object from outside and needing bindings:
257 
258```swift
259@Observable
260final class UserModel {
261    var name = ""
262    var email = ""
263}
264 
265struct ParentView: View {
266    @State private var user = UserModel()
267 
268    var body: some View {
269        EditUserView(user: user)
270    }
271}
272 
273struct EditUserView: View {
274    @Bindable var user: UserModel  // Received from parent, needs bindings
275 
276    var body: some View {
277        Form {
278            TextField("Name", text: $user.name)
279            TextField("Email", text: $user.email)
280        }
281    }
282}
283```
284 
285## let vs var for Passed Values
286 
287### Use `let` for read-only display
288 
289```swift
290struct ProfileHeader: View {
291    let username: String
292    let avatarURL: URL
293 
294    var body: some View {
295        HStack {
296            AsyncImage(url: avatarURL)
297            Text(username)
298        }
299    }
300}
301```
302 
303### Use `var` when reacting to changes with `.onChange()`
304 
305```swift
306struct ReactiveView: View {
307    var externalValue: Int  // Watch with .onChange()
308    @State private var displayText = ""
309 
310    var body: some View {
311        Text(displayText)
312            .onChange(of: externalValue) { oldValue, newValue in
313                displayText = "Changed from \(oldValue) to \(newValue)"
314            }
315    }
316}
317```
318 
319## Environment and Preferences
320 
321### @Environment
322 
323Access environment values provided by SwiftUI or parent views:
324 
325```swift
326struct MyView: View {
327    @Environment(\.colorScheme) private var colorScheme
328    @Environment(\.dismiss) private var dismiss
329 
330    var body: some View {
331        Button("Done") { dismiss() }
332            .foregroundStyle(colorScheme == .dark ? .white : .black)
333    }
334}
335```
336 
337### Custom Environment Values with @Entry
338 
339Use the `@Entry` macro (Xcode 16+, backward compatible to iOS 13) to define custom environment values without boilerplate:
340 
341```swift
342extension EnvironmentValues {
343    @Entry var accentTheme: Theme = .default
344}
345 
346// Inject
347ContentView()
348    .environment(\.accentTheme, customTheme)
349 
350// Access
351struct ThemedView: View {
352    @Environment(\.accentTheme) private var theme
353}
354```
355 
356The `@Entry` macro replaces the manual `EnvironmentKey` conformance pattern. It also works with `Transaction`, `ContainerValues`, and `FocusedValues`.
357 
358#### Never store closures in custom environment keys
359 
360SwiftUI can't reliably compare function values, so a view that reads an environment key holding a closure invalidates on every environment write, even when nothing it cares about changed. Wrapping the closure in a struct doesn't help — the struct still contains an uncomparable closure. The fix is to eliminate the closure: store the data it would have captured as properties and expose the behavior via `callAsFunction` or a method.
361 
362```swift
363// AVOID: closure in a custom environment key
364extension EnvironmentValues {
365    @Entry var submit: (String) -> Void = { _ in }
366}
367 
368// PREFER: a defunctionalized struct (or an @Observable model)
369struct SubmitAction { func callAsFunction(_ draft: String) { /* ... */ } }
370extension EnvironmentValues {
371    @Entry var submit = SubmitAction()
372}
373```
374 
375This rule is for **custom** keys. Framework action types designed to wrap a closure — `\.openURL`, `\.dismiss`, `\.refresh`, and similar — are the intended API and are fine.
376 
377#### Keep @Entry default values stable
378 
379`@Entry` wraps its default expression in a computed getter, so the default is re-evaluated on every read that falls back to it. If the expression returns a different result each time — a fresh reference like `Model()`, or a runtime value like `Date()` / `UUID()` — readers that use the default invalidate on every unrelated environment write.
380 
381```swift
382// AVOID: re-allocates Model() on every fallback read
383extension EnvironmentValues {
384    @Entry var model = Model()
385}
386 
387// PREFER: back the default with a stable value
388extension EnvironmentValues {
389    @Entry var model = _defaultModel
390    private static let _defaultModel = Model()
391}
392```
393 
394Stable defaults (literals, enum cases, `nil`, or a `static let`-backed instance) need no fix. If readers test the default for an "empty" sentinel, prefer an optional `@Entry var model: Model?` and branch on `if let` instead.
395 
396#### Remove unused @Environment reads
397 
398Declaring `@Environment(\.someKey)` subscribes the view to that key even if `body` never uses the value, so every write to that key re-evaluates the view for nothing. If the wrapped value isn't referenced anywhere the body reaches, delete the declaration. (The type form `@Environment(Model.self)` is different — observation tracks at the property level, so an unused type-form declaration carries no live invalidation cost.)
399 
400### @Environment with @Observable (iOS 17+ - Preferred)
401 
402**Always prefer this pattern** for sharing state through the environment:
403 
404```swift
405@Observable
406@MainActor
407final class AppState {
408    var isLoggedIn = false
409}
410 
411// Inject
412ContentView()
413    .environment(AppState())
414 
415// Access
416struct ChildView: View {
417    @Environment(AppState.self) private var appState
418}
419```
420 
421### @EnvironmentObject (Legacy - Pre-iOS 17)
422 
423Legacy pattern: inject with `.environmentObject(AppState())`, access with `@EnvironmentObject var appState: AppState`. Prefer `@Observable` with `@Environment` instead.
424 
425## Decision Flowchart
426 
427```
428Is this value owned by this view?
429├─ YES: Is it a simple value type?
430│       ├─ YES → @State private var
431│       └─ NO (class):
432│           ├─ Use @Observable → @State private var (mark class @MainActor)
433│           └─ Legacy ObservableObject → @StateObject private var
434│
435└─ NO (passed from parent):
436    ├─ Does child need to MODIFY it?
437    │   ├─ YES → @Binding var
438    │   └─ NO: Does child need BINDINGS to its properties?
439    │       ├─ YES (@Observable) → @Bindable var
440    │       └─ NO: Does child react to changes?
441    │           ├─ YES → var + .onChange()
442    │           └─ NO → let
443    │
444    └─ Is it a legacy ObservableObject from parent?
445        └─ YES → @ObservedObject var (consider migrating to @Observable)
446```
447 
448## State Privacy Rules
449 
450**All view-owned state should be `private`:**
451 
452```swift
453// Correct - clear what's created vs passed
454struct MyView: View {
455    // Created by view - private
456    @State private var isExpanded = false
457    @State private var viewModel = ViewModel()
458    @AppStorage("theme") private var theme = "light"
459    @Environment(\.colorScheme) private var colorScheme
460    
461    // Passed from parent - not private
462    let title: String
463    @Binding var isSelected: Bool
464    @Bindable var user: User
465    
466    var body: some View {
467        // ...
468    }
469}
470```
471 
472**Why**: This makes dependencies explicit and improves code completion for the generated initializer.
473 
474## Avoid Nested ObservableObject
475 
476**Note**: This limitation only applies to `ObservableObject`. `@Observable` fully supports nested observed objects.
477 
478SwiftUI can't track changes through nested `ObservableObject` properties. Workaround: pass the nested object directly to child views as `@ObservedObject`. With `@Observable`, nesting works automatically.
479 
480## Key Principles
481 
4821. **Always prefer `@Observable` over `ObservableObject`** for new code
4832. **Mark `@Observable` classes with `@MainActor` for thread safety (unless using default actor isolation)`**
4843. Use `@State` with `@Observable` classes (not `@StateObject`)
4854. Use `@Bindable` for injected `@Observable` objects that need bindings
4865. **Always mark `@State` and `@StateObject` as `private`**
4876. **Never declare passed values as `@State` or `@StateObject`**
4887. With `@Observable`, nested objects work fine; with `ObservableObject`, pass nested objects directly to child views
4898. **Always add `@ObservationIgnored` to property wrappers** (e.g., `@AppStorage`, `@SceneStorage`, `@Query`) inside `@Observable` classes — they conflict with the macro's property transformation
4909. **Prefer `Equatable` types for frequently-written `@Observable` properties** so the generated setter skips redundant invalidations
49110. **Never store closures in custom environment keys; keep `@Entry` defaults stable** (no `Model()`/`Date()` expressions)
49211. **Prefer KeyPath/subscript bindings over closure bindings**
493