Search​Box Search​Box Search​Box Search​Box Class

Definition

Represents a control that can be used to enter search query text. (Not recommended for Universal Windows Platform (UWP) apps. See AutoSuggestBox.)

public : class SearchBox : Control, ISearchBoxpublic class SearchBox : Control, ISearchBoxPublic Class SearchBox Inherits Control Implements ISearchBox// This API is not available in Javascript.
<SearchBox .../>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

Examples

Here's a basic XAML definition for a SearchBox, and an implementation of the QuerySubmitted handler. It calls Frame.Navigate to load a search query result page (not shown) that's named SearchResultsPage1. The this/Me reference in the handlers is the containing page instance, as is typical for on-page input event handling code. You can see similar code as part of Quickstart: Adding search to an app.

<SearchBox x:Name="mySearchBox" 
    FocusOnKeyboardInput="True"
    QuerySubmitted="mySearchBox_QuerySubmitted"
    Height="35"/>
private void mySearchBox_QuerySubmitted(SearchBox sender, SearchBoxQuerySubmittedEventArgs args)
{
    this.Frame.Navigate(typeof(SearchResultsPage1), args.QueryText);
}
Private Sub mySearchBox_QuerySubmitted(sender As SearchBox, args As SearchBoxQuerySubmittedEventArgs)
    Me.Frame.Navigate(GetType(SearchResultsPage1), args.QueryText)
End Sub

Remarks

Windows 10

Important

Although SearchBox is implemented in the Universal device family, it is not fully functional on mobile devices. Use AutoSuggestBox for your universal search experience. See SearchBox deprecated in favor of AutoSuggestBox.

Windows 8.x

To support keyboard interaction and make your app's search experience consistent with the Start screen, set the FocusOnKeyboardInput property to true. For more info, see Guidelines and checklist for search.

At a minimum each SearchBox control should always have a QuerySubmitted handler. This handler passes the user's query text to a search results page that the handler opens. Open this page by calling Frame.Navigate. For more info on how to write a basic QuerySubmitted handler and create a search results page as part of your app, see Enabling users to search for information in your .

In addition to the basic results and search experience, a SearchBox also supports search suggestions, programmatically setting the starting search text, and search history. The search suggestion feature is supported by API in the Windows.ApplicationModel.Search namespace. For example code that shows how to use these features, see SearchBox control sample.

Note

An app can't use both the search box (Windows.UI.Xaml.Controls.SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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'"

Constructors

SearchBox() SearchBox() SearchBox() SearchBox()

Initializes a new instance of the SearchBox class.

public : SearchBox()public SearchBox()Public Sub New()// This API is not available in Javascript.

Properties

ChooseSuggestionOnEnter ChooseSuggestionOnEnter ChooseSuggestionOnEnter ChooseSuggestionOnEnter

Gets or sets a value that determines whether the suggested search query is activated when the user presses Enter.

public : PlatForm::Boolean ChooseSuggestionOnEnter { get; set; }public bool ChooseSuggestionOnEnter { get; set; }Public ReadWrite Property ChooseSuggestionOnEnter As bool// This API is not available in Javascript.
<SearchBox ChooseSuggestionOnEnter="bool"/>
Value
PlatForm::Boolean bool bool bool

true if the suggested search query is activated when the user presses Enter; otherwise, false. The default is false.

ChooseSuggestionOnEnterProperty ChooseSuggestionOnEnterProperty ChooseSuggestionOnEnterProperty ChooseSuggestionOnEnterProperty

Identifies the ChooseSuggestionOnEnter dependency property.

public : static DependencyProperty ChooseSuggestionOnEnterProperty { get; }public static DependencyProperty ChooseSuggestionOnEnterProperty { get; }Public Static ReadOnly Property ChooseSuggestionOnEnterProperty As DependencyProperty// This API is not available in Javascript.

FocusOnKeyboardInput FocusOnKeyboardInput FocusOnKeyboardInput FocusOnKeyboardInput

Gets or sets a value that determines whether a user can search by typing anywhere in the app.

