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
<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

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'"

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

Constructors

SearchBox() SearchBox() SearchBox()

Initializes a new instance of the SearchBox class.

public SearchBox()public SearchBox()Public Sub New()
Attributes

Properties

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
<SearchBox ChooseSuggestionOnEnter="bool"/>
Value
bool bool bool

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

Attributes

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
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the ChooseSuggestionOnEnter dependency property.

Attributes

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
<SearchBox FocusOnKeyboardInput="bool"/>
Value
bool bool bool

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

Attributes

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

Identifies the FocusOnKeyboardInput dependency property.

public static DependencyProperty FocusOnKeyboardInputProperty { get; }public static DependencyProperty FocusOnKeyboardInputProperty { get; }Public Static ReadOnly Property FocusOnKeyboardInputProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the FocusOnKeyboardInput dependency property.

Attributes

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

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
<SearchBox PlaceholderText="placeholderString"/>

Value
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.

Attributes

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
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the PlaceholderText dependency property.

Attributes

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
<SearchBox QueryText="string"/>
Value
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.

Attributes

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
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the QueryText dependency property.

Attributes

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
<SearchBox SearchHistoryContext="string"/>
Value
string string string

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

Attributes

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

Identifies the SearchHistoryContext dependency property.

public static DependencyProperty SearchHistoryContextProperty { get; }public static DependencyProperty SearchHistoryContextProperty { get; }Public Static ReadOnly Property SearchHistoryContextProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the SearchHistoryContext dependency property.

Attributes

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
<SearchBox SearchHistoryEnabled="bool"/>
Value
bool bool bool

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

Attributes

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
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the SearchHistoryEnabled dependency property.

Attributes

Methods

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
Parameters
settings
LocalContentSuggestionSettings LocalContentSuggestionSettings LocalContentSuggestionSettings

The new settings for local content suggestions.

Attributes

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.

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);
}

Events

PrepareForFocusOnKeyboardInput PrepareForFocusOnKeyboardInput PrepareForFocusOnKeyboardInput

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

public event TypedEventHandler PrepareForFocusOnKeyboardInputpublic event TypedEventHandler PrepareForFocusOnKeyboardInputPublic Event PrepareForFocusOnKeyboardInput
<SearchBox PrepareForFocusOnKeyboardInput="eventhandler"/>
Attributes

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.

QueryChanged QueryChanged QueryChanged

Occurs when the query text changes.

public event TypedEventHandler QueryChangedpublic event TypedEventHandler QueryChangedPublic Event QueryChanged
<SearchBox QueryChanged="eventhandler"/>
Attributes

QuerySubmitted QuerySubmitted QuerySubmitted

Occurs when the user submits a search query.

public event TypedEventHandler QuerySubmittedpublic event TypedEventHandler QuerySubmittedPublic Event QuerySubmitted
<SearchBox QuerySubmitted="eventhandler"/>

Attributes

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.

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
See Also

ResultSuggestionChosen ResultSuggestionChosen ResultSuggestionChosen

Occurs when the user picks a suggested search result.

public event TypedEventHandler ResultSuggestionChosenpublic event TypedEventHandler ResultSuggestionChosenPublic Event ResultSuggestionChosen
<SearchBox ResultSuggestionChosen="eventhandler"/>
Attributes

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 SuggestionsRequestedpublic event TypedEventHandler SuggestionsRequestedPublic Event SuggestionsRequested
<SearchBox SuggestionsRequested="eventhandler"/>
Attributes

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