WinJS.UI.SearchBox object

Article
01/26/2017

[SearchBox is no longer available for use as of Windows 10. Instead, use AutoSuggestBox. ]

Enables the user to perform search queries and select suggestions.

Syntax

<div 
    data-win-control="WinJS.UI.SearchBox">
</div>

var object = new WinJS.UI.SearchBox();

Members

The SearchBox object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The SearchBox object has these constructors.

Constructor	Description
SearchBox	Creates a new SearchBox.

Events

The SearchBox object has these events.

Event	Description
onquerychanged	Raised when the user or the app changes the queryText.
onquerysubmitted	Raised awhen the user clicks the search glyph or presses Enter.
onreceivingfocusonkeyboardinput	Raised when the app automatically redirects focus to the search box. This event can only be raised when the focusOnKeyboardInput property is set to true.
onresultsuggestionchosen	Raised when the user selects a suggested option for the search.
onsuggestionsrequested	Raised when the system requests search suggestions from this app.

Methods

The SearchBox object has these methods.

Method	Description
addEventListener	Registers an event handler for the specified event.
createResultSuggestionImage	Creates the image argument for appending result suggestions when handling the `suggestionsrequested` event.
dispatchEvent	Raises an event of the specified type and with additional properties.
dispose	Releases resources held by this SearchBox. Call this method when the SearchBox is no longer needed. After calling this method, the SearchBox becomes unusable.
removeEventListener	Removes an event handler that the addEventListener method registered.
setLocalContentSuggestionSettings	Specifies whether suggestions based on local files are automatically displayed in the search pane, and defines the criteria that Windows uses to locate and filter these suggestions.

Properties

The SearchBox object has these properties.

Property	Access type	Description
chooseSuggestionOnEnter	Read/write	Gets or sets whether the first suggestion is chosen when the user presses Enter.
disabled	Read/write	Gets or sets a value that specifies whether the SearchBox is disabled. If the control is disabled, it won't receive focus.
element	Read-only	Gets the DOM element that hosts the SearchBox.
focusOnKeyboardInput	Read/write	Gets or sets a value that specifies whether the search box automatically receives focus when the user types into the app window.
placeholderText	Read/write	Gets or sets the placeholder text for the SearchBox. This text is displayed if there is no other text in the input box.
queryText	Read/write	Gets or sets the query text for the SearchBox.
searchHistoryContext	Read/write	Gets or sets the search history context. This context is used a secondary key (the app ID is the primary key) for storing search history.
searchHistoryDisabled	Read/write	Gets or sets a value that specifies whether search history is disabled.

Remarks

For more info, see Guidelines for search.

Note An app can't use both the search box (Windows.UI.Xaml.Controls.SearchBox for Windows Store apps using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows apps using JavaScript) and the SearchPane. Using both the search box and the search pane in the same app causes the app to throw an exception with this message: "Cannot create instance of type 'Windows.UI.Xaml.Controls.SearchBox.'"

Requirements

Minimum WinJS version	WinJS 3.0
Namespace	WinJS.UI

Share via