public : PlatForm::Boolean FocusOnKeyboardInput { get; set; }public bool FocusOnKeyboardInput { get; set; }Public ReadWrite Property FocusOnKeyboardInput As bool// This API is not available in Javascript.
<SearchBox FocusOnKeyboardInput="bool"/>
Value
PlatForm::Boolean bool bool bool

true if the user can search by typing anywhere in the app; otherwise, false. The default is false.

Remarks

Note

When FocusOnKeyboardInput is set to true, there’s an issue that sometimes creates duplicate characters in the SearchBox control when using the touch keyboard. You can work around the issue by following these steps:

  1. Disable FocusOnKeyboardInput after the SearchBox receives focus. To do this, register for the PrepareForFocusOnKeyboardInput event and use the event handler to set FocusOnKeyboardInput to false.
  2. When the SearchBox loses focus, set FocusOnKeyboardInput back to true. To do this, register for the LostFocus event and use the event handler to set FocusOnKeyboardInput back to true.

When FocusOnKeyboardInput is true, keyboard input on the current thread is intercepted and textual input is redirected to the SearchBox. Only textual input will cause the SearchBox to receive focus. Non-text keys, such as arrows or Tab, are not redirected to the SearchBox. WIN/CTRL/ALT key combinations (except for Ctrl-V for paste) are also not redirected.

To do more than just set focus in the SearchBox, such as make the control visible, handle the PrepareForFocusOnKeyboardInput event.

You should set FocusOnKeyboardInput to false if the user sets focus on some other editable text field.

To learn more about when you should let users type to search, see Guidelines and checklist for search.

See Also

FocusOnKeyboardInputProperty FocusOnKeyboardInputProperty FocusOnKeyboardInputProperty FocusOnKeyboardInputProperty

Identifies the FocusOnKeyboardInput dependency property.

public : static DependencyProperty FocusOnKeyboardInputProperty { get; }public static DependencyProperty FocusOnKeyboardInputProperty { get; }Public Static ReadOnly Property FocusOnKeyboardInputProperty As DependencyProperty// This API is not available in Javascript.

Remarks

Note

When FocusOnKeyboardInput is set to true, there’s an issue that sometimes causes users to see duplicate characters in the SearchBox control when using the touch keyboard. You can work around the issue by following these steps: 1. Register for the PrepareForFocusOnKeyboardInput event and use the event handler to set FocusOnKeyboardInput to false. 2. Register for the LostFocus event and use the event handler to set FocusOnKeyboardInput back to true.

PlaceholderText PlaceholderText PlaceholderText PlaceholderText

Gets or sets the text that is displayed in the control until the value is changed by a user action or some other operation.

public : PlatForm::String PlaceholderText { get; set; }public string PlaceholderText { get; set; }Public ReadWrite Property PlaceholderText As string// This API is not available in Javascript.
<SearchBox PlaceholderText="placeholderString"/>

Value
PlatForm::String string string string

The text that is displayed in the control when no value is entered. The default is an empty string (""). The maximum placeholder text length is 128 characters.

PlaceholderTextProperty PlaceholderTextProperty PlaceholderTextProperty PlaceholderTextProperty

Identifies the PlaceholderText dependency property.

public : static DependencyProperty PlaceholderTextProperty { get; }public static DependencyProperty PlaceholderTextProperty { get; }Public Static ReadOnly Property PlaceholderTextProperty As DependencyProperty// This API is not available in Javascript.

QueryText QueryText QueryText QueryText

Gets or sets the text contents of the search box.

public : PlatForm::String QueryText { get; set; }public string QueryText { get; set; }Public ReadWrite Property QueryText As string// This API is not available in Javascript.
<SearchBox QueryText="string"/>
Value
PlatForm::String string string string

A string containing the text contents of the search box. The default is an empty string (""). The maximum query text length is 2048 characters.

QueryTextProperty QueryTextProperty QueryTextProperty QueryTextProperty

Identifies the QueryText dependency property.

public : static DependencyProperty QueryTextProperty { get; }public static DependencyProperty QueryTextProperty { get; }Public Static ReadOnly Property QueryTextProperty As DependencyProperty// This API is not available in Javascript.
Value
DependencyProperty DependencyProperty DependencyProperty DependencyProperty

The identifier for the QueryText dependency property.

