axiom-swiftui-search-ref

name	axiom-swiftui-search-ref
description	Use when implementing SwiftUI search — .searchable, isSearching, search suggestions, scopes, tokens, programmatic search control (iOS 15-18). For iOS 26 search refinements (bottom-aligned, minimized toolbar, search tab role), see swiftui-26-ref.
license	MIT
metadata	{"version":"1.0.0"}

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

.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 isSearching and dismissSearch through the environment
4. Your view filters or queries based on the bound text

struct RecipeListView: View {
    @State private var searchText = ""
    let recipes: [Recipe]

    var body: some View {
        NavigationStack {
            List(filteredRecipes) { recipe in
                NavigationLink(recipe.name, value: recipe)
            }
            .navigationTitle("Recipes")
            .searchable(text: $searchText, prompt: "Find a recipe")
        }
    }

    var filteredRecipes: [Recipe] {
        if searchText.isEmpty { return recipes }
        return recipes.filter { $0.name.localizedCaseInsensitiveContains(searchText) }
    }
}

Placement Options

Placement	Behavior
.automatic	System decides (recommended)
.navigationBarDrawer	Below navigation bar title (iOS)
.navigationBarDrawer(displayMode: .always)	Always visible, not hidden on scroll
.sidebar	In the sidebar column (NavigationSplitView)
.toolbar	In the toolbar area
.toolbarPrincipal	In toolbar's principal section

Gotcha: SwiftUI may ignore your placement preference if the view hierarchy doesn't support it. Always test on the target platform.

Column Association in NavigationSplitView

Where you attach .searchable determines which column displays the search field:

NavigationSplitView {
    SidebarView()
        .searchable(text: $query)  // Search in sidebar
} detail: {
    DetailView()
}

// vs.

NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
        .searchable(text: $query)  // Search in detail
}

// vs.

NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
}
.searchable(text: $query)  // System decides column

---

Part 2: Displaying Search Results

isSearching Environment

@Environment(\.isSearching) private var isSearching

Availability: iOS 15+

Becomes true when the user activates search (taps the field), false when they cancel or you call dismissSearch.

Critical rule: isSearching must be read from a child of the view that has .searchable. SwiftUI sets the value in the searchable view's environment and does not propagate it upward.

// Pattern: Overlay search results when searching
struct WeatherCityList: View {
    @State private var searchText = ""

    var body: some View {
        NavigationStack {
            // SearchResultsOverlay reads isSearching
            SearchResultsOverlay(searchText: searchText) {
                List(favoriteCities) { city in
                    CityRow(city: city)
                }
            }
            .searchable(text: $searchText)
            .navigationTitle("Weather")
        }
    }
}

struct SearchResultsOverlay<Content: View>: View {
    let searchText: String
    @ViewBuilder let content: Content
    @Environment(\.isSearching) private var isSearching

    var body: some View {
        if isSearching {
            // Show search results
            SearchResults(query: searchText)
        } else {
            content
        }
    }
}

dismissSearch Environment

@Environment(\.dismissSearch) private var dismissSearch

Availability: iOS 15+

Calling dismissSearch() clears the search text, removes focus, and sets isSearching to false. Must be called from inside the searchable view hierarchy.

struct SearchResults: View {
    @Environment(\.dismissSearch) private var dismissSearch

    var body: some View {
        List(results) { result in
            Button(result.name) {
                selectResult(result)
                dismissSearch()  // Close search after selection
            }
        }
    }
}

---

Part 3: Search Suggestions

Adding Suggestions

Pass a suggestions closure to .searchable:

.searchable(text: $searchText) {
    ForEach(suggestedResults) { suggestion in
        Text(suggestion.name)
            .searchCompletion(suggestion.name)
    }
}

Availability: iOS 15+

Suggestions appear in a list below the search field when the user is typing.

searchCompletion Modifier

.searchCompletion(_:) binds a suggestion to a completion value. When the user taps the suggestion, the search text is replaced with the completion value.

.searchable(text: $searchText) {
    ForEach(matchingColors) { color in
        HStack {
            Circle()
                .fill(color.value)
                .frame(width: 16, height: 16)
            Text(color.name)
        }
        .searchCompletion(color.name)  // Tapping fills search with color name
    }
}

Without .searchCompletion(): Suggestions display but tapping them does nothing to the search field. This is the most common suggestions bug.

Complete Suggestion Pattern

struct ColorSearchView: View {
    @State private var searchText = ""
    let allColors: [NamedColor]

    var body: some View {
        NavigationStack {
            List(filteredColors) { color in
                ColorRow(color: color)
            }
            .navigationTitle("Colors")
            .searchable(text: $searchText, prompt: "Search colors") {
                ForEach(suggestedColors) { color in
                    Label(color.name, systemImage: "paintpalette")
                        .searchCompletion(color.name)
                }
            }
        }
    }

    var suggestedColors: [NamedColor] {
        guard !searchText.isEmpty else { return [] }
        return allColors.filter {
            $0.name.localizedCaseInsensitiveContains(searchText)
        }
        .prefix(5)
        .map { $0 }  // Convert ArraySlice to Array
    }

    var filteredColors: [NamedColor] {
        if searchText.isEmpty { return allColors }
        return allColors.filter {
            $0.name.localizedCaseInsensitiveContains(searchText)
        }
    }
}

---

Part 4: Search Submission

onSubmit(of: .search)

Triggers when the user presses Return/Enter in the search field:

.searchable(text: $searchText)
.onSubmit(of: .search) {
    performSearch(searchText)
}

Availability: iOS 15+

Filter vs Submit Decision

Pattern	Use When	Example
Filter-as-you-type	Local data, fast filtering	Contacts, settings
Submit-based search	Network requests, expensive queries	App Store, web search
Combined	Suggestions filter locally, submit triggers server	Maps, shopping

Combined Suggestions + Submit Pattern

struct StoreSearchView: View {
    @State private var searchText = ""
    @State private var searchResults: [Product] = []
    let recentSearches: [String]

    var body: some View {
        NavigationStack {
            List(searchResults) { product in
                ProductRow(product: product)
            }
            .navigationTitle("Store")
            .searchable(text: $searchText, prompt: "Search products") {
                // Local suggestions from recent searches
                ForEach(matchingRecent, id: \.self) { term in
                    Label(term, systemImage: "clock")
                        .searchCompletion(term)
                }
            }
            .onSubmit(of: .search) {
                // Server search on submit
                Task {
                    searchResults = await ProductAPI.search(searchText)
                }
            }
        }
    }

    var matchingRecent: [String] {
        guard !searchText.isEmpty else { return recentSearches }
        return recentSearches.filter {
            $0.localizedCaseInsensitiveContains(searchText)
        }
    }
}

---

Part 5: Search Scopes (iOS 16+)

Adding Scopes

Scopes add a segmented picker below the search field for narrowing results by category:

enum SearchScope: String, CaseIterable {
    case all = "All"
    case recipes = "Recipes"
    case ingredients = "Ingredients"
}

struct ScopedSearchView: View {
    @State private var searchText = ""
    @State private var searchScope: SearchScope = .all

    var body: some View {
        NavigationStack {
            List(filteredResults) { result in
                ResultRow(result: result)
            }
            .navigationTitle("Cookbook")
            .searchable(text: $searchText)
            .searchScopes($searchScope) {
                ForEach(SearchScope.allCases, id: \.self) { scope in
                    Text(scope.rawValue).tag(scope)
                }
            }
        }
    }
}

Availability: iOS 16+, macOS 13+

Scope Activation (iOS 16.4+)

Control when scopes appear:

.searchScopes($searchScope, activation: .onTextEntry) {
    // Scopes appear only when user starts typing
    ForEach(SearchScope.allCases, id: \.self) { scope in
        Text(scope.rawValue).tag(scope)
    }
}

Activation	Behavior
.automatic	System default
.onTextEntry	Scopes appear when user types text
.onSearchPresentation	Scopes appear when search is activated

Platform differences:

