SearchBox SearchBox SearchBox Class

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

Windows 10 Although @Windows.UI.Xaml.Controls.SearchBox.#ctor 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.

Syntax

Declaration

public class SearchBoxpublic class SearchBoxPublic Class SearchBox
<SearchBox .../>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

Windows 10

Important

Although @Windows.UI.Xaml.Controls.SearchBox.#ctor 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 Navigate(Windows.UI.Xaml.Interop.TypeName,System.Object,Windows.UI.Xaml.Media.Animation.NavigationTransitionInfo). 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 (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 Navigate(Windows.UI.Xaml.Interop.TypeName,System.Object,Windows.UI.Xaml.Media.Animation.NavigationTransitionInfo) 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 summary

Initializes a new instance of the SearchBox class.

Properties summary

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

Identifies the ChooseSuggestionOnEnter dependency property.

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

Identifies the FocusOnKeyboardInput dependency property.

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

Identifies the PlaceholderText dependency property.

Gets or sets the text contents of the search box.

Identifies the QueryText dependency property.

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.

Identifies the SearchHistoryContext dependency property.

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

Identifies the SearchHistoryEnabled dependency property.

Methods summary

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.

Events summary

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

Occurs when the query text changes.

Occurs when the user submits a search query.

Occurs when the user picks a suggested search result.

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

Constructors

  • SearchBox()
    SearchBox()
    SearchBox()
    SearchBox()

    Initializes a new instance of the SearchBox class.

    public SearchBox()public SearchBox()Public Function SearchBox() As

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 bool ChooseSuggestionOnEnter { get; set; }public bool ChooseSuggestionOnEnter { get; set; }Public ReadWrite Property ChooseSuggestionOnEnter As bool
    <SearchBox ChooseSuggestionOnEnter="bool"/>
    

    Property Value

    • 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

    Property Value

  • FocusOnKeyboardInput
    FocusOnKeyboardInput
    FocusOnKeyboardInput
    FocusOnKeyboardInput

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

    public bool FocusOnKeyboardInput { get; set; }public bool FocusOnKeyboardInput { get; set; }Public ReadWrite Property FocusOnKeyboardInput As bool
    <SearchBox FocusOnKeyboardInput="bool"/>
    

    Property Value

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

  • 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

    Property Value

    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 string PlaceholderText { get; set; }public string PlaceholderText { get; set; }Public ReadWrite Property PlaceholderText As string
    <SearchBox PlaceholderText="placeholderString"/>
    
    

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

  • 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

    Property Value

  • QueryText
    QueryText
    QueryText
    QueryText

    Gets or sets the text contents of the search box.

    public string QueryText { get; set; }public string QueryText { get; set; }Public ReadWrite Property QueryText As string
    <SearchBox QueryText="string"/>
    

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

  • 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

    Property Value

  • 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 string SearchHistoryContext { get; set; }public string SearchHistoryContext { get; set; }Public ReadWrite Property SearchHistoryContext As string
    <SearchBox SearchHistoryContext="string"/>
    

    Property Value

    • 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

    Property Value

  • SearchHistoryEnabled
    SearchHistoryEnabled
    SearchHistoryEnabled
    SearchHistoryEnabled

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

    public bool SearchHistoryEnabled { get; set; }public bool SearchHistoryEnabled { get; set; }Public ReadWrite Property SearchHistoryEnabled As bool
    <SearchBox SearchHistoryEnabled="bool"/>
    

    Property Value

    • 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

    Property Value

Methods

  • SetLocalContentSuggestionSettings(Windows.ApplicationModel.Search.LocalContentSuggestionSettings)
    SetLocalContentSuggestionSettings(Windows.ApplicationModel.Search.LocalContentSuggestionSettings)
    SetLocalContentSuggestionSettings(Windows.ApplicationModel.Search.LocalContentSuggestionSettings)
    SetLocalContentSuggestionSettings(Windows.ApplicationModel.Search.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(Windows.ApplicationModel.Search.LocalContentSuggestionSettings settings)public void SetLocalContentSuggestionSettings(Windows.ApplicationModel.Search.LocalContentSuggestionSettings settings)Public Function SetLocalContentSuggestionSettings(settings As Windows.ApplicationModel.Search.LocalContentSuggestionSettings) As void

    Parameters

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

    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
    QueryChanged

    Occurs when the query text changes.

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

    Occurs when the user submits a search query.

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

    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 Navigate(Windows.UI.Xaml.Interop.TypeName,System.Object,Windows.UI.Xaml.Media.Animation.NavigationTransitionInfo) 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
    
  • ResultSuggestionChosen
    ResultSuggestionChosen
    ResultSuggestionChosen
    ResultSuggestionChosen

    Occurs when the user picks a suggested search result.

    public event TypedEventHandler ResultSuggestionChosenpublic event TypedEventHandler ResultSuggestionChosenPublic Event ResultSuggestionChosen
    <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 SuggestionsRequestedpublic event TypedEventHandler SuggestionsRequestedPublic Event SuggestionsRequested
    <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 @Windows.ApplicationModel.Search.SearchSuggestionsRequest.@Windows.ApplicationModel.Search.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(System.String). 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();
                }
    
            }
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll