Swiftui Input API

User Input API Reference

Lifecycle Position

Phase 3 API Reference — load during implementation when building forms, text fields, or interactive controls. Dispatched from autonomous-ui-workflow Phase 2 research table.

Text Input

TextField("Username", text: $username)
TextField(text: $username, prompt: Text("Required")) { Text("Username") }
SecureField("Password", text: $password)
TextEditor(text: $notes)
TextEditor(text: $attributedText, selection: $selection)  // rich text

Text Modifiers

Controls

Picker("Choice", selection: $choice) { Text("A").tag(0) }.pickerStyle(.menu)
Slider(value: $volume, in: 0...100)
Stepper("Qty: \(count)", value: $count, in: 1...10)
Toggle("Feature", isOn: $isEnabled).toggleStyle(.switch)

Keyboard Shortcuts

Button("Save") { save() }.keyboardShortcut("s", modifiers: .command)
Button("OK") { confirm() }.keyboardShortcut(.defaultAction)

Key Press Handling

.onKeyPress(.return) { submit(); return .handled }
.onKeyPress(phases: .down) { keyPress in return .handled }
.onKeyPress(characters: .alphanumerics, phases: .down) { _ in .handled }
.onModifierKeysChanged(mask: .shift) { old, new in }

When to Use Which

Focus Management (Critical for forms)

enum Field: Hashable { case name, email, password }
@FocusState private var focus: Field?

TextField("Name", text: $name)
    .focused($focus, equals: .name)
    .onSubmit { focus = .email }
    .submitLabel(.next)

TextField("Email", text: $email)
    .focused($focus, equals: .email)
    .textContentType(.emailAddress)
    .onSubmit { focus = .password }
    .submitLabel(.next)

SecureField("Password", text: $password)
    .focused($focus, equals: .password)
    .onSubmit { submit() }
    .submitLabel(.done)

macOS Form Conventions

• Use Form in Settings scene for preference windows
• Use LabeledContent("Label") { control } for aligned form rows
• Use Toggle, Picker with .pickerStyle(.menu) for macOS-native feel
• Keyboard shortcuts: .keyboardShortcut("s", modifiers: .command) on save buttons

Common Mistakes

1. No @FocusState in forms — user can't Tab between fields on macOS or use Next on iOS keyboard
2. TextField without .textContentType() — misses AutoFill for emails, passwords, addresses
3. Using onTapGesture to dismiss keyboard instead of .scrollDismissesKeyboard(.interactively)
4. Missing .submitLabel() — iOS keyboard shows generic "return" instead of "Next"/"Done"/"Search"
5. DatePicker without .datePickerStyle() on macOS — defaults may not fit the layout

Before (incorrect):

// Form with no focus management:
TextField("Email", text: $email)
TextField("Password", text: $password)
// User must tap each field manually; Tab does nothing on macOS

After (correct):

enum Field: Hashable { case email, password }
@FocusState private var focus: Field?

TextField("Email", text: $email)
    .focused($focus, equals: .email)
    .textContentType(.emailAddress)
    .submitLabel(.next)
    .onSubmit { focus = .password }

SecureField("Password", text: $password)
    .focused($focus, equals: .password)
    .textContentType(.password)
    .submitLabel(.done)
    .onSubmit { login() }

Before (incorrect):

// Dismiss keyboard on tap — brittle, misses scroll gesture:
.onTapGesture { UIApplication.shared.sendAction(#selector(UIResponder.resignFirstResponder), ...) }

After (correct):

ScrollView {
    // form content
}
.scrollDismissesKeyboard(.interactively)

Checklist

• All form fields have @FocusState for keyboard/Tab navigation
• Text fields have .textContentType() for AutoFill
• .submitLabel() set on all text fields in forms
• .onSubmit chains focus to next field (or submits on last field)
• macOS forms use LabeledContent for alignment
• .searchable() used instead of custom search TextField in navigation contexts

Cross-References

• swiftui-presentation-api — sheets and alerts that contain forms
• swiftui-typography-api — text styles for form labels
• swiftui-ui-patterns — state management for form data (@Observable view model pattern)
• swiftui-26-api — iOS 26 rich text: AttributedTextSelection, AttributedTextFormattingDefinition, FindContext