# Titanium.UI.SearchBar > A specialized text field for entering search text. - Source: https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.UI.SearchBar - Titanium SDK version: 12.6.3 - Kind: view - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.8 - Extends: Titanium.UI.View - Inheritance: Titanium.UI.View > Titanium.Proxy | Android | iOS | | ------- | --- | | ![Android](./searchbar_android.png) | ![iOS](./searchbar_ios.png) | Search bars are most commonly used for filtering the rows in a [TableView](https://titaniumsdk.com/docs/sdk/Titanium.UI.TableView.md) and [ListView](https://titaniumsdk.com/docs/sdk/Titanium.UI.ListView.md). You can add a search bar to a table view via its [search](https://titaniumsdk.com/docs/sdk/Titanium.UI.TableView.md#search) property. You can add a search bar to a list view via its [searchBar](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md) property. A search bar can also be used on its own. Use the [Titanium.UI.createSearchBar](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createSearchBar) method or Alloy **``** element to create a search bar. #### Android Notes On Android, the search bar's `[x]` clear button is used as a cancel button if [iconifiedByDefault](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#iconifiedByDefault) is set `true`, causing it to collapse back into an icon. Otherwise, it will only clear the text and you'll receive a [change](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#change) event instead of a [cancel](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#cancel) event like iOS. ## Example: Simple Search Bar ``` js var search = Titanium.UI.createSearchBar({ barColor:'#000', showCancel:true, height:43, top:0, }); ``` ## Example: Alloy XML Markup Previous example as an Alloy view. ``` xml ``` ## Example: Search Bar with TableView ``` js var search = Ti.UI.createSearchBar({ showCancel: true }); var tableview = Ti.UI.createTableView({ search: search }); ``` ## Example: Alloy XML Markup Previous example as an Alloy view. ``` xml ``` ## Properties ### autocapitalization - Type: Number - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 10.0.0, iPhone 0.8, iPad 0.8, macOS 9.2.0 - Default: `Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE` Determines how text is capitalized during typing. Accepts: `Titanium.UI.TEXT_AUTOCAPITALIZATION_ALL`, `Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE`, `Titanium.UI.TEXT_AUTOCAPITALIZATION_SENTENCES`, `Titanium.UI.TEXT_AUTOCAPITALIZATION_WORDS` ### autocorrect - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 10.0.0, iPhone 0.8, iPad 0.8, macOS 9.2.0 - Default: `false` Determines whether the text in the search bar is autocorrected during typing. ### barColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Default: `System default bar color.` Bar color of the search bar view, as a color name or hex triplet. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). On iOS and Android, `barColor` specifies the color of the "frame" around the search text field. On Windows, `barColor` specifies the color of the whole surrounding area of the search text field. ### cancelButtonTitle - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.4.0 - Default: `System-localized 'Cancel'` The title of the cancel button when the search bar field is focused. Use this property if you want to display a custom cancel title. ### color - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 7.1.0 Color of the text in this text field, as a color name or hex triplet. For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md). ### fieldBackgroundDisabledImage - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 Background image of the text field in disabled state, specified as a local file path or URL. If this property is not specified, the default white background is used. ### fieldBackgroundImage - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 7.5.0 Background image of the text field, specified as a local file path or URL. If this property is not specified, the default white background is used. ### focused - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 9.1.0 - Permission: read-only - Default: `false` Determines whether this SearchBar has focus. ### hintText - Type: String - Platforms: Android, iPhone, iPad, macOS - Default: `On iOS, System-localized 'Search'. On Android and Windows, no hint text.` Text to show when the search bar field is not focused. ### hintTextColor - Type: String | Titanium.UI.Color - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 7.1.0 - Default: `The platform's default hint text color.` Hint text color to display when the field is empty. Sets the color of the [Titanium.UI.SearchBar.hintText](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#hintText). ### hinttextid - Type: String - Platforms: Android, iPhone, iPad, macOS Key identifying a string from the locale file to use for the [hintText](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#hintText) property. Only one of `hintText` or `hinttextid` should be specified. ### iconColor - Type: String | Titanium.UI.Color - Platforms: Android - Since: Titanium SDK 12.0.0 Color of the search and close icon. Search icon will only work for `iconified:false`. ### iconified - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `undefined` Collapses/expands the search view to/from a search icon. See [Android Documentation](https://developer.android.com/reference/android/widget/SearchView.html#setIconified(boolean)) for more details. ### iconifiedByDefault - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `false` Set true show as a search icon that expands to a search view when tapped on. See [Android Documentation](https://developer.android.com/reference/android/widget/SearchView.html#setIconifiedByDefault(boolean)) for more details. ### keyboardAppearance - Type: Number - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.2.0 - Default: `Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT` Determines the appearance of the keyboard to be displayed the field is focused. Accepts: `Titanium.UI.KEYBOARD_APPEARANCE_DARK`, `Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT`, `Titanium.UI.KEYBOARD_APPEARANCE_LIGHT` ### keyboardType - Type: Number - Platforms: iPhone, iPad, macOS - Default: `Titanium.UI.KEYBOARD_TYPE_DEFAULT` Keyboard type constant to use when the field is focused. Accepts: `Titanium.UI.KEYBOARD_TYPE_ASCII`, `Titanium.UI.KEYBOARD_TYPE_DECIMAL_PAD`, `Titanium.UI.KEYBOARD_TYPE_DEFAULT`, `Titanium.UI.KEYBOARD_TYPE_EMAIL`, `Titanium.UI.KEYBOARD_TYPE_NAMEPHONE_PAD`, `Titanium.UI.KEYBOARD_TYPE_NUMBERS_PUNCTUATION`, `Titanium.UI.KEYBOARD_TYPE_NUMBER_PAD`, `Titanium.UI.KEYBOARD_TYPE_PHONE_PAD`, `Titanium.UI.KEYBOARD_TYPE_TWITTER`, `Titanium.UI.KEYBOARD_TYPE_URL`, `Titanium.UI.KEYBOARD_TYPE_WEBSEARCH` ### prompt - Type: String - Platforms: iPhone, iPad, macOS - Default: `No prompt.` Single line of text displayed at the top of the search bar. On Android, this property is no longer supported as of Titanium 10.0.0. ### promptid - Type: String - Platforms: iPhone, iPad, macOS Key identifying a string from the locale file to use for the [prompt](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#prompt) property. On Android, this property is no longer supported as of Titanium 10.0.0. ### showBookmark - Type: Boolean - Platforms: iPhone, iPad, macOS - Default: `false` Determines whether the bookmark button is displayed. ### showCancel - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `false` Determines whether the cancel button is displayed. On iOS, you can specify that showing and hiding the cancel button should be animated. The change is not animated by default. To enable animation, call [setShowCancel](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#setShowCancel). ### style - Type: Number - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 5.4.0 - Default: `Titanium.UI.iOS.SEARCH_BAR_STYLE_PROMINENT` Determines the style of the search bar. Accepts: `Titanium.UI.iOS.SEARCH_BAR_STYLE_MINIMAL`, `Titanium.UI.iOS.SEARCH_BAR_STYLE_PROMINENT` ### tokens - Type: Array - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 9.1.0 - Requires: iOS 13.0+ - Default: `` The token of a search text field ### value - Type: String - Platforms: Android, iPhone, iPad, macOS Value of the search bar. On Android and before Titanium 10.0.0, the value cannot be set until after the search bar is created. ## Methods ### blur - Platforms: Android, iPhone, iPad, macOS Causes the search bar to lose focus. ### focus - Platforms: Android, iPhone, iPad, macOS Causes the search bar to gain focus. ### insertTokenAtIndex - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 9.1.0 - Requires: iOS 13.0+ Inserts a new search token at the specified index. Parameters: - `token` (SearchBarToken): The token to insert - `index` (Number): The index to insert the token at. ### removeTokenAtIndex - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 9.1.0 - Requires: iOS 13.0+ Removes an existing token at the specified index. Parameters: - `index` (Number): The index to remove the token at. ### setShowCancel - Platforms: Android, iPhone, iPad, macOS Shows or hides the cancel button. Sets the value of the [showCancel](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#showCancel) property. On iOS, this method can be used to specify animation properties when changing the state of the cancel button. ``` js searchBar.setShowCancel(true, { animated: true }); ``` Parameters: - `showCancel` (Boolean): New value for [showCancel](https://titaniumsdk.com/docs/sdk/Titanium.UI.SearchBar.md#showCancel). - `options` (AnimatedOptions, optional): Dictionary of animation properties. Currently only a single boolean property, `animated` is supported. Only used on iOS. Note that the default here is equivalent to passing in `{ animated: false }` Default: `{ animated: false }`. ## Events ### blur - Platforms: Android, iPhone, iPad, macOS Fired when the search bar loses focus. Event properties: - `value` (String): Value of the search bar. ### bookmark - Platforms: iPhone, iPad Fired when the bookmark button is pressed. Event properties: - `value` (String): Value of the search bar. ### cancel - Platforms: Android, iPhone, iPad, macOS Fired when the cancel button is pressed. Event properties: - `value` (String): Value of the search bar. ### change - Platforms: Android, iPhone, iPad, macOS Fired when the value of the search bar changes. Event properties: - `value` (String): Value of the search bar. ### focus - Platforms: Android, iPhone, iPad Fired when the search bar gains focus. Event properties: - `value` (String): Value of the search bar. ### return - Platforms: Android, iPhone, iPad, macOS Fired when keyboard search button is pressed. Event properties: - `value` (String): Value of the search bar. ## Inherited members 99 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` - [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedColor`, `backgroundFocusedImage`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundSelectedColor`, `backgroundSelectedImage`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `children`, `clearMotionEffects`, `click`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepScreenOn`, `keypressed`, `layout`, `left`, `longclick`, `longpress`, `opacity`, `overrideCurrentAnimation`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `swipe`, `tintColor`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `twofingertap`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.