# Titanium.UI.SearchBar

A specialized text field for entering search text.

Availability
0.8
0.8
9.2.0
4.1.0

# Overview

Android iOS Windows
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

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.

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
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
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.1.0
9.2.0
focused :Boolean

Determines whether this SearchBar has focus.

Default: false


# hintText

Availability
0.8
0.8
9.2.0
4.1.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
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
0.8
9.2.0
4.1.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
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
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.

Default: Titanium.UI.KEYBOARD_APPEARANCE_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
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.

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
0.8
9.2.0
4.1.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
0.8
9.2.0
blur() void

Causes the search bar to lose focus.

Returns

Type
void

# focus

Availability
0.8
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
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.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# blur

Availability
0.8
0.8
9.2.0

Fired when the search bar loses focus.

Properties

Name Type Description
value String

Value of the search bar.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# bookmark

Availability
0.8

Fired when the bookmark button is pressed.

Properties

Name Type Description
value String

Value of the search bar.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# cancel

Availability
0.8
0.8
9.2.0

Fired when the cancel button is pressed.

Properties

Name Type Description
value String

Value of the search bar.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# change

Availability
0.8
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.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# return

Availability
0.8
0.8
9.2.0

Fired when keyboard search button is pressed.

Properties

Name Type Description
value String

Value of the search bar.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.