axiom-swiftui-search-ref（axiom swiftui 搜索参考）

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

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)
    }
}

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

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:

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

Environment Values

Types

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+