SearchHistoryContext SearchHistoryContext SearchHistoryContext SearchHistoryContext

Gets or sets a string that identifies the context of the search and is used to store the user's search history with the app.

public : PlatForm::String SearchHistoryContext { get; set; }public string SearchHistoryContext { get; set; }Public ReadWrite Property SearchHistoryContext As string// This API is not available in Javascript.
<SearchBox SearchHistoryContext="string"/>
Value
PlatForm::String string string string

A string that identifies the context of the search. The default is an empty string ("").

Remarks

The search history context string is used as a secondary key for storing search history. The primary key is the AppId. You can use the search history context string to store different search histories for different pages or search entry points in the app. If you don't set this property, Windows assumes that all searches in your app occur in the same context.

SearchHistoryContextProperty SearchHistoryContextProperty SearchHistoryContextProperty SearchHistoryContextProperty

Identifies the SearchHistoryContext dependency property.

public : static DependencyProperty SearchHistoryContextProperty { get; }public static DependencyProperty SearchHistoryContextProperty { get; }Public Static ReadOnly Property SearchHistoryContextProperty As DependencyProperty// This API is not available in Javascript.

SearchHistoryEnabled SearchHistoryEnabled SearchHistoryEnabled SearchHistoryEnabled

Gets or sets a value that determines whether search suggestions are made from the search history.

public : PlatForm::Boolean SearchHistoryEnabled { get; set; }public bool SearchHistoryEnabled { get; set; }Public ReadWrite Property SearchHistoryEnabled As bool// This API is not available in Javascript.
<SearchBox SearchHistoryEnabled="bool"/>
Value
PlatForm::Boolean bool bool bool

true if search suggestions are made from the search history; otherwise, false. The default is true.

SearchHistoryEnabledProperty SearchHistoryEnabledProperty SearchHistoryEnabledProperty SearchHistoryEnabledProperty

Identifies the SearchHistoryEnabled dependency property.

public : static DependencyProperty SearchHistoryEnabledProperty { get; }public static DependencyProperty SearchHistoryEnabledProperty { get; }Public Static ReadOnly Property SearchHistoryEnabledProperty As DependencyProperty// This API is not available in Javascript.

Methods

SetLocalContentSuggestionSettings(LocalContentSuggestionSettings) SetLocalContentSuggestionSettings(LocalContentSuggestionSettings) SetLocalContentSuggestionSettings(LocalContentSuggestionSettings) SetLocalContentSuggestionSettings(LocalContentSuggestionSettings)

Specifies whether suggestions based on local files are automatically displayed in the search box suggestions, and defines the criteria that Windows uses to locate and filter these suggestions.

public : void SetLocalContentSuggestionSettings(LocalContentSuggestionSettings settings)public void SetLocalContentSuggestionSettings(LocalContentSuggestionSettings settings)Public Function SetLocalContentSuggestionSettings(settings As LocalContentSuggestionSettings) As void// This API is not available in Javascript.
Parameters

Examples

Here, suggestions are restricted to one kind of file, music files, using an AQS string. Two of the most common AQS filters restrict based on file kind, like "kind:music" in the example; and based on file name extension, like "ext:.mp3". You can learn more about AQS in Advanced Query Syntax.

public MainPage()
{
    this.InitializeComponent();

    // Let Windows provide suggestions from local files.
    var settings = new Windows.ApplicationModel.Search.LocalContentSuggestionSettings();
    settings.Enabled = true;
    // Access to the music library requires that the Music Library capability
    // be declared in the app manifest .
    settings.Locations.Add(Windows.Storage.KnownFolders.MusicLibrary);
    settings.AqsFilter = "kind:Music";
    MySearchBox.SetLocalContentSuggestionSettings(settings);
}

Remarks

When local content suggestions are enabled, Windows provides search suggestions from the user's local files as the user enters query text. For example, a picture application can configure local content suggestions so that search suggestions come only from a particular kind of image file that is stored in the user's picture library.

To search a local library, the appropriate capability must be declared in the app manifest. For more info, see App capability declarations.

Events

PrepareForFocusOnKeyboardInput PrepareForFocusOnKeyboardInput PrepareForFocusOnKeyboardInput PrepareForFocusOnKeyboardInput

