Class

UISearchController

A UISearchController object manages the display of search results based on interactions with a search bar. You use a search controller in tandem with your existing view controllers. When you have a view controller with searchable content, incorporate the search bar of a UISearchController object into your view controller’s interface. When the user interacts with that search bar, the search controller automatically displays a new view controller with the search results that you specify.

Overview

A search controller works with two custom view controllers that you provide. The first view controller displays your searchable content and the second displays your search results. The first view controller is part of your app’s main interface and you display it in whatever way is appropriate for your app. You pass the second view controller to the init(searchResultsController:) method when you initialize your search controller, and the search controller displays that view controller at appropriate times.

Each search controller provides a UISearchBar object that you must incorporate into the user interface of your initial view controller. Add this object to the view containing your searchable contents. When the user taps the search bar to enter a search term, the search controller automatically displays your search results view controller and notifies your app that the search process has begun.

When the user interacts with the search bar, the search controller notifies the object in its searchResultsUpdater property. You provide the search results updater object, which must conform to the UISearchResultsUpdating protocol. You use the methods of that protocol to search your content and deliver the results to your search results view controller. Typically, the view controller with your searchable content also acts as the search results updater object, but you can use another object if you prefer.

To customize the presentation or dismissal of the search results controller, assign an object to the search controller’s delegate property. Delegate objects must conform to the UISearchControllerDelegate protocol. You use the methods of that protocol to be notified when the search controller itself is activated and when the search results controller is presented or dismissed.

Listing 1 is an iOS example that shows how to configure a search controller from the view controller displaying the searchable content. The searchable content is displayed in a table and the search bar is displayed as the table header. This code creates another custom view controller for displaying the search results and uses that object to initialize the search controller object. The current view controller stores a reference to the search controller and handles any updates when the search term changes. The view controller also acts as the presentation context for the search results, which is usually what you want.

Listing 1

Creating and configuring a search controller on iOS

// Create the search results controller and store a reference to it.
MySearchResultsController* resultsController = [[MySearchResultsController alloc] init];
self.searchController = [[UISearchController alloc] initWithSearchResultsController:resultsController];
 
// Use the current view controller to update the search results.
self.searchController.searchResultsUpdater = self;
 
// Install the search bar as the table header.
self.tableView.tableHeaderView = self.searchController.searchBar;
 
// It is usually good to set the presentation context.
self.definesPresentationContext = YES;

Listing 2 is an excerpt from UIKit Catalog (tvOS): Creating and Customizing UIKit Controls. The search results view controller is loaded from a storyboard. The results controller is also used to update the search results. Rather than adding the search bar to another controller’s content, the search controller is wrapped inside a UISearchContainerViewController object so that it can be displayed explicitly. In the example, the search container view controller is itself wrapped inside a UINavigationController object which is then returned from the function.

Listing 2

Creating and configuring a search controller on tvOS

func packagedSearchController() -> UIViewController {
    let storyboard = UIStoryboard(name: "ViewControllerSamples", bundle: nil)
    guard let searchResultsController = storyboard.instantiateViewController(withIdentifier: SearchResultsViewController.storyboardIdentifier) as? SearchResultsViewController else {
        fatalError("Unable to instatiate a SearchResultsViewController from the storyboard.")
    }
    
    let searchController = UISearchController(searchResultsController: searchResultsController)
    searchController.searchResultsUpdater = searchResultsController
    searchController.searchBar.placeholder = NSLocalizedString("Enter keyword (e.g. iceland)", comment: "")
    
    let searchContainer = UISearchContainerViewController(searchController: searchController)
    searchContainer.title = NSLocalizedString("Search", comment: "")
    
    let searchNavigationController = UINavigationController(rootViewController: searchContainer)
    return searchNavigationController
}

Symbols

Initializing a Search Controller

init(searchResultsController: UIViewController?)

Initializes and returns a search controller with the specified view controller for displaying the results.

Managing the Search Results

var searchBar: UISearchBar

The search bar to install in your interface.

var searchResultsUpdater: UISearchResultsUpdating?

The object responsible for updating the contents of the search results controller.

var searchResultsController: UIViewController?

The view controller that displays the results of the search.

var isActive: Bool

The presented state of the search interface.

Configuring the Search Interface

var obscuresBackgroundDuringPresentation: Bool

A Boolean indicating whether the underlying content is obscured during a search.

var dimsBackgroundDuringPresentation: Bool

A Boolean indicating whether the underlying content is dimmed during a search.

var hidesNavigationBarDuringPresentation: Bool

A Boolean indicating whether the navigation bar should be hidden when searching.

Accessing the Delegate

var delegate: UISearchControllerDelegate?

The search controller’s delegate.