@FocusState — what it is, managing focus and keyboard in SwiftUI

What is @FocusState in SwiftUI

@FocusState is a property wrapper that ties the focus state to a specific input field or other focusable element in SwiftUI. Unlike UIKit, where focus management happens through becomeFirstResponder and resignFirstResponder methods, SwiftUI uses a declarative approach: you declare a state (@FocusState) and bind it to an element via the .focused() modifier. Changing the state automatically changes the focus.

Before @FocusState was introduced in iOS 15, developers had to create UIViewRepresentable wrappers around UITextField or use third-party libraries. @FocusState is integrated directly into SwiftUI and works with TextField, TextEditor, SecureField, and SearchField. This makes code cleaner, reduces the number of UIKit bridges, and improves testability.

According to WWDC Session 10136 — What's new in SwiftUI (2024), @FocusState uses SwiftUI's preference key system to pass focus information between elements. When a field receives focus, SwiftUI automatically updates the associated @FocusState property, allowing you to react to focus changes in code.

Managing Focus with Bool

The simplest way to use @FocusState is with the Bool type. When a field is focused, the property is true. When focus is lost — false. You can force focus by setting it to true, or clear it by setting it to false.

struct LoginForm: View {
    @State var email = ""
    @FocusState var isEmailFocused: Bool
    
    var body: some View {
        VStack {
            TextField("Email", text: $email)
                .focused($isEmailFocused)
            
            Button("Show Keyboard") {
                isEmailFocused = true
            }
            Button("Hide Keyboard") {
                isEmailFocused = false
            }
        }
    }
}

In this example, isEmailFocused automatically becomes true when the user taps on the text field, and false when the keyboard is dismissed. The buttons allow you to manage focus programmatically — useful for custom keyboards, "Next" buttons, and situations where you need to force-dismiss the keyboard after form submission.

Managing Focus with Enum for Multiple Fields

For forms with multiple fields, @FocusState supports an enum conforming to the FocusStateValue (or Hashable) protocol. Each enum case corresponds to a specific field. This allows switching focus between fields — for example, when the user presses "Next" on the keyboard to move to the next field.

struct RegistrationForm: View {
    enum Field: Hashable {
        case email
        case password
        case confirmPassword
    }
    
    @State var email = ""
    @State var password = ""
    @State var confirmPassword = ""
    @FocusState var focusedField: Field?
    
    var body: some View {
        Form {
            TextField("Email", text: $email)
                .focused($focusedField, equals: .email)
                .onSubmit { focusedField = .password }
            
            SecureField("Password", text: $password)
                .focused($focusedField, equals: .password)
                .onSubmit { focusedField = .confirmPassword }
            
            SecureField("Confirm", text: $confirmPassword)
                .focused($focusedField, equals: .confirmPassword)
                .onSubmit { submitForm() }
        }
    }
}

Note the .onSubmit modifier — it is called when the user presses "Return" on the keyboard. Inside .onSubmit we switch focusedField to the next field, which automatically moves focus. The last field calls submitForm() to submit the form.

Hiding and Showing the Keyboard

@FocusState provides a simple way to hide the keyboard — just set the property to nil (for enum) or false (for Bool). However, sometimes you need to hide the keyboard without tying it to a specific field — for example, when tapping on empty space. In this case, there are several approaches.

struct DismissKeyboardView: View {
    @State var text = ""
    @FocusState var isFocused: Bool
    
    var body: some View {
        TextField("Enter text", text: $text)
            .focused($isFocused)
            .toolbar {
                ToolbarItemGroup(placement: .keyboard) {
                    Spacer()
                    Button("Done") {
                        isFocused = false
                    }
                }
            }
    }
}

The .toolbar modifier with placement .keyboard adds a button above the keyboard. This is a standard UX pattern in iOS for dismissing the keyboard. An alternative approach is to use .onTapGesture on the root VStack to reset focus when tapping on the background.

Focus and Form Validation

@FocusState combines perfectly with form validation. A typical pattern: after pressing the "Submit" button, validate all fields and set focus to the first field with an error. This improves the user experience — the user immediately sees which field needs to be corrected.

struct ValidatedForm: View {
    enum Field: Hashable { case name; case phone }
    
    @State var name = ""
    @State var phone = ""
    @FocusState var focusedField: Field?
    @State var errors: [String] = []
    
    var body: some View {
        Form {
            TextField("Name", text: $name)
                .focused($focusedField, equals: .name)
            TextField("Phone", text: $phone)
                .focused($focusedField, equals: .phone)
            
            Button("Submit") { validateAndSubmit() }
        }
    }
    
    func validateAndSubmit() {
        if name.isEmpty {
            focusedField = .name
            return
        }
        if phone.isEmpty {
            focusedField = .phone
            return
        }
        // submit form
    }
}

In this example, if the name field is empty, focus moves to it, and the user immediately sees where the error is. If name is filled, phone is checked. This is natural behavior for forms — the user fills fields from top to bottom, and validation follows the same order.

Common Mistakes with @FocusState

The most common mistake is trying to use @FocusState with a type that does not conform to Hashable. @FocusState requires the property type to be Hashable (Bool and optional enums already conform). If you are trying to use a custom structure, make sure it implements Hashable.

• Forgot .focused() modifier — @FocusState on its own does not manage focus. You must bind it to a field via .focused($property) or .focused($property, equals: .case).
• Multiple @FocusState in one View — for multiple fields, use a single @FocusState with an enum, not multiple @FocusState properties. Multiple Bool properties will not be synchronized with each other.
• Changing @FocusState off the main thread — @FocusState should only be changed on the main thread, like all UI properties in SwiftUI. Asynchronous operations must switch to MainActor before changing it.
• Focus reset on view rebuild — if the View is rebuilt, @FocusState may reset. Use the .id() modifier for stable View identification.

// ❌ Wrong: two @FocusState Bool instead of enum
@FocusState var isNameFocused: Bool
@FocusState var isEmailFocused: Bool

// ✅ Correct: single enum @FocusState
enum Field: Hashable { case name; case email }
@FocusState var focusedField: Field?