Occurs when the FocusOnKeyboardInput property is true and the app receives textual keyboard input.

public : event TypedEventHandler PrepareForFocusOnKeyboardInput<SearchBox,  RoutedEventArgs>public event TypedEventHandler PrepareForFocusOnKeyboardInput<SearchBox,  RoutedEventArgs>Public Event PrepareForFocusOnKeyboardInput<SearchBox,  RoutedEventArgs>// This API is not available in Javascript.
<SearchBox PrepareForFocusOnKeyboardInput="eventhandler"/>

Remarks

This event occurs only if the FocusOnKeyboardInput property is true. If you wan to provide "type-to-search" behavior in your app, you should handle this event and synchronously ensure the SearchBox control is visible before the event call completes. After this event occurs, the control sets focus to itself.

When FocusOnKeyboardInput is true, keyboard input on the current thread is intercepted and textual input is redirected to the SearchBox. Only textual input will cause the SearchBox to receive focus. Non-text keys, such as arrows or Tab, are not redirected to the SearchBox. WIN/CTRL/ALT key combinations (except for Ctrl-V for paste) are also not redirected.

See Also

QueryChanged QueryChanged QueryChanged QueryChanged

Occurs when the query text changes.

public : event TypedEventHandler QueryChanged<SearchBox,  SearchBoxQueryChangedEventArgs>public event TypedEventHandler QueryChanged<SearchBox,  SearchBoxQueryChangedEventArgs>Public Event QueryChanged<SearchBox,  SearchBoxQueryChangedEventArgs>// This API is not available in Javascript.
<SearchBox QueryChanged="eventhandler"/>
See Also

QuerySubmitted QuerySubmitted QuerySubmitted QuerySubmitted

Occurs when the user submits a search query.

public : event TypedEventHandler QuerySubmitted<SearchBox,  SearchBoxQuerySubmittedEventArgs>public event TypedEventHandler QuerySubmitted<SearchBox,  SearchBoxQuerySubmittedEventArgs>Public Event QuerySubmitted<SearchBox,  SearchBoxQuerySubmittedEventArgs>// This API is not available in Javascript.
<SearchBox QuerySubmitted="eventhandler"/>

Examples

Here's a basic XAML definition for a SearchBox, and an implementation of the QuerySubmitted handler. It calls Frame.Navigate to load a search query result page (not shown) that's named SearchResultsPage1. The this/Me reference in the handlers is the containing page instance, as is typical for on-page input event handling code. You can see similar code as part of Quickstart: Adding search to an app and Enabling users to search for information in your .

<SearchBox x:Name="mySearchBox" 
    FocusOnKeyboardInput="True"
    QuerySubmitted="mySearchBox_QuerySubmitted"
    Height="35"  />
private void mySearchBox_QuerySubmitted(SearchBox sender, SearchBoxQuerySubmittedEventArgs args)
{
    this.Frame.Navigate(typeof(SearchResultsPage1), args.QueryText);
}
Private Sub mySearchBox_QuerySubmitted(sender As SearchBox, args As SearchBoxQuerySubmittedEventArgs)
    Me.Frame.Navigate(GetType(SearchResultsPage1), args.QueryText)
End Sub

Remarks

Handle this event so that you can get the QueryText value from SearchBoxQuerySubmittedEventArgs, and pass it on as navigation data when you load a search results page to display to the user.

For a complete example of how to handle QuerySubmitted as part of a complete example that also does search suggestions, see SearchBox control sample.

The handler signature for QuerySubmitted uses TypedEventHandler and enforces that the sender parameter be a SearchBox instance, not just Object.

See Also

ResultSuggestionChosen ResultSuggestionChosen ResultSuggestionChosen ResultSuggestionChosen

Occurs when the user picks a suggested search result.

public : event TypedEventHandler ResultSuggestionChosen<SearchBox,  SearchBoxResultSuggestionChosenEventArgs>public event TypedEventHandler ResultSuggestionChosen<SearchBox,  SearchBoxResultSuggestionChosenEventArgs>Public Event ResultSuggestionChosen<SearchBox,  SearchBoxResultSuggestionChosenEventArgs>// This API is not available in Javascript.
<SearchBox ResultSuggestionChosen="eventhandler"/>

