# Titanium.UI.SearchBar

A specialized text field for entering search text.

Availability

0.8

9.2.0

Extends

Titanium.UI.View

# Overview

Android	iOS	Windows

Search bars are most commonly used for filtering the rows in a Titanium.UI.TableView and Titanium.UI.ListView. You can add a search bar to a table view via its Titanium.UI.TableView.search property. You can add a search bar to a list view via its searchView property.

A search bar can also be used on its own.

Use the Titanium.UI.createSearchBar method or Alloy <SearchBar> element to create a search bar.

# Android Notes

On Android, the search bar's [x] clear button is used as a cancel button if Titanium.UI.SearchBar.iconifiedByDefault is set true, causing it to collapse back into an icon. Otherwise, it will only clear the text and you'll receive a Titanium.UI.SearchBar.change event instead of a Titanium.UI.SearchBar.cancel event like iOS.

# Examples

# Simple Search Bar

var search = Titanium.UI.createSearchBar({
  barColor:'#000',
  showCancel:true,
  height:43,
  top:0,
});

# Alloy XML Markup

Previous example as an Alloy view.

<Alloy>
    <SearchBar id="search" barColor="#000" showCancel="true" height="43" top="0" />
</Alloy>

# Search Bar with TableView

var search = Ti.UI.createSearchBar({
    showCancel: true
});
var tableview = Ti.UI.createTableView({
    search: search
});

# Alloy XML Markup

Previous example as an Alloy view.

<Alloy>
    <TableView id="tableview">
        <SearchBar id="search" showCancel="true" />
    </TableView>
</Alloy>

# Properties

# autocapitalization

Availability

10.0.0

0.8

9.2.0

autocapitalization :Number

Determines how text is capitalized during typing.

This API can be assigned the following constants:

Default: Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE

# autocorrect

Availability

10.0.0

0.8

9.2.0

autocorrect :Boolean

Determines whether the text in the search bar is autocorrected during typing.

Default: false

# barColor

Availability

0.8

9.2.0

barColor :String | Titanium.UI.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.

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.

Default: System default bar color.

# cancelButtonTitle

Availability

5.4.0

9.2.0

cancelButtonTitle :String

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.

Default: System-localized 'Cancel'

# color

Availability

7.1.0

9.2.0

color :String | Titanium.UI.Color

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.

# fieldBackgroundDisabledImage

Availability

7.5.0

9.2.0

fieldBackgroundDisabledImage :String

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

Availability

7.5.0

9.2.0

fieldBackgroundImage :String

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 READONLY

Availability

9.1.0

9.2.0

focused :Boolean

Determines whether this SearchBar has focus.

Default: false

# hintText

Availability

0.8

9.2.0

hintText :String

Text to show when the search bar field is not focused.

Default: On iOS, System-localized 'Search'. On Android and Windows, no hint text.

# hintTextColor

Availability

7.1.0

9.2.0

hintTextColor :String | Titanium.UI.Color

Hint text color to display when the field is empty.

Sets the color of the hintText.

Default: The platform's default hint text color.

# hinttextid

Availability

0.8

9.2.0

hinttextid :String

Key identifying a string from the locale file to use for the hintText property.

Only one of hintText or hinttextid should be specified.

# iconified

Availability

0.8

9.2.0

iconified :Boolean

Collapses/expands the search view to/from a search icon.

See Android Documentation for more details.

Default: undefined

# iconifiedByDefault

Availability

0.8

9.2.0

iconifiedByDefault :Boolean

Set true show as a search icon that expands to a search view when tapped on.

See Android Documentation for more details.

Default: false

# keyboardAppearance

Availability

5.2.0

9.2.0

keyboardAppearance :Number

Determines the appearance of the keyboard to be displayed the field is focused.

This API can be assigned the following constants:

Default: Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT

# keyboardType

Availability

0.8

9.2.0

keyboardType :Number

Keyboard type constant to use when the field is focused.

This API can be assigned the following constants:

Default: Titanium.UI.KEYBOARD_TYPE_DEFAULT

# prompt

Availability

0.8

9.2.0

prompt :String

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.

Default: No prompt.

# promptid

Availability

0.8

9.2.0

promptid :String

Key identifying a string from the locale file to use for the prompt property.

On Android, this property is no longer supported as of Titanium 10.0.0.

# showBookmark

Availability

0.8

9.2.0

showBookmark :Boolean

Determines whether the bookmark button is displayed.

Default: false

# showCancel

Availability

0.8

9.2.0

showCancel :Boolean

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.

Default: false

# style

Availability

5.4.0

9.2.0

style :Number

Determines the style of the search bar.

This API can be assigned the following constants:

Default: Titanium.UI.iOS.SEARCH_BAR_STYLE_PROMINENT

# tokens

Availability

9.1.0

9.2.0

tokens :Array<String>

The token of a search text field

# value

Availability

0.8

9.2.0

value :String

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

Availability

0.8

9.2.0

blur() → void

Causes the search bar to lose focus.

Returns

Type: void

# focus

Availability

0.8

9.2.0

focus() → void

Causes the search bar to gain focus.

Returns

Type: void

# insertTokenAtIndex

Availability

9.1.0

9.2.0

insertTokenAtIndex(token, index) → void

Inserts a new search token at the specified index.

Parameters

Name	Type	Description
`token`	SearchBarToken	The token to insert
`index`	Number	The index to insert the token at.

Returns

Type: void

# removeTokenAtIndex

Availability

9.1.0

9.2.0

removeTokenAtIndex(index) → void

Removes an existing token at the specified index.

Parameters

Name	Type	Description
`index`	Number	The index to remove the token at.

Returns

Type: void

# setShowCancel

Availability

0.8

9.2.0

setShowCancel(showCancel[, options]) → void

Shows or hides the cancel button.

Sets the value of the showCancel property.

On iOS, this method can be used to specify animation properties when changing the state of the cancel button.

searchBar.setShowCancel(true, { animated: true });

Parameters

Name	Type	Description
`showCancel`	Boolean	New value for showCancel.
`options`	AnimatedOptions	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 }`

Returns

Type: void

# Events

# focus

Availability

0.9

0.8

Fired when the search bar gains focus.

This event only fires when using the trackball to navigate.

Properties

Name	Type	Description
value	String	Value of the search bar.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# blur

Availability

0.8

9.2.0

Fired when the search bar loses focus.

Properties

Name	Type	Description
value	String	Value of the search bar.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# bookmark

Availability

0.8

Fired when the bookmark button is pressed.

Properties

Name	Type	Description
value	String	Value of the search bar.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# cancel

Availability

0.8

9.2.0

Fired when the cancel button is pressed.

Properties

Name	Type	Description
value	String	Value of the search bar.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# change

Availability

0.8

9.2.0

Fired when the value of the search bar changes.

Properties

Name	Type	Description
value	String	Value of the search bar.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.

# return

Availability

0.8

9.2.0

Fired when keyboard search button is pressed.

Properties

Name	Type	Description
value	String	Value of the search bar.
source	Object	Source object that fired the event.
type	String	Name of the event fired.
bubbles	Boolean	True if the event will try to bubble up if possible.
cancelBubble	Boolean	Set to true to stop the event from bubbling.