iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UISearchController Class Reference

Options
Deployment Target:

On This Page
Language:

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.

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 initWithSearchResultsController: 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. For example, if you use a table view for your searchable contents, you can assign the search bar to the tableHeaderView property of that table view. 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.

Listing 1 shows how to configure a search controller from the view controller displaying the searchable content. This code creates another custom view controller for displaying the search results and uses that object to create the search controller object. The current view controller stores a reference to the search controller and handles 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 1Creating and configuring a search controller
  1. // Create the search results controller and store a reference to it.
  2. MySearchResultsController* resultsController = [[MySearchResultsController alloc] init];
  3. self.searchController = [[UISearchController alloc] initWithSearchResultsController:resultsController];
  4. // Use the current view controller to update the search results.
  5. self.searchController.searchResultsUpdater = self;
  6. // Install the search bar as the table header.
  7. self.tableView.tableHeaderView = self.searchController.searchBar;
  8. // It is usually good to set the presentation context.
  9. self.definesPresentationContext = YES;

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.

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

    Declaration

    Swift

    init(searchResultsController searchResultsController: UIViewController?)

    Objective-C

    - (instancetype)initWithSearchResultsController:(UIViewController *)searchResultsController

    Parameters

    searchResultsController

    The view controller that displays the search results. Specify nil if you want to display the search results in the same view controller that displays your searchable content.

    Return Value

    An initialized search controller.

    Discussion

    After creating the search controller, always assign an object to the searchResultsUpdater property. The search controller uses that object to update the search results.

    Availability

    Available in iOS 8.0 and later.

  • The search bar to install in your interface. (read-only)

    Declaration

    Swift

    var searchBar: UISearchBar { get }

    Objective-C

    @property(nonatomic, strong, readonly) UISearchBar *searchBar

    Discussion

    Before presenting your searchable content, install the search bar in this property somewhere into your view controller’s interface. The search bar becomes the starting point for searching your contents. Interactions with the search bar are handled automatically by the UISearchController object, which notifies the object in the searchResultsUpdater property whenever the search information changes.

    To use a custom subclass of UISearchBar, subclass UISearchController and implement this property to return your custom search bar.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    weak var searchResultsUpdater: UISearchResultsUpdating?

    Objective-C

    @property(nonatomic, weak) id< UISearchResultsUpdating > searchResultsUpdater

    Discussion

    Assign an object that adopts the UISearchResultsUpdating protocol. Use the methods of that protocol to search your content and deliver the results to your search results view controller. The object contained by the searchResultsUpdater property is often the view controller that is set during initialization.

    Availability

    Available in iOS 8.0 and later.

  • The view controller that displays the results of the search. (read-only)

    Declaration

    Swift

    var searchResultsController: UIViewController? { get }

    Objective-C

    @property(nonatomic, strong, readonly) UIViewController *searchResultsController

    Discussion

    When the user enters text in the search bar, the search controller displays this view controller immediately and without any animations. You are responsible for passing the search results to this view controller so that they can be displayed. You do this using the object in the searchResultsUpdater property.

    When the value of this property is nil, the search controller does not present a separate view controller for the search results. Instead, you should display the results using the original view controller containing the search bar and searchable contents.

    Availability

    Available in iOS 8.0 and later.

  • The presented state of the search interface.

    Declaration

    Swift

    var active: Bool

    Objective-C

    @property(nonatomic, assign, getter=isActive) BOOL active

    Discussion

    When the user taps in the search field of a managed search bar, the search controller automatically displays the search results controller. Usually, you get the value of this property to determine whether the search results are displayed. However, you can set this property to YEStrue to force the search interface to appear, even if the user has not taps in the search field.

    The default value of this property is NOfalse.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var obscuresBackgroundDuringPresentation: Bool

    Objective-C

    @property(nonatomic, assign) BOOL obscuresBackgroundDuringPresentation

    Discussion

    When the value of this property is YEStrue, the search controller obscures the view controller containing your searchable content as soon as the user interacts with the search bar. When this property is NOfalse, the search controller does not obscure the original view controller. This property controls only whether the original view controller is initially obscured. When the user enters text in the search bar, the search controller immediately displays the search results controller with the results.

    If you use the same view controller to display the searchable content and search results, it is recommended that you set this property to NOfalse. The default value of this property is YEStrue.

    Availability

    Available in iOS 9.1 and later.

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

    Declaration

    Swift

    var dimsBackgroundDuringPresentation: Bool

    Objective-C

    @property(nonatomic, assign) BOOL dimsBackgroundDuringPresentation

    Discussion

    Use the obscuresBackgroundDuringPresentation property instead.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var hidesNavigationBarDuringPresentation: Bool

    Objective-C

    @property(nonatomic, assign) BOOL hidesNavigationBarDuringPresentation

    Discussion

    The default value of this property is YEStrue.

    Availability

    Available in iOS 8.0 and later.

  • The search controller’s delegate.

    Declaration

    Swift

    weak var delegate: UISearchControllerDelegate?

    Objective-C

    @property(nonatomic, weak) id< UISearchControllerDelegate > delegate

    Discussion

    Use the delegate object to receive notifications when the search results controller is presented and dismissed. You might use these notifications to customize the search interface or perform related actions.

    Availability

    Available in iOS 8.0 and later.