• iOS/iPadOS: Scopes appear on text entry by default, dismiss on cancel
• macOS: Scopes appear when search is presented, dismiss on cancel

---

Part 6: Search Tokens (iOS 16+)

Tokens are structured search elements that appear as "pills" in the search field alongside free text.

Basic Tokens

enum RecipeToken: Identifiable, Hashable {
    case cuisine(String)
    case difficulty(String)

    var id: Self { self }
}

struct TokenSearchView: View {
    @State private var searchText = ""
    @State private var tokens: [RecipeToken] = []

    var body: some View {
        NavigationStack {
            List(filteredRecipes) { recipe in
                RecipeRow(recipe: recipe)
            }
            .navigationTitle("Recipes")
            .searchable(text: $searchText, tokens: $tokens) { token in
                switch token {
                case .cuisine(let name):
                    Label(name, systemImage: "globe")
                case .difficulty(let name):
                    Label(name, systemImage: "star")
                }
            }
        }
    }
}

Availability: iOS 16+

Token model requirements: Each token element must conform to Identifiable.

Suggested Tokens (iOS 17+)

.searchable(
    text: $searchText,
    tokens: $tokens,
    suggestedTokens: $suggestedTokens,
    prompt: "Search recipes"
) { token in
    Label(token.displayName, systemImage: token.icon)
}

Availability: iOS 17+ adds suggestedTokens and isPresented parameters.

Combined Tokens + Text Filtering

var filteredRecipes: [Recipe] {
    var results = allRecipes

    // Apply token filters
    for token in tokens {
        switch token {
        case .cuisine(let cuisine):
            results = results.filter { $0.cuisine == cuisine }
        case .difficulty(let difficulty):
            results = results.filter { $0.difficulty == difficulty }
        }
    }

    // Apply text filter
    if !searchText.isEmpty {
        results = results.filter {
            $0.name.localizedCaseInsensitiveContains(searchText)
        }
    }

    return results
}

---

Part 7: Programmatic Search Control (iOS 18+)

searchFocused

Bind a FocusState<Bool> to the search field to activate or dismiss search programmatically:

struct ProgrammaticSearchView: View {
    @State private var searchText = ""
    @FocusState private var isSearchFocused: Bool

    var body: some View {
        NavigationStack {
            VStack {
                Button("Start Search") {
                    isSearchFocused = true  // Activate search field
                }

                List(filteredItems) { item in
                    Text(item.name)
                }
            }
            .navigationTitle("Items")
            .searchable(text: $searchText)
            .searchFocused($isSearchFocused)
        }
    }
}

Availability: iOS 18+, macOS 15+, visionOS 2+

Note: For a non-boolean variant, use .searchFocused(_:equals:) to match specific focus values.

Comparison with dismissSearch

API	Direction	iOS
dismissSearch	Dismiss only	15+
.searchFocused($bool)	Activate or dismiss	18+

Use dismissSearch if you only need to close search. Use searchFocused when you need to programmatically open search (e.g., a floating action button that opens search).

---

Part 8: Platform Behavior

SwiftUI search adapts automatically per platform:

Platform	Default Behavior
iOS	Search bar in navigation bar. Scrolls out of view by default; pull down to reveal.
iPadOS	Same as iOS in compact; may appear in toolbar in regular width.
macOS	Trailing toolbar search field. Always visible.
watchOS	Dictation-first input. Search bar at top of list.
tvOS	Tab-based search with on-screen keyboard.

iOS-Specific Behavior

// Always-visible search field (doesn't scroll away)
.searchable(text: $searchText, placement: .navigationBarDrawer(displayMode: .always))

// Default: search field scrolls out, pull down to reveal
.searchable(text: $searchText)

macOS-Specific Behavior

// Search in toolbar (default on macOS)
.searchable(text: $searchText, placement: .toolbar)

// Search in sidebar
.searchable(text: $searchText, placement: .sidebar)

---

Part 9: Common Gotchas

1. Search Field Doesn't Appear

Cause: .searchable is not inside a navigation container.

// WRONG: No navigation container
List { ... }
    .searchable(text: $query)

