Class

UISearchBar

The UISearchBar class implements a text field control for text-based searches. The control provides a text field for entering text, a search button, a bookmark button, and a cancel button. The UISearchBar object does not actually perform any searches. You use a delegate, an object conforming to the UISearchBarDelegate protocol, to implement the actions when text is entered and buttons are clicked.

Overview

Customizing Appearance

You can customize the appearance of search bars one at a time, or you can use the appearance proxy ([UISearchBar appearance]) to customize the appearance of all search bars in an app.

In general, you should specify a value for the normal state to be used by other states which don’t have a custom value set. Similarly, when a property is dependent on the bar metrics (on iPhone, in landscape orientation bars have a different height from standard), you should specify a value for UIBarMetricsDefault.

For more information about appearance and behavior configuration, see Search Bars.

Symbols

Text Content

var placeholder: String?

The string that is displayed when there is no other text in the text field.

var prompt: String?

A single line of text displayed at the top of the search bar.

var text: String?

The current or starting search text.

Display Attributes

var barStyle: UIBarStyle

A bar style that specifies the search bar’s appearance.

var barTintColor: UIColor?

The tint color to apply to the search bar background.

var searchBarStyle: UISearchBarStyle

A search bar style that specifies the search bar’s appearance.

var tintColor: UIColor!

The tint color to apply to key elements in the search bar.

var isTranslucent: Bool

A Boolean value that indicates whether the search bar is translucent (true) or not (false).

Customizing the Keyboard Shortcut Items

var inputAssistantItem: UITextInputAssistantItem

The input assistant to use for configuring the keyboard’s shortcuts bar.

Button Configuration

var showsBookmarkButton: Bool

A Boolean value indicating whether the bookmark button is displayed.

var showsCancelButton: Bool

A Boolean value indicating whether the cancel button is displayed.

func setShowsCancelButton(Bool, animated: Bool)

Sets the display state of the cancel button optionally with animation.

var showsSearchResultsButton: Bool

A Boolean value indicating whether the search results button is displayed.

var isSearchResultsButtonSelected: Bool

A Boolean value indicating whether the search results button is selected.

Scope Buttons

var scopeButtonTitles: [String]?

An array of strings indicating the titles of the scope buttons.

var selectedScopeButtonIndex: Int

The index of the selected scope button.

var showsScopeBar: Bool

Specifies whether the scope bar is displayed.

Delegate

var delegate: UISearchBarDelegate?

The search bar’s delegate object.

Customizing Appearance

var backgroundImage: UIImage?

The background image for the search bar.

func backgroundImage(for: UIBarPosition, barMetrics: UIBarMetrics)

Returns the image used for the background in a given position and with given metrics.

func setBackgroundImage(UIImage?, for: UIBarPosition, barMetrics: UIBarMetrics)

Sets the image to use for the background in a given position and with given metrics.

func image(for: UISearchBarIcon, state: UIControlState)

Returns the image for a given search bar icon type and control state.

func setImage(UIImage?, for: UISearchBarIcon, state: UIControlState)

Sets the image for a given search bar icon type and control state.

func positionAdjustment(for: UISearchBarIcon)

Returns the position adjustment for a given icon.

func setPositionAdjustment(UIOffset, for: UISearchBarIcon)

Returns the position adjustment for a given icon.

var inputAccessoryView: UIView?

A custom input accessory view for the keyboard of the search bar.

var scopeBarBackgroundImage: UIImage?

The background image for the scope bar.

func scopeBarButtonBackgroundImage(for: UIControlState)

Returns the background image for the scope bar button in a given state.

func setScopeBarButtonBackgroundImage(UIImage?, for: UIControlState)

Sets the background image for the scope bar button in a given state.

func scopeBarButtonDividerImage(forLeftSegmentState: UIControlState, rightSegmentState: UIControlState)

Returns the divider image to use for a given combination of left and right segment states.

func setScopeBarButtonDividerImage(UIImage?, forLeftSegmentState: UIControlState, rightSegmentState: UIControlState)

Sets the divider image to use for a given combination of left and right segment states.

func scopeBarButtonTitleTextAttributes(for: UIControlState)

Returns the text attributes for the search bar’s button’s title string for a given state.

func setScopeBarButtonTitleTextAttributes([String : Any]?, for: UIControlState)

Sets the text attributes for the search bar’ button’s title string for a given state.

func searchFieldBackgroundImage(for: UIControlState)

Returns the search text field image for a given state.

func setSearchFieldBackgroundImage(UIImage?, for: UIControlState)

Sets the search text field image for a given state.

var searchFieldBackgroundPositionAdjustment: UIOffset

The offset of the search text field background in the search bar.

var searchTextPositionAdjustment: UIOffset

The offset of the text within the search text field background.

Constants

UISearchBarIcon

Constants to identify the icons used in the search bar.

UISearchBarStyle

Specifies whether the search bar has a background.