Improve: The Search Box Experience

Proposal: Improve the Search Box Experience

Summary

Searching within an app is very common, especially if your app is more than a few pages deep. Today, you can build a search experience through either modifying a TextBox control or building on top of AutoSuggestBox. It’s important that we make sure the most common searching scenarios seen across the industry can be enabled in XAML as well with relative ease.

Rationale

Although our controls provide a lot of the necessary base components to creating a search experience, there are still a lot of scenarios to searching within a UWP app that are difficult to create using the properties and capabilities currently available.

The scope of this proposal is to ensure that a UWP developer can easily and efficiently build many of the most common experiences that are seen across the industry today in regards to searching with a search input box/control. In addition to that, the developer should also be confident that the type of experience that they are getting when using our search box control is coherent within the Windows ecosystem when it comes to controls with similar behavior.

Functional Requirements

#	Feature	Priority
1	Have a versatile, but simple default search box experience and setup process	Must
2	Provide documentation guidance around how to set up and create a basic and common search experience	Must
3	Make it easy to create explicit and implicit search experiences, with a search box control behavior that reflects the type of search that is enabled	Must
4	Intuitive keyboard support for navigation within the suggestions dropdown - for both implicit and explicit searches	Must
5	Suggestion predictions (or “ghost”) text within the input field	Must
6	Support a compact mode to enable high-density or limited app real estate scenarios	Must
7	Allow certain items in the suggestions dropdown to be query events, and some to not	Should
8	Enable the query icon to be displayed at the beginning of the text string as an icon	Should
9	Have a custom content region within the input field	Could

Usage Examples

The following are a set of scenarios attempting to cover the most common searching experiences.

A. Simple input field with explicit searching

User Experience
User clicks into the search box to give it focus User inputs a search string The search button icons goes from disabled to enabled once text input is received User then explicitly presses enter or clicks the query icon button and the search is committed

What The Developer Writes

<SearchField Width="250" QuerySubmitted="mySearchField_QuerySubmitted"/>

private void mySearchField_QuerySubmitted(SearchField sender, 
    SearchFieldQuerySubmittedEventArgs args)
{
    string search_term = mySearchField.Text;
    var results = GetItemsResult(myDatabase);

    //Populate a ListView or page with sorted results...
}

B. Simple input field with implicit searching

User Experience
Users sees the search box and clicks into it to give focus Once text input is received, the query icon is replaced with a clear button As user types, a separate suggestions or results list is live-updating Once the desired result is shown to the user, they click it and their search experience is implicitly finished </ui> The query icon is never interact-able

What The Developer Writes

<SearchField Width="250" SearchMode="Implicit" TextChanged="mySearchField_TextChanged/> 

private void mySearchField_TextChanged(SearchField sender, SearchFieldTextChangedEventArgs args)
{
    string search_term = mySearchField.Text;
    var results = GetItemsResult(myDatabase);

    //Update a Listview or page with sorted results...
}

C. Searching with suggestions and keyboarding

User Experience (explicit search)

User Experience (implicit search)

User clicks into search box User types in text query string Once finished, the user presses enter or clicks the search button and the search commits A search results dropdown/popup list appears User arrows down to put selection on the first item, and can arrow down or up to put selection on the subsequent items in list User presses enter or clicks on a selected item in the list The item selected is executed on (opening another window, navigating to another page, updating current page, etc.)

User clicks into search box User types in text query string As the user types, a suggestions dropdown/popup list appears below, updating as user refines search string User arrows down to put selection on the first item, and can arrow down or up to put selection on the subsequent items in the list User presses enter or clicks on a selected item in the list The item selected is executed on (opening another window, navigating to another page, updating current page, etc.)

If at any point the user clicks away or the search box loses focus, the suggestions list will close and the user’s search string will remain in the box. If focus is returned to the search box, in explicit searching the user must press enter to show the suggestion results list again, but in implicit searching the list will re-hydrate when the control received focus again.

What The Developer Writes

On either TextChanged or QuerySubmitted, populate the suggestions ItemSource attached to the search control:

string search_term = mySearchField.Text;
var results = GetItemsResult(myDatabase);

mySearchField.SuggestionItemsSource = results;

private void mySearchField_SuggestionChosen(SearchField sender, 
    SearchFieldSuggestionChosenEventArgs args)
{
    Frame.Navigate(resultsPage);
}

Supplying the search control’s suggestions list with a list of items to be displayed will trigger the suggestions dropdown to show. Specifying no source to the suggestions will never display a popup dropdown attached to the control.

D. Searching with suggestions, keyboarding, and text predictions

User Experience

A suggestion list is shown (either implicitly or explicitly, see scenario C as it’s behaviors still apply) User arrows into the list As the user navigates through the list, “ghost” text of the items being selected in the list by the user appear in their input box User Presses Spacebar on Selected Item Selected item text is added to the input field with a trailing space character at end of string No QuerySubmitted or SuggestionChosen events fire User Presses Right Arrow on Selected Item Selected item text is added to the input field with no trailing space character No QuerySubmitted or SuggestionChosen events fire User Presses Enter on Selected Item Selected item text is added to the input field and executed on

What The Developer Writes

private void mySearchField_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
    mySearchField.PredictionText = selectedItem.Text;
}

E. Compact search mode

User Experience
User sees the search icon button The user clicks on the button and it expands into a search input field </ui>

What The Developer Writes

<SearchField Width="250" IsCompact="True"/>

F. Developer can specify “non-selectable” suggestions in the dropdown

User Experience

Search History User puts focus into the search box A suggestion dropdown appears with recent search terms listed and un-selectable helper text indicating that the popup is a search history If the user types anything into the search string the history refines or disappears, depending on if any terms match the history If the user arrows down into the suggestion history, the un-selectable text will be skipped, just as disabled text is in a ListView No Results User enters terms and activates a search, either explicitly or implicitly A search is preformed but no results match the users’ terms The suggestions box is triggered, but displays only a non-selectable list item indicating that the search found nothing </ui>

What The Developer Writes

On a OnFocus event or after a search is completed, the developer can specify which elements in the suggetions list are non-selectable.

A disabled suggestion item will not fire a QuerySubmitted, SuggestionChosen or SelectionChanged.

mySearchField.SuggestionItems[0].SelectionState = SuggestionItemsSelectionState.Disabled;

G. Enable alternate query icon placement

User Experience (explicit search)	User Experience (implicit search)
User puts focus on the search box The user enters search terms and presses enter, no explicit mouse invocation is necessary The search is committed </ui>	User puts focus on the search box The user enters search terms and as the input is received results are updated and shown to the user User selects desired results and search is implicitly finished

What The Developer Writes

<SearchField QueryIconPlacement="Left" Width="250"/>

H. Secondary in-line content

This could be a variety of scenarios:

• Showing x of n results for finding words on a page (image example)
• A spinning progress ring indicating that a search is being preformed
• A fav icon button for a browser search

Most of these scenarioss visual affordances are telling the user what’s going on with their search, or layout efficiency.

What The Developer Writes

<SearchField Width="250">
    <SearchField.SecondaryContent>
        <TextBlock Text="0 of 5" />
    </SearchField.SecondaryContent>
</SearchField>

Open Questions

Currently working on aligning with other internal teams on how text predictions should operate with keyboard and mouse behavior. Once an agreement is reached this feature request will be updated. At the moment however, the defined text prediction behavior in this document is tentative.

[michael-hawker]

I’m trying to see how this isn’t an extra style/extension/helper/improvement to the AutoSuggestBox; wasn’t that it’s original purpose? Maybe start with a section calling out the current limitations/drawbacks to AutoSuggestBox and why adding to it wouldn’t work?

I know as a developer, the UX for the search box hasn’t been as big of a struggle as all that comes before and after it:

1. Gathering the diverse set of possible inputs if it’s truly across the app or documents within the app from different sources
2. Showing a list of all the results with context of where they are after the user selects a search term
3. Providing navigation from the result to where in the app that result came from
4. Highlighting the search term within context of where it was found when navigated from 3

I mean it’d be great to have more features/properties to AutoSuggestBox, as the API looks similar as is, than create a new control from the UI perspective. But if we could solve any of the other pieces of this puzzle, I think that’d be a bigger win.

[dotMorten]

I definitely have a big 👍 for the compact/expanded mode on AutoSuggestBox. It’s a quite common pattern for search controls (For instance the Windows Store app is one example, but it’s fairly common on android and ios too to reduce space taken up). It’s also a feature used in Xamarin.Forms’ Shell, and something I would use there once it moves to WinUI.