1# SwiftUI Focus Patterns Reference
2 
3## Table of Contents
4 
5- [@FocusState](#focusstate)
6- [Making Views Focusable](#making-views-focusable)
7- [Focused Values for Commands and Menus](#focused-values-for-commands-and-menus)
8- [Default Focus](#default-focus)
9- [Focus Scope and Sections](#focus-scope-and-sections)
10- [Focus Effects](#focus-effects)
11- [Search Focus](#search-focus)
12- [Common Pitfalls](#common-pitfalls)
13 
14## @FocusState
15 
16Always mark `@FocusState` as `private`. Use `Bool` for a single field, an optional `Hashable` enum for multiple fields.
17 
18### Single field
19 
20```swift
21@FocusState private var isFocused: Bool
22 
23TextField("Email", text: $email)
24    .focused($isFocused)
25```
26 
27### Multiple fields
28 
29```swift
30enum Field: Hashable { case name, email, password }
31@FocusState private var focusedField: Field?
32 
33TextField("Name", text: $name)
34    .focused($focusedField, equals: .name)
35TextField("Email", text: $email)
36    .focused($focusedField, equals: .email)
37```
38 
39Set `focusedField = .email` to move focus programmatically; set `nil` to dismiss the keyboard.
40 
41### `focused(_:)` vs `focused(_:equals:)` with nested views
42 
43`.focused($bool)` reports `true` when the modified view *or any focusable descendant* has focus. `.focused($enum, equals:)` reports its value only when that specific view receives focus.
44 
45```swift
46enum Focus: Hashable { case container, field }
47@FocusState private var focus: Focus?
48 
49VStack {
50    TextField("Name", text: $name)
51        .focused($focus, equals: .field)
52}
53.focusable()
54.focused($focus, equals: .container)
55```
56 
57With `focused(_:equals:)` and a single `@FocusState`, SwiftUI distinguishes the container *receiving* focus from the container merely *containing* focus.
58 
59### `isFocused` environment value
60 
61Read-only environment value that returns `true` when the nearest focusable ancestor has focus. Useful for styling non-focusable child views.
62 
63```swift
64struct HighlightWrapper: View {
65    @Environment(\.isFocused) private var isFocused
66 
67    var body: some View {
68        content
69            .background(isFocused ? Color.accentColor.opacity(0.1) : .clear)
70    }
71}
72```
73 
74## Making Views Focusable
75 
76### `.focusable(_:)`
77 
78Makes a non-text-input view participate in the focus system. Focused views can respond to keyboard events via `onKeyPress` and menu commands like Edit > Delete via `onDeleteCommand`.
79 
80```swift
81struct SelectableCard: View {
82    @FocusState private var isFocused: Bool
83 
84    var body: some View {
85        CardContent()
86            .focusable()
87            .focused($isFocused)
88            .border(isFocused ? Color.accentColor : .clear)
89            .onDeleteCommand { deleteCard() }
90    }
91}
92```
93 
94### `.focusable(_:interactions:)` (iOS 17+)
95 
96Controls which focus-driven interactions the view supports via `FocusInteractions`:
97 
98- `.activate` -- Button-like: only focusable when system-wide keyboard navigation is on (macOS/iOS)
99- `.edit` -- Captures keyboard/Digital Crown input
100- `.automatic` -- Platform default (both activate and edit)
101 
102```swift
103MyTapGestureView(...)
104    .focusable(interactions: .activate)
105```
106 
107Use `.activate` for custom button-like views that should match system keyboard-navigation behavior.
108 
109## Focused Values for Commands and Menus
110 
111Focused values let parent views (App, Scene, Commands) read state from whichever view currently has focus. Use for enabling/disabling menu commands based on the focused document or selection.
112 
113### Declare with `@Entry`
114 
115```swift
116extension FocusedValues {
117    @Entry var selectedDocument: Binding<Document>?
118}
119```
120 
121Focused values are typically optional (default is `nil` when no view publishes them), but you can also use non-optional entries when you have a sensible default value.
122 
123### Publish from views
124 
125```swift
126// View-scoped: available when this view (or descendant) has focus
127.focusedValue(\.selectedDocument, $document)
128 
129// Scene-scoped: available when this scene has focus
130.focusedSceneValue(\.selectedDocument, $document)
131```
132 
133### Consume in commands
134 
135`@FocusedValue` reads the value; `@FocusedBinding` unwraps a `Binding` automatically.
136 
137```swift
138@main
139struct MyApp: App {
140    @FocusedBinding(\.selectedDocument) var document
141 
142    var body: some Scene {
143        WindowGroup {
144            ContentView()
145        }
146        .commands {
147            CommandGroup(after: .pasteboard) {
148                Button("Duplicate") { document?.duplicate() }
149                    .disabled(document == nil)
150            }
151        }
152    }
153}
154```
155 
156### `@FocusedObject` (iOS 16+)
157 
158For `ObservableObject` types. The view invalidates when the focused object changes.
159 
160```swift
161// Publish
162.focusedObject(myObservableModel)
163 
164// Consume
165@FocusedObject var model: MyModel?
166```
167 
168Scene-scoped variant: `.focusedSceneObject(_:)`.
169 
170## Default Focus
171 
172### `.defaultFocus(_:_:priority:)` (iOS 17+, macOS 13+, tvOS 16+)
173 
174Prefer `.defaultFocus` over setting `@FocusState` in `onAppear` for initial focus placement.
175 
176```swift
177@FocusState private var focusedField: Field?
178 
179VStack {
180    TextField("Name", text: $name)
181        .focused($focusedField, equals: .name)
182    TextField("Email", text: $email)
183        .focused($focusedField, equals: .email)
184}
185.defaultFocus($focusedField, .email)
186```
187 
188**Priority**: `.automatic` (default) applies on window appearance and programmatic focus changes. `.userInitiated` also applies during user-driven focus navigation.
189 
190### `prefersDefaultFocus(_:in:)` (macOS/tvOS/watchOS)
191 
192Used with `.focusScope(_:)` to mark a preferred default target within a scoped region.
193 
194### `resetFocus` environment action (macOS/tvOS/watchOS)
195 
196Re-evaluates default focus within a namespace.
197 
198```swift
199@Namespace var scopeID
200@Environment(\.resetFocus) private var resetFocus
201 
202Button("Reset") { resetFocus(in: scopeID) }
203```
204 
205## Focus Scope and Sections
206 
207### `.focusScope(_:)` (macOS/tvOS/watchOS)
208 
209Limits default focus preferences to a namespace. Use with `prefersDefaultFocus` and `resetFocus`.
210 
211### `.focusSection()` (macOS 13+, tvOS 15+)
212 
213Guides directional and sequential focus movement through a group of focusable descendants. Useful when focusable views are spatially separated and directional navigation would otherwise skip them.
214 
215```swift
216HStack {
217    VStack { Button("1") {}; Button("2") {}; Spacer() }
218    Spacer()
219    VStack { Spacer(); Button("A") {}; Button("B") {} }
220        .focusSection()
221}
222```
223 
224Without `.focusSection()`, swiping right from buttons 1/2 finds nothing. With it, the VStack receives directional focus and delivers it to its first focusable child.
225 
226## Focus Effects
227 
228### `.focusEffectDisabled(_:)`
229 
230Suppresses the system focus ring (macOS) or hover effect. Use when providing custom focus visuals.
231 
232```swift
233MyCustomCard()
234    .focusable()
235    .focusEffectDisabled()
236    .overlay { customFocusRing }
237```
238 
239`isFocusEffectEnabled` environment value reads the current state.
240 
241## Search Focus
242 
243### `.searchFocused(_:)` / `.searchFocused(_:equals:)`
244 
245Bind focus state to the search field associated with the nearest `.searchable` modifier. Works like `.focused` but targets the search bar.
246 
247```swift
248@FocusState private var isSearchFocused: Bool
249 
250NavigationStack {
251    ContentView()
252        .searchable(text: $query)
253        .searchFocused($isSearchFocused)
254}
255 
256// Programmatically focus the search bar
257Button("Search") { isSearchFocused = true }
258```
259 
260## Common Pitfalls
261 
262### Redundant `@FocusState` writes revoke focus
263 
264`.focusable()` + `.focused()` handles focus-on-click natively. Adding a tap gesture that *also* writes to `@FocusState` triggers a redundant state write, causing a second body evaluation that revokes focus. The result: focus briefly appears then disappears, and key commands like `onDeleteCommand` stop working.
265 
266```swift
267// WRONG -- tap gesture redundantly sets focus, causing double evaluation
268CardView()
269    .focusable()
270    .focused($isFocused)
271    .onTapGesture { isFocused = true }  // Remove this line
272 
273// CORRECT -- let .focusable() + .focused() handle it
274CardView()
275    .focusable()
276    .focused($isFocused)
277```
278 
279### Ambiguous focus bindings
280 
281Binding the same enum case to multiple views is ambiguous. SwiftUI picks the first candidate and emits a runtime warning.
282 
283```swift
284// WRONG -- .name bound to two views
285TextField("Name", text: $name)
286    .focused($focusedField, equals: .name)
287TextField("Full Name", text: $fullName)
288    .focused($focusedField, equals: .name)  // ambiguous
289```
290 
291Always use distinct enum cases for each focusable view.
292 
293### `.onAppear` focus timing
294 
295Setting `@FocusState` in `.onAppear` may fail if the view tree hasn't settled. Prefer `.defaultFocus` (iOS 17+) for reliable initial focus. If you must use `.onAppear`, wrap in `DispatchQueue.main.async` as a last resort.
296 
297### Missing `.focusable()` for non-text views
298 
299`TextField` and `SecureField` are implicitly focusable. Custom views (stacks, shapes, images) are not. Forgetting `.focusable()` means `.focused()` bindings have no effect and key event handlers never fire.
300