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- [@Binding](#binding)
9- [@FocusState](#focusstate)
10- [@StateObject vs @ObservedObject (Legacy - Pre-iOS 17)](#stateobject-vs-observedobject-legacy---pre-ios-17)
11- [Don't Pass Values as @State](#dont-pass-values-as-state)
12- [@Bindable (iOS 17+)](#bindable-ios-17)
13- [let vs var for Passed Values](#let-vs-var-for-passed-values)
14- [Environment and Preferences](#environment-and-preferences)
15- [Decision Flowchart](#decision-flowchart)
16- [State Privacy Rules](#state-privacy-rules)
17- [Avoid Nested ObservableObject](#avoid-nested-observableobject)
18- [Key Principles](#key-principles)
19 
20## Property Wrapper Selection Guide
21 
22| Wrapper | Use When | Notes |
23|---------|----------|-------|
24| `@State` | Internal view state that triggers updates | Must be `private` |
25| `@Binding` | Child view needs to modify parent's state | Don't use for read-only |
26| `@Bindable` | iOS 17+: View receives `@Observable` object and needs bindings | For injected observables |
27| `let` | Read-only value passed from parent | Simplest option |
28| `var` | Read-only value that child observes via `.onChange()` | For reactive reads |
29 
30**Legacy (Pre-iOS 17):**
31| Wrapper | Use When | Notes |
32|---------|----------|-------|
33| `@StateObject` | View owns an `ObservableObject` instance | Use `@State` with `@Observable` instead |
34| `@ObservedObject` | View receives an `ObservableObject` from outside | Never create inline |
35 
36## @State
37 
38Always mark `@State` properties as `private`. Use for internal view state that triggers UI updates.
39 
40```swift
41// Correct
42@State private var isAnimating = false
43@State private var selectedTab = 0
44```
45 
46**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).
47 
48### iOS 17+ with @Observable (Preferred)
49 
50**Always prefer `@Observable` over `ObservableObject`.** With iOS 17's `@Observable` macro, use `@State` instead of `@StateObject`:
51 
52```swift
53@Observable
54@MainActor  // Always mark @Observable classes with @MainActor
55final class DataModel {
56    var name = "Some Name"
57    var count = 0
58}
59 
60struct MyView: View {
61    @State private var model = DataModel()  // Use @State, not @StateObject
62 
63    var body: some View {
64        VStack {
65            TextField("Name", text: $model.name)
66            Stepper("Count: \(model.count)", value: $model.count)
67        }
68    }
69}
70```
71 
72**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`).
73 
74**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.
75 
76## Property Wrappers Inside @Observable Classes
77 
78**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.
79 
80**Always annotate property-wrapper properties with `@ObservationIgnored` inside `@Observable` classes.**
81 
82```swift
83@Observable
84@MainActor
85final class SettingsModel {
86    // WRONG - compiler error: property wrappers conflict with @Observable
87    // @AppStorage("username") var username = ""
88 
89    // CORRECT - @ObservationIgnored prevents the conflict
90    @ObservationIgnored @AppStorage("username") var username = ""
91    @ObservationIgnored @AppStorage("isDarkMode") var isDarkMode = false
92 
93    // Regular stored properties work fine with @Observable
94    var isLoading = false
95}
96```
97 
98This applies to **any** property wrapper used inside an `@Observable` class, including but not limited to:
99- `@AppStorage`
100- `@SceneStorage`
101- `@Query` (SwiftData)
102 
103**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.
104 
105**Never remove `@ObservationIgnored`** from property-wrapper properties in `@Observable` classes — doing so causes a compiler error.
106 
107## @Binding
108 
109Use only when child view needs to **modify** parent's state. If child only reads the value, use `let` instead.
110 
111```swift
112// Parent
113struct ParentView: View {
114    @State private var isSelected = false
115 
116    var body: some View {
117        ChildView(isSelected: $isSelected)
118    }
119}
120 
121// Child - will modify the value
122struct ChildView: View {
123    @Binding var isSelected: Bool
124 
125    var body: some View {
126        Button("Toggle") {
127            isSelected.toggle()
128        }
129    }
130}
131```
132 
133### When NOT to use @Binding
134 
135- **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.
136 
137## @FocusState
138 
139See `references/focus-patterns.md` for comprehensive focus management guidance including `@FocusState`, `@FocusedValue`, `.focusable()`, default focus, and common pitfalls.
140 
141Always mark `@FocusState` as `private`.
142 
143## @StateObject vs @ObservedObject (Legacy - Pre-iOS 17)
144 
145**Note**: Always prefer `@Observable` with `@State` for iOS 17+.
146 
147The key distinction is **ownership**: `@StateObject` when the view **creates and owns** the object; `@ObservedObject` when the view **receives** it from outside.
148 
149```swift
150// View creates it → @StateObject
151@StateObject private var viewModel = MyViewModel()
152 
153// View receives it → @ObservedObject
154@ObservedObject var viewModel: MyViewModel
155```
156 
157**Never** create an `ObservableObject` inline with `@ObservedObject` -- it recreates the instance on every view update.
158 
159### @StateObject instantiation in View's initializer
160 
161Prefer 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:
162 
163```swift
164// Inside a View's init(movie:):
165// WRONG — assigning to a local first defeats @autoclosure
166let vm = MovieDetailsViewModel(movie: movie)
167_viewModel = StateObject(wrappedValue: vm)
168 
169// CORRECT — inline expression defers creation
170_viewModel = StateObject(wrappedValue: MovieDetailsViewModel(movie: movie))
171```
172 
173**Modern Alternative**: Use `@Observable` with `@State` instead.
174 
175## Don't Pass Values as @State
176 
177**Critical**: Never declare passed values as `@State` or `@StateObject`. They only accept an initial value and ignore subsequent updates from the parent.
178 
179```swift
180// WRONG - child ignores parent updates
181struct ChildView: View {
182    @State var item: Item  // Shows initial value forever!
183    var body: some View { Text(item.name) }
184}
185 
186// CORRECT - child receives updates
187struct ChildView: View {
188    let item: Item  // Or @Binding if child needs to modify
189    var body: some View { Text(item.name) }
190}
191```
192 
193**Prevention**: Always mark `@State` and `@StateObject` as `private`. This prevents them from appearing in the generated initializer.
194 
195## @Bindable (iOS 17+)
196 
197Use when receiving an `@Observable` object from outside and needing bindings:
198 
199```swift
200@Observable
201final class UserModel {
202    var name = ""
203    var email = ""
204}
205 
206struct ParentView: View {
207    @State private var user = UserModel()
208 
209    var body: some View {
210        EditUserView(user: user)
211    }
212}
213 
214struct EditUserView: View {
215    @Bindable var user: UserModel  // Received from parent, needs bindings
216 
217    var body: some View {
218        Form {
219            TextField("Name", text: $user.name)
220            TextField("Email", text: $user.email)
221        }
222    }
223}
224```
225 
226## let vs var for Passed Values
227 
228### Use `let` for read-only display
229 
230```swift
231struct ProfileHeader: View {
232    let username: String
233    let avatarURL: URL
234 
235    var body: some View {
236        HStack {
237            AsyncImage(url: avatarURL)
238            Text(username)
239        }
240    }
241}
242```
243 
244### Use `var` when reacting to changes with `.onChange()`
245 
246```swift
247struct ReactiveView: View {
248    var externalValue: Int  // Watch with .onChange()
249    @State private var displayText = ""
250 
251    var body: some View {
252        Text(displayText)
253            .onChange(of: externalValue) { oldValue, newValue in
254                displayText = "Changed from \(oldValue) to \(newValue)"
255            }
256    }
257}
258```
259 
260## Environment and Preferences
261 
262### @Environment
263 
264Access environment values provided by SwiftUI or parent views:
265 
266```swift
267struct MyView: View {
268    @Environment(\.colorScheme) private var colorScheme
269    @Environment(\.dismiss) private var dismiss
270 
271    var body: some View {
272        Button("Done") { dismiss() }
273            .foregroundStyle(colorScheme == .dark ? .white : .black)
274    }
275}
276```
277 
278### Custom Environment Values with @Entry
279 
280Use the `@Entry` macro (Xcode 16+, backward compatible to iOS 13) to define custom environment values without boilerplate:
281 
282```swift
283extension EnvironmentValues {
284    @Entry var accentTheme: Theme = .default
285}
286 
287// Inject
288ContentView()
289    .environment(\.accentTheme, customTheme)
290 
291// Access
292struct ThemedView: View {
293    @Environment(\.accentTheme) private var theme
294}
295```
296 
297The `@Entry` macro replaces the manual `EnvironmentKey` conformance pattern. It also works with `TransactionValues`, `ContainerValues`, and `FocusedValues`.
298 
299### @Environment with @Observable (iOS 17+ - Preferred)
300 
301**Always prefer this pattern** for sharing state through the environment:
302 
303```swift
304@Observable
305@MainActor
306final class AppState {
307    var isLoggedIn = false
308}
309 
310// Inject
311ContentView()
312    .environment(AppState())
313 
314// Access
315struct ChildView: View {
316    @Environment(AppState.self) private var appState
317}
318```
319 
320### @EnvironmentObject (Legacy - Pre-iOS 17)
321 
322Legacy pattern: inject with `.environmentObject(AppState())`, access with `@EnvironmentObject var appState: AppState`. Prefer `@Observable` with `@Environment` instead.
323 
324## Decision Flowchart
325 
326```
327Is this value owned by this view?
328├─ YES: Is it a simple value type?
329│       ├─ YES → @State private var
330│       └─ NO (class):
331│           ├─ Use @Observable → @State private var (mark class @MainActor)
332│           └─ Legacy ObservableObject → @StateObject private var
333│
334└─ NO (passed from parent):
335    ├─ Does child need to MODIFY it?
336    │   ├─ YES → @Binding var
337    │   └─ NO: Does child need BINDINGS to its properties?
338    │       ├─ YES (@Observable) → @Bindable var
339    │       └─ NO: Does child react to changes?
340    │           ├─ YES → var + .onChange()
341    │           └─ NO → let
342    │
343    └─ Is it a legacy ObservableObject from parent?
344        └─ YES → @ObservedObject var (consider migrating to @Observable)
345```
346 
347## State Privacy Rules
348 
349**All view-owned state should be `private`:**
350 
351```swift
352// Correct - clear what's created vs passed
353struct MyView: View {
354    // Created by view - private
355    @State private var isExpanded = false
356    @State private var viewModel = ViewModel()
357    @AppStorage("theme") private var theme = "light"
358    @Environment(\.colorScheme) private var colorScheme
359    
360    // Passed from parent - not private
361    let title: String
362    @Binding var isSelected: Bool
363    @Bindable var user: User
364    
365    var body: some View {
366        // ...
367    }
368}
369```
370 
371**Why**: This makes dependencies explicit and improves code completion for the generated initializer.
372 
373## Avoid Nested ObservableObject
374 
375**Note**: This limitation only applies to `ObservableObject`. `@Observable` fully supports nested observed objects.
376 
377SwiftUI can't track changes through nested `ObservableObject` properties. Workaround: pass the nested object directly to child views as `@ObservedObject`. With `@Observable`, nesting works automatically.
378 
379## Key Principles
380 
3811. **Always prefer `@Observable` over `ObservableObject`** for new code
3822. **Mark `@Observable` classes with `@MainActor` for thread safety (unless using default actor isolation)`**
3833. Use `@State` with `@Observable` classes (not `@StateObject`)
3844. Use `@Bindable` for injected `@Observable` objects that need bindings
3855. **Always mark `@State` and `@StateObject` as `private`**
3866. **Never declare passed values as `@State` or `@StateObject`**
3877. With `@Observable`, nested objects work fine; with `ObservableObject`, pass nested objects directly to child views
3888. **Always add `@ObservationIgnored` to property wrappers** (e.g., `@AppStorage`, `@SceneStorage`, `@Query`) inside `@Observable` classes — they conflict with the macro's property transformation
389