Class

UISearchBar

A text field–like control that supports text-based searches.

Overview

UISearchBar provides a text field for entering text, a search button, a bookmark button, and a cancel button. A search bar 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.

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.

Topics

Initializing the Search Bar

init()

Initializes the search bar to its default state.

Customizing the Search Bar Behavior

var delegate: UISearchBarDelegate?

The search bar’s delegate object.

protocol UISearchBarDelegate

A collection of optional methods that you implement to make a search bar control functional.

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.

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

enum UISearchBarIcon

Constants to identify the icons used in the search bar.

enum UISearchBarStyle

Specifies whether the search bar has a background.

enum UIBarStyle

Defines the stylistic appearance of different types of views.

struct UIOffset

Defines a structure that specifies an amount to offset a position.

See Also

Bars

class UIBarItem

An abstract superclass for items that can be added to a bar that appears at the bottom of the screen.

class UIBarButtonItem

A button specialized for placement on a toolbar or tab bar.

class UIBarButtonItemGroup

A set of bar button items on the shortcuts bar above the keyboard on iPad.

class UINavigationBar

A control that supports navigation of hierarchical content, most often used in navigation controllers.

class UIToolbar

A control that displays one or more buttons along the bottom edge of your interface.

class UITabBar

A control that displays one or more buttons in a tab bar for selecting between different subtasks, views, or modes in an app.

class UITabBarItem

An item in a tab bar.

protocol UIBarPositioning

A set of methods for defining the ways that bars can be positioned in iOS apps.

protocol UIBarPositioningDelegate

A set of methods that support the positioning of a bar that conforms to the UIBarPositioning protocol.