// CORRECT: Inside NavigationStack
NavigationStack {
    List { ... }
        .searchable(text: $query)
}

2. isSearching Always Returns false

Cause: Reading isSearching from the wrong view level.

// WRONG: Reading from parent of searchable view
struct ParentView: View {
    @Environment(\.isSearching) var isSearching  // Always false
    @State private var query = ""

    var body: some View {
        NavigationStack {
            ChildView(isSearching: isSearching)
                .searchable(text: $query)
        }
    }
}

// CORRECT: Reading from child view
struct ChildView: View {
    @Environment(\.isSearching) var isSearching  // Works

    var body: some View {
        if isSearching {
            SearchResults()
        } else {
            DefaultContent()
        }
    }
}

3. Suggestions Don't Fill Search Field

Cause: Missing .searchCompletion() on suggestion views.

// WRONG: No searchCompletion
.searchable(text: $query) {
    ForEach(suggestions) { s in
        Text(s.name)  // Displays but tapping does nothing
    }
}

// CORRECT: With searchCompletion
.searchable(text: $query) {
    ForEach(suggestions) { s in
        Text(s.name)
            .searchCompletion(s.name)  // Fills search field on tap
    }
}

4. Placement on Wrong Navigation Level

Cause: Attaching .searchable to the wrong column in NavigationSplitView.

// Might not appear where expected
NavigationSplitView {
    SidebarView()
} detail: {
    DetailView()
}
.searchable(text: $query)  // System chooses column

// Explicit placement
NavigationSplitView {
    SidebarView()
        .searchable(text: $query, placement: .sidebar)  // In sidebar
} detail: {
    DetailView()
}

5. Search Scopes Don't Appear

Cause: Scopes require .searchable on the same view. They also require a navigation container.

// WRONG: Scopes without searchable
List { ... }
    .searchScopes($scope) { ... }

// CORRECT: Scopes alongside searchable
List { ... }
    .searchable(text: $query)
    .searchScopes($scope) {
        Text("All").tag(Scope.all)
        Text("Recent").tag(Scope.recent)
    }

6. iOS 26 Refinements

For bottom-aligned search, .searchToolbarBehavior(.minimize), Tab(role: .search), and DefaultToolbarItem(kind: .search), see axiom-swiftui-26-ref. These build on the foundational APIs documented here.

---

Part 10: API Quick Reference

Modifiers

Modifier	iOS	Purpose
.searchable(text:placement:prompt:)	15+	Add search field
.searchable(text:tokens:token:)	16+	Search with tokens
.searchable(text:tokens:suggestedTokens:isPresented:token:)	17+	Tokens + suggested tokens + presentation control
.searchCompletion(_:)	15+	Auto-fill search on suggestion tap
.searchScopes(_:_:)	16+	Category picker below search
.searchScopes(_:activation:_:)	16.4+	Scopes with activation control
.searchFocused(_:)	18+	Programmatic search focus
.searchPresentationToolbarBehavior(_:)	17.1+	Keep title visible during search
.searchToolbarBehavior(_:)	26+	Compact/minimize search field
onSubmit(of: .search)	15+	Handle search submission

Environment Values

Value	iOS	Purpose
isSearching	15+	Is user actively searching
dismissSearch	15+	Action to dismiss search

Types

Type	iOS	Purpose
SearchFieldPlacement	15+	Where search field renders
SearchScopeActivation	16.4+	When scopes appear

---

Resources

WWDC: 2021-10176, 2022-10023

Docs: /swiftui/view/searchable(text:placement:prompt:), /swiftui/environmentvalues/issearching, /swiftui/view/searchscopes(:activation::), /swiftui/view/searchfocused(_:), /swiftui/searchfieldplacement

Skills: axiom-swiftui-26-ref, axiom-swiftui-nav-ref, axiom-swiftui-nav

---

Last Updated Based on WWDC 2021-10176 "Searchable modifier", sosumi.ai API reference Platforms iOS 15+, iPadOS 15+, macOS 12+, watchOS 8+, tvOS 15+