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
![image](https://user-images.githubusercontent.com/6964369/49896059-1c6e0a80-fe07-11e8-887d-9ff6eed2edc3.png)
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
![defaultimplicitasb](https://user-images.githubusercontent.com/6964369/49896149-5a6b2e80-fe07-11e8-8f9c-831b79789116.png)
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
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
![asbwithsimplesuggestions](https://user-images.githubusercontent.com/6964369/49896366-fbf28000-fe07-11e8-8fcd-a558f92188de.png)
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
![image](https://user-images.githubusercontent.com/6964369/49957637-4aae2180-febd-11e8-9f77-3a3b96b589b5.png)
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
![image](https://user-images.githubusercontent.com/6964369/49961881-a3cf8280-fec8-11e8-8eba-0cee8d876ad4.png)
User Experience |
- User sees the search icon button
- The user clicks on the button and it expands into a search input field
|
What The Developer Writes
<SearchField Width="250" IsCompact="True"/>
F. Developer can specify "non-selectable" suggestions in the dropdown
![image](https://user-images.githubusercontent.com/6964369/49971147-55c77880-fee2-11e8-9c87-d1d756b74639.png)
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
|
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
![image](https://user-images.githubusercontent.com/6964369/49971801-8d372480-fee4-11e8-98b6-3e52c10f69a8.png)
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
|
- 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
![image](https://user-images.githubusercontent.com/6964369/49972431-7560a000-fee6-11e8-9031-c029ec3c3901.png)
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.