UISearchBar Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UISearchBar.h
Related sample code

Overview

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.

Customizing Appearance

In iOS v5.0 and later, you can customize the appearance of search bars using the methods listed in “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”.

Tasks

Text Content

Display Attributes

Text Input Properties

Button Configuration

Scope Buttons

Delegate

Customizing Appearance

Properties

autocapitalizationType

The auto-capitalization style for the text object.

@property(nonatomic) UITextAutocapitalizationType autocapitalizationType
Discussion

This property determines at what times the Shift key is automatically pressed, thereby making the typed character a capital letter. The default value is UITextAutocapitalizationTypeNone.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

autocorrectionType

The auto-correction style for the text object.

@property(nonatomic) UITextAutocorrectionType autocorrectionType
Discussion

This property determines whether auto-correction is enabled or disabled during typing. With auto-correction enabled, the text object tracks unknown words and suggests a replacement candidate to the user, replacing the typed text automatically unless the user explicitly overrides the action.

The default value is UITextAutocorrectionTypeDefault, which for most input methods results in auto-correction being enabled.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

backgroundImage

The background image for the search bar.

@property(nonatomic, retain) UIImage *backgroundImage
Discussion

Images that are 1 point wide or stretchable images are stretched, otherwise the image is tiled.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

barStyle

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

@property(nonatomic) UIBarStyle barStyle
Discussion

This property can be used together with searchBarStyle.

See UIBarStyle for possible values. The default value is UIBarStyleDefault.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

barTintColor

The tint color to apply to the search bar background.

@property(nonatomic, retain) UIColor *barTintColor
Discussion

This color is made translucent by default unless you set the translucent property to NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
UISearchBar.h

delegate

The search bar’s delegate object.

@property(nonatomic, assign) id<UISearchBarDelegate> delegate
Discussion

The delegate should conform to the UISearchBarDelegate protocol. Set this property to further modify the behavior. The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

inputAccessoryView

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

@property(nonatomic, readwrite, retain) UIView *inputAccessoryView
Discussion

The default value is nil. When non-nil, this property represents a custom input accessory view that will be placed onto the search bar’s system-supplied keyboard.

Availability
  • Available in iOS 6.0 and later.
Declared In
UISearchBar.h

keyboardType

The keyboard style associated with the text object.

@property(nonatomic) UIKeyboardType keyboardType
Discussion

Text objects can be targeted for specific types of input, such as plain text, email, numeric entry, and so on. The keyboard style identifies what keys are available on the keyboard and which ones appear by default.

The default value is UIKeyboardTypeDefault.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

placeholder

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

@property(nonatomic, copy) NSString *placeholder
Discussion

The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

prompt

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

@property(nonatomic, copy) NSString *prompt
Discussion

The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

scopeBarBackgroundImage

The background image for the scope bar.

@property(nonatomic, retain) UIImage *scopeBarBackgroundImage
Discussion

Images that are 1 point wide or stretchable images are stretched, otherwise the image is tiled.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

scopeButtonTitles

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

@property(nonatomic, copy) NSArray *scopeButtonTitles
Discussion

The order of the strings in the array indicates the order that the corresponding buttons will be displayed, from left to right. The index in the array corresponds to the index used in selectedScopeButtonIndex.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchBar.h

searchBarStyle

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

@property(nonatomic) UISearchBarStyle searchBarStyle
Discussion

This property can be used together with barStyle. The style UISearchBarStyleMinimal provides no default background color or image but will display one if customized as such.

Custom background and search field images take precedence over this property.

See “UISearchBarStyle” for possible values. The default value is UISearchBarStyleDefault.

Availability
  • Available in iOS 7.0 and later.
Declared In
UISearchBar.h

searchFieldBackgroundPositionAdjustment

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

@property(nonatomic) UIOffset searchFieldBackgroundPositionAdjustment
Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

searchResultsButtonSelected

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

@property(nonatomic, getter=isSearchResultsButtonSelected) BOOL searchResultsButtonSelected
Discussion

The default value is NO.

Availability
  • Available in iOS 3.2 and later.
Declared In
UISearchBar.h

searchTextPositionAdjustment

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

@property(nonatomic) UIOffset searchTextPositionAdjustment
Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

selectedScopeButtonIndex

The index of the selected scope button.

@property(nonatomic) NSInteger selectedScopeButtonIndex
Discussion

The indexes of the scope buttons are determined by the indexes of the strings in scopeButtonTitles.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchBar.h

showsBookmarkButton

A Boolean value indicating whether the bookmark button is displayed.

@property(nonatomic) BOOL showsBookmarkButton
Discussion

The default value is NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

showsCancelButton

A Boolean value indicating whether the cancel button is displayed.

@property(nonatomic) BOOL showsCancelButton
Discussion

