OpenSkillIndex← back to search
claude-code

Skillshub axiom-swiftui-search-ref

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.

install
source · Clone the upstream repo
git clone https://github.com/ComeOnOliver/skillshub
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/ComeOnOliver/skillshub "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/CharlesWiltgen/Axiom/axiom-swiftui-search-ref" ~/.claude/skills/comeonoliver-skillshub-axiom-swiftui-search-ref && rm -rf "$T"
manifest: skills/CharlesWiltgen/Axiom/axiom-swiftui-search-ref/SKILL.md
source content

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

iOSKey Additions
15
.searchable(text:)
, 
isSearching
, 
dismissSearch
, suggestions, 
.searchCompletion()
, 
onSubmit(of: .search)
16Search scopes (
.searchScopes
), search tokens (
.searchable(text:tokens:)
), 
SearchScopeActivation
16.4Search scope 
activation
parameter (
.onTextEntry
, 
.onSearchPresentation
)
17
isPresented
parameter, 
suggestedTokens
parameter
17.1
.searchPresentationToolbarBehavior(.avoidHidingContent)
18
.searchFocused($isFocused)
for programmatic focus control
26Bottom-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

PlacementBehavior
.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

PatternUse WhenExample
Filter-as-you-typeLocal data, fast filteringContacts, settings
Submit-based searchNetwork requests, expensive queriesApp Store, web search
CombinedSuggestions filter locally, submit triggers serverMaps, 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)
    }
}
ActivationBehavior
.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

APIDirectioniOS
dismissSearch
Dismiss only15+
.searchFocused($bool)
Activate or dismiss18+

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:

PlatformDefault Behavior
iOSSearch bar in navigation bar. Scrolls out of view by default; pull down to reveal.
iPadOSSame as iOS in compact; may appear in toolbar in regular width.
macOSTrailing toolbar search field. Always visible.
watchOSDictation-first input. Search bar at top of list.
tvOSTab-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

ModifieriOSPurpose
.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

ValueiOSPurpose
isSearching
15+Is user actively searching
dismissSearch
15+Action to dismiss search

Types

TypeiOSPurpose
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+