SuggestionsRequested SuggestionsRequested SuggestionsRequested SuggestionsRequested

Occurs when the user's query text changes and the app needs to provide new suggestions to display in the search pane.

public : event TypedEventHandler SuggestionsRequested<SearchBox,  SearchBoxSuggestionsRequestedEventArgs>public event TypedEventHandler SuggestionsRequested<SearchBox,  SearchBoxSuggestionsRequestedEventArgs>Public Event SuggestionsRequested<SearchBox,  SearchBoxSuggestionsRequestedEventArgs>// This API is not available in Javascript.
<SearchBox SuggestionsRequested="eventhandler"/>

Remarks

You can get suggestions from several sources:

  • You can define them yourself. For example, you could create a list of car manufacturers.
  • You can get them from Windows if your app searches local files.
  • You can get them from a web service or server.

For user experience guidelines for displaying suggestions, see Guidelines and checklist for search.

You can use LocalContentSuggestionSettings to add suggestions, based on local files from Windows, in only a few lines of code. Alternatively, you can register for the search box control's SuggestionsRequested event and build your own list of suggestions that is made up of suggestions you retrieved from another source (like a locally-defined list or a web service).

For code examples that show how to add search suggestions, download the SearchBox control sample. The sample demonstrates how to add search suggestions by using all three possible sources, and how to add suggestions for East Asian languages by using alternate forms of the query text generated by an Input Method Editor (IME). (We recommend using query text alternatives if your app will be used by Japanese or Chinese users.)

Types of search suggestions

There are two types of suggestions your app can display: suggestions that help users refine a query (query suggestions), and suggestions that are actual results of a query (result suggestions). You may choose to display either or both types of suggestions.

If you provide query suggestions and the user selects one, your app should respond by displaying results for the selected, refined query in your app's search results page.

If you provide result suggestions, you must also register a ResultSuggestionChosen event handler so that you can respond when the user selects one of your result suggestions and you can display the result to the user.

Displaying app-provided suggestions

After you obtain suggestions, you display them by adding them to the SearchSuggestionsRequest.@Windows.ApplicationModel.Search.SearchSuggestionCollection?text=SearchSuggestionCollection.

If you choose to display both query suggestions and result suggestions, you should group the suggestions by suggestion type (query or result) and separate the groups using AppendSearchSeparator. Each separator takes the place of a suggestion and must be followed by at least one suggestion, decreasing the number of suggestions that you can display.

The maximum length of all of the textual fields in a suggestion (such as text, detail text, and image alt text) is 512 characters.

To learn more about using suggestions to create a good search experience for your users in Guidelines and checklist for search.

Handling the SuggestionsRequested event asynchronously

If you want to respond to the SuggestionsRequested event asynchronously, you must obtain a SearchSuggestionsRequestDeferral object before you edit the suggestion list. Here's an example from Quickstart: Adding search to an app that shows how:

        public async static void SearchBox_SuggestionsRequested(
            SearchBox sender, 
            SearchBoxSuggestionsRequestedEventArgs args)
        {

            // This object lets us edit the SearchSuggestionCollection asynchronously. 
            var deferral = args.Request.GetDeferral();

            try { 

                // Retrieve the system-supplied suggestions.
                var suggestions = args.Request.SearchSuggestionCollection;

                var groups = await SampleDataSource.GetGroupsAsync();
                foreach (var group in groups)
                {
                    var matchingItems = group.Items.Where(
                        item => item.Title.StartsWith(
                            args.QueryText, StringComparison.CurrentCultureIgnoreCase));

                    foreach (var item in matchingItems)
                    {
                        suggestions.AppendQuerySuggestion(item.Title);
                    }
                }

                foreach (string alternative in args.LinguisticDetails.QueryTextAlternatives)
                {
                    if (alternative.StartsWith(
                        args.QueryText, StringComparison.CurrentCultureIgnoreCase))
                    {
                        suggestions.AppendQuerySuggestion(alternative); 
                    }
                }
            }
            finally {
                deferral.Complete();
            }

        }
See Also

See Also