The default value is NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

showsScopeBar

Specifies whether the scope bar is displayed.

@property(nonatomic) BOOL showsScopeBar
Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchBar.h

showsSearchResultsButton

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

@property(nonatomic) BOOL showsSearchResultsButton
Discussion

The default value is NO.

Availability
  • Available in iOS 3.2 and later.
Declared In
UISearchBar.h

spellCheckingType

The spell-checking type.

@property(nonatomic) UITextSpellCheckingType spellCheckingType
Discussion

The default value is UITextSpellCheckingTypeDefault.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

text

The current or starting search text.

@property(nonatomic, copy) NSString *text
Discussion

The default value is nil.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

tintColor

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

@property(nonatomic, retain) UIColor *tintColor
Discussion

In iOS v7.0, all subclasses of UIView derive their behavior for tintColor from the base class. See the discussion of tintColor at the UIView level for more information.

Availability
  • Available in iOS 2.0 and later.
Declared In
UISearchBar.h

translucent

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

@property(nonatomic, assign, getter=isTranslucent) BOOL translucent
Discussion

The default value is YES. If the search bar has a custom background image, the default is YES if any pixel of the image has an alpha value of less than 1.0, and NO otherwise.

If you set this property to YES on a search bar with an opaque custom background image, the search bar will apply a system opacity less than 1.0 to the image.

If you set this property to NO on a search bar with a translucent custom background image, the search bar provides an opaque background for the image using black if the search bar has UIBarStyleBlack style, white if the search bar has UIBarStyleDefault, or the search bar’s barTintColor if a custom value is defined.

Availability
  • Available in iOS 3.0 and later.
Declared In
UISearchBar.h

Instance Methods

backgroundImageForBarPosition:barMetrics:

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

- (UIImage *)backgroundImageForBarPosition:(UIBarPosition)barPosition barMetrics:(UIBarMetrics)barMetrics
Parameters
barPosition

A bar position constant.

barMetrics

A bar metrics constant.

Return Value

The image used for the search bar background in the position specified by barPosition and with the metrics specified by barMetrics.

Discussion

The default value is nil.

Availability
  • Available in iOS 7.0 and later.
Declared In
UISearchBar.h

imageForSearchBarIcon:state:

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

- (UIImage *)imageForSearchBarIcon:(UISearchBarIcon)icon state:(UIControlState)state
Parameters
icon

An icon identifier constant.

state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

Return Value

The image used for the search bar icon identified by icon in the state identified by state.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

positionAdjustmentForSearchBarIcon:

Returns the position adjustment for a given icon.

- (UIOffset)positionAdjustmentForSearchBarIcon:(UISearchBarIcon)icon
Parameters
icon

An icon identifier constant.

Return Value

The position adjustment for the icon identified by icon.

Discussion

The offset is used to adjust the position of an icon within the search text field.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

scopeBarButtonBackgroundImageForState:

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

- (UIImage *)scopeBarButtonBackgroundImageForState:(UIControlState)state
Parameters
state

A control state.

Return Value

The background image for the scope bar button in state.

Discussion

If the background image is an image returned from stretchableImageWithLeftCapWidth:topCapHeight: (UIImage), the cap widths are calculated from that information, otherwise, the cap width is calculated by subtracting one from the image’s width then dividing by 2. The cap widths are used as the margins for text placement. To adjust the margin use the margin adjustment methods.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

scopeBarButtonDividerImageForLeftSegmentState:rightSegmentState:

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

- (UIImage *)scopeBarButtonDividerImageForLeftSegmentState:(UIControlState)leftState rightSegmentState:(UIControlState)rightState
Parameters
leftState

The state of the left segment for which to provide the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

rightState

The state of the right segment for which to provide the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

Return Value

The divider image to use for the combination of leftState and rightState.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

scopeBarButtonTitleTextAttributesForState:

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

- (NSDictionary *)scopeBarButtonTitleTextAttributesForState:(UIControlState)state
Parameters
state

A control state.

Return Value

The text attributes for the search bar’ button’s title string for state.

The attributes may specify the font, text color, text shadow color, and text shadow offset, using the keys found in NSString UIKit Additions Reference.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

searchFieldBackgroundImageForState:

Returns the search text field image for a given state.

- (UIImage *)searchFieldBackgroundImageForState:(UIControlState)state
Parameters
state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

Return Value

The search text field image to use for state.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

setBackgroundImage:forBarPosition:barMetrics:

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

- (void)setBackgroundImage:(UIImage *)backgroundImage forBarPosition:(UIBarPosition)barPosition barMetrics:(UIBarMetrics)barMetrics
Parameters
backgroundImage

The image to use for the search bar background in the position specified by barPosition and with the metrics specified by barMetrics.

barPosition

A bar position constant.

barMetrics

A bar metrics constant.

Availability
  • Available in iOS 7.0 and later.
Declared In
UISearchBar.h

setImage:forSearchBarIcon:state:

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

- (void)setImage:(UIImage *)iconImage forSearchBarIcon:(UISearchBarIcon)icon state:(UIControlState)state
Parameters
iconImage

The image to use for the search bar icon identified by icon in the state identified by state.

icon

An icon identifier constant.

state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

setPositionAdjustment:forSearchBarIcon:

Returns the position adjustment for a given icon.

- (void)setPositionAdjustment:(UIOffset)adjustment forSearchBarIcon:(UISearchBarIcon)icon
Parameters
adjustment

The offset to use for the icon identified by icon.

icon

An icon identifier constant.

Discussion

Use this method to adjust the position of an icon within the search text field.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

setScopeBarButtonBackgroundImage:forState:

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

- (void)setScopeBarButtonBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state
Parameters
backgroundImage

The background image for the scope bar button in state.

state

A control state.

Discussion

For more details, see scopeBarButtonBackgroundImageForState:.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

setScopeBarButtonDividerImage:forLeftSegmentState:rightSegmentState:

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

- (void)setScopeBarButtonDividerImage:(UIImage *)dividerImage forLeftSegmentState:(UIControlState)leftState rightSegmentState:(UIControlState)rightState
Parameters
dividerImage

The divider image to use for the combination of leftState and rightState.

leftState

The state of the left segment for which to set the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

rightState

The state of the right segment for which to set the divider image.

The state may be UIControlStateNormal or UIControlStateSelected.

Discussion

To customize the segmented control appearance you need to provide divider images to go between two unselected segments (leftSegmentState:UIControlStateNormal rightSegmentState:UIControlStateNormal), selected on the left and unselected on the right (leftSegmentState:UIControlStateSelected rightSegmentState:UIControlStateNormal), and unselected on the left and selected on the right (leftSegmentState:UIControlStateNormal rightSegmentState:UIControlStateSelected).

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

setScopeBarButtonTitleTextAttributes:forState:

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

- (void)setScopeBarButtonTitleTextAttributes:(NSDictionary *)attributes forState:(UIControlState)state
Parameters
attributes

A dictionary containing key-value pairs specifying the text attributes to use for state.

You may specify the font, text color, text shadow color, and text shadow offset, using the keys found in NSString UIKit Additions Reference.

state

A control state.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

setSearchFieldBackgroundImage:forState:

Sets the search text field image for a given state.

- (void)setSearchFieldBackgroundImage:(UIImage *)backgroundImage forState:(UIControlState)state
Parameters
backgroundImage

The search text field image image to use for state.

state

A control state.

Valid states are UIControlStateNormal and UIControlStateDisabled.

Availability
  • Available in iOS 5.0 and later.
Declared In
UISearchBar.h

setShowsCancelButton:animated:

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

- (void)setShowsCancelButton:(BOOL)showsCancelButton animated:(BOOL)animated
Parameters
showsCancelButton

YES to display the cancel button, otherwise NO.

animated

YES to use animation to change the display state of the cancel button, otherwise NO.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
UISearchBar.h

Constants

UISearchBarIcon

Constants to identify the icons used in the search bar.

typedef enum {
   UISearchBarIconSearch,
   UISearchBarIconClear,
   UISearchBarIconBookmark,
   UISearchBarIconResultsList,
} UISearchBarIcon;
Constants
UISearchBarIconSearch

Identifies the search icon.

By default, the corresponding icon is a magnifying glass.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.

UISearchBarIconClear

Identifies the clear action icon.

By default, the corresponding icon is a circle containing an X.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.

UISearchBarIconBookmark

Identifies the bookmarks icon.

By default, the corresponding icon is an open book.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.

UISearchBarIconResultsList

Identifies the results list icon.

By default, the corresponding icon is a list lozenge icon.

Available in iOS 5.0 and later.

Declared in UISearchBar.h.

UISearchBarStyle

Specifies whether the search bar has a background.

typedef NS_ENUM(NSUInteger,
   UISearchBarStyle) {
   UISearchBarStyleDefault,
   UISearchBarStyleProminent,
   UISearchBarStyleMinimal
};
Constants
UISearchBarStyleDefault

The search bar has the default style.

Defaults to UISearchBarStyleProminent.

Available in iOS 7.0 and later.

Declared in UISearchBar.h.

UISearchBarStyleProminent

The search bar has a translucent background, and the search field is opaque.

Available in iOS 7.0 and later.

Declared in UISearchBar.h.

UISearchBarStyleMinimal

The search bar has no background, and the search field is translucent.

Available in iOS 7.0 and later.

Declared in UISearchBar.h.