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

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

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 {
<