axiom-swiftui-search-ref

# SwiftUI Search API Reference

## Overview

SwiftUI search is **environment-based and navigation-consumed**. You attach `.searchable()` to a view, but a *navigation container* (NavigationStack, NavigationSplitView, or TabView) renders the actual search field. This indirection is the source of most search bugs.

#### API Evolution

| iOS | Key Additions |
|-----|---------------|
| 15 | `.searchable(text:)`, `isSearching`, `dismissSearch`, suggestions, `.searchCompletion()`, `onSubmit(of: .search)` |
| 16 | Search scopes (`.searchScopes`), search tokens (`.searchable(text:tokens:)`), `SearchScopeActivation` |
| 16.4 | Search scope `activation` parameter (`.onTextEntry`, `.onSearchPresentation`) |
| 17 | `isPresented` parameter, `suggestedTokens` parameter |
| 17.1 | `.searchPresentationToolbarBehavior(.avoidHidingContent)` |
| 18 | `.searchFocused($isFocused)` for programmatic focus control |
| 26 | Bottom-aligned search, `.searchToolbarBehavior(.minimize)`, `Tab(role: .search)`, `DefaultToolbarItem(kind: .search)` — see `axiom-swiftui-26-ref` |

## When to Use This Skill

- Adding search to a SwiftUI list or collection
- Implementing filter-as-you-type or submit-based search
- Adding search suggestions with auto-completion
- Using search scopes to narrow results by category
- Using search tokens for structured queries
- Controlling search focus programmatically
- Debugging "search field doesn't appear" issues

For iOS 26 search features (bottom-aligned, minimized toolbar, search tab role), see `axiom-swiftui-26-ref`.

---

## Part 1: The searchable Modifier

### Core API

```swift
.searchable(
    text: Binding<String>,
    placement: SearchFieldPlacement = .automatic,
    prompt: LocalizedStringKey
)
```

**Availability**: iOS 15+, macOS 12+, tvOS 15+, watchOS 8+

### How It Works

1. You attach `.searchable(text: $query)` to a view
2. The **nearest navigation container** (NavigationStack, NavigationSplitView) renders the search field
3. The view receives `isSearch