iOS Developer Library

Developer

UIKit Framework Reference UISearchBar Class Reference

Options
Deployment Target:

On This Page
Language:

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. More...

Inheritance


Import Statement


import UIKit @import UIKit;

Availability


Available in iOS 2.0 and later.
  • The string that is displayed when there is no other text in the text field.

    Declaration

    Swift

    var placeholder: String?

    Objective-C

    @property(nonatomic, copy) NSString *placeholder

    Discussion

    The default value is nil.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • prompt prompt Property

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

    Declaration

    Swift

    var prompt: String?

    Objective-C

    @property(nonatomic, copy) NSString *prompt

    Discussion

    The default value is nil.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • text text Property

    The current or starting search text.

    Declaration

    Swift

    var text: String!

    Objective-C

    @property(nonatomic, copy) NSString *text

    Discussion

    The default value is nil.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • barStyle barStyle Property

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

    Declaration

    Swift

    var barStyle: UIBarStyle

    Objective-C

    @property(nonatomic) UIBarStyle barStyle

    Discussion

    This property can be used together with searchBarStyle.

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The tint color to apply to the search bar background.

    Declaration

    Swift

    var barTintColor: UIColor?

    Objective-C

    @property(nonatomic, retain) UIColor *barTintColor

    Discussion

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var searchBarStyle: UISearchBarStyle

    Objective-C

    @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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • tintColor tintColor Property

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

    Declaration

    Swift

    var tintColor: UIColor?

    Objective-C

    @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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value that indicates whether the search bar is translucent (YEStrue) or not (NOfalse).

    Declaration

    Swift

    var translucent: Bool

    Objective-C

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

    Discussion

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

    If you set this property to YEStrue 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 NOfalse 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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • autocapitalizationType autocapitalizationType Available in iOS 2.0 through iOS 7.1 Property

    The auto-capitalization style for the text object.

    Declaration

    Objective-C

    @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.

    Import Statement

    Availability

    Available in iOS 2.0 through iOS 7.1.

  • autocorrectionType autocorrectionType Available in iOS 2.0 through iOS 7.1 Property

    The auto-correction style for the text object.

    Declaration

    Objective-C

    @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.

    Import Statement

    Availability

    Available in iOS 2.0 through iOS 7.1.

  • keyboardType keyboardType Available in iOS 2.0 through iOS 7.1 Property

    The keyboard style associated with the text object.

    Declaration

    Objective-C

    @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.

    Import Statement

    Availability

    Available in iOS 2.0 through iOS 7.1.

  • spellCheckingType spellCheckingType Available in iOS 5.0 through iOS 7.1 Property

    The spell-checking type.

    Declaration

    Objective-C

    @property(nonatomic) UITextSpellCheckingType spellCheckingType

    Discussion

    The default value is UITextSpellCheckingTypeDefault.

    Import Statement

    Availability

    Available in iOS 5.0 through iOS 7.1.

  • A Boolean value indicating whether the bookmark button is displayed.

    Declaration

    Swift

    var showsBookmarkButton: Bool

    Objective-C

    @property(nonatomic) BOOL showsBookmarkButton

    Discussion

    The default value is NOfalse.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether the cancel button is displayed.

    Declaration

    Swift

    var showsCancelButton: Bool

    Objective-C

    @property(nonatomic) BOOL showsCancelButton

    Discussion

    The default value is NOfalse.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func setShowsCancelButton(_ showsCancelButton: Bool, animated animated: Bool)

    Objective-C

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

    Parameters

    showsCancelButton

    YEStrue to display the cancel button, otherwise NOfalse.

    animated

    YEStrue to use animation to change the display state of the cancel button, otherwise NOfalse.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var showsSearchResultsButton: Bool

    Objective-C

    @property(nonatomic) BOOL showsSearchResultsButton

    Discussion

    The default value is NOfalse.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    var searchResultsButtonSelected: Bool

    Objective-C

    @property(nonatomic, getter=isSearchResultsButtonSelected) BOOL searchResultsButtonSelected

    Discussion

    The default value is NOfalse.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    var scopeButtonTitles: [AnyObject]?

    Objective-C

    @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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • The index of the selected scope button.

    Declaration

    Swift

    var selectedScopeButtonIndex: Int

    Objective-C

    @property(nonatomic) NSInteger selectedScopeButtonIndex

    Discussion

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Specifies whether the scope bar is displayed.

    Declaration

    Swift

    var showsScopeBar: Bool

    Objective-C

    @property(nonatomic) BOOL showsScopeBar

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • delegate delegate Property

    The search bar’s delegate object.

    Declaration

    Swift

    unowned(unsafe) var delegate: UISearchBarDelegate?

    Objective-C

    @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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Constants to identify the icons used in the search bar.

    Declaration

    Swift

    enum UISearchBarIcon : Int { case Search case Clear case Bookmark case ResultsList }

    Objective-C

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

    Constants

    • Search

      UISearchBarIconSearch

      Identifies the search icon.

      By default, the corresponding icon is a magnifying glass.

      Available in iOS 5.0 and later.

    • Clear

      UISearchBarIconClear

      Identifies the clear action icon.

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

      Available in iOS 5.0 and later.

    • Bookmark

      UISearchBarIconBookmark

      Identifies the bookmarks icon.

      By default, the corresponding icon is an open book.

      Available in iOS 5.0 and later.

    • ResultsList

      UISearchBarIconResultsList

      Identifies the results list icon.

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

      Available in iOS 5.0 and later.

    Import Statement

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Specifies whether the search bar has a background.

    Declaration

    Swift

    enum UISearchBarStyle : UInt { case Default case Prominent case Minimal }

    Objective-C

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

    Constants

    • Default

      UISearchBarStyleDefault

      The search bar has the default style.

      Defaults to UISearchBarStyleProminent.

      Available in iOS 7.0 and later.

    • Prominent

      UISearchBarStyleProminent

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

      Available in iOS 7.0 and later.

    • Minimal

      UISearchBarStyleMinimal

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

      Available in iOS 7.0 and later.

    Import Statement

    import UIKit

    Availability

    Available in iOS 7.0 and later.