Guidelines for search

A sample of what a standard search box control looks like

Use these guidelines to help provide search results for your app's content. The guidelines include help for providing search suggestions and placeholder text in the search box, and designing a search results page.

See this feature in action as part of our App features, start to finish series:  Windows Store app UI, start to finish


The search box is a control that can be used to enter search query text.

Consider adding a search box to your app canvas if search is one of the main ways people will get to content in your app. A search box is a great way for users to know where to start. If space is a concern for your layout, use an icon that expands to reveal a search box. Also, you can put your search box in the app bar. Consider putting the search box on every page in your app. Users may be confused if some pages have a search box and others don't, but this decision depends on context and the purpose of your app.


A screen shot that illustrates the standard search box control

Implementing Search

If your app has content that users might want to search, add a search box to your app canvas.

  • Use the SearchBox control for Windows Store apps using C++, C#, or Visual Basic and the WinJS.UI.SearchBox object for Windows Store apps using JavaScript.

  • Regardless of where your app's content is located, for example on the local file system, or through a web service, you can use the search box to respond to user queries and display search results in an app page of your own design.

  • A search box is a great way for users to know where to start. If space is a concern for your layout, use an icon that expands to reveal a search box. Also, you can put your search box in the app bar.

  • If you need search UI in the app bar, place it in the upper app bar. In Windows Store apps using JavaScript, you can place search UI in the nav bar.

  • Consider putting the search box on every page in your app. Users may be confused if some pages have a search box and others don't, but this decision depends on context and the purpose of your app.

Customizing suggestions and placeholder text in the search box

When people start typing a query into the search box, the app supplies search suggestions in a suggestions flyout beneath the search box. The app supplies these by using the AppendResultSuggestion and AppendQuerySuggestion methods.

The search box takes a maximum of 25 search suggestions.

An app can provide two types of search suggestions: query suggestions and result suggestions. You can think of result suggestions as answers and query suggestions as possibilities.

  • Query suggestions are frequently auto-completions of the user's query text, and they provide queries that the user might want to search for. For example, let's say the user is searching for an app in the Store app and enters the query "word" in the Store app's search box. "Wordament" and "Wordpress" might appear as result suggestions, and "word games" and "words" might be query suggestions. If the user selects one of the query suggestions, the Store app take the user to a search results page for that query. Although it's usually the case that query suggestions are auto-completions, they don't have to be. For example, if you're in a recipe app searching for “eggs,” quiche is a viable query suggestion.

  • Result suggestions are strong or exact or matches to the user's query that the user may want to view immediately. For example, the Wordament app is suggested as a result, under the Recommendations label, for the "word" query in the Store app. If the user selects the Wordament result suggestion, the Store app takes the user directly to the Wordament app page in the Store.

Result suggestions, which are usually closer matches, go on top of the suggestions flyout, and query suggestions follow.

When the user enters a search query, the system automatically provides search history suggestions for possible queries in the search box. These suggestions are based on the user's previous interactions with your app's search box, before suggestions that your app provides. You can disable the search history.

Don't use suggestions to filter or scope search results for your app. Filtering and scoping options should be placed with the results in the app's search results page, where they can refine the search results. In contrast, suggestions should be placed in the search box, because they are directly related to the query text that the user enters.

Query suggestions

  • In general, consider providing query suggestions to help the user search quickly.

  • Use query suggestions as way to auto-complete query text that users can search for in your app. This helps users search quickly by reducing the amount of typing needed to complete a search. Instead of entering the entire query, users can select one of the suggested queries and immediately execute the search.

  • If the user selects a query suggestion, navigate immediately to a search results page for the selected query.

  • Your app's query suggestions should contain the user's current query text. Because your query suggestions usually are auto-completions that are based on the current query text, they should contain the current query text.

  • Your query suggestions should reflect the content of your app and the results it can provide, instead of providing results from a more global context. By searching the content your app can provide, your query suggestions help the user figure out what they can search for in your app. For example, the Weather app automatically completes the user's query to suggest cities for which the app can provide weather reports.

Result suggestions

  • If you want to recommend strong or exact matches for the user's query, provide result suggestions.

  • Use result suggestions to take the user directly to the details of a particular result without first taking them to a search results page.

  • A result suggestion should consist of an appropriate image or thumbnail, a relevant title or label, and a brief description. The image size is fixed at 40x40 pixels.

  • The image, title, and description help the user to determine quickly whether the suggested result is what they were searching for.

  • With a small result set, consider filtering results on the app's canvas, which means that as the user types, the results update immediately with each keystroke. This is a form of filtering as the user types. For example, the Reading List app filters results this way. The search history should be turned off, and the app updates its canvas as fast as possible. Implementing this feature depends on UI performance and on how quickly you can return a small result set back, usually with no more than ten results. If the user has to type more than three characters to get a set of ten results, consider using suggestions as described previously.


  • Use a separator to define a group of a similar or conceptually aligned results.

  • You can add separators to the list of suggestions that your app supplies to the search box, but each separator counts toward the limit of 25 suggestions.

  • If you want to supply multiple types of result suggestions, use labeled separators to help users distinguish between results. For example, when you provide more than one suggestion for results with different content types, like movies and TV shows, use a labeled separator to provide a meaningful distinction between the "movies" and "TV shows" content types.

Placeholder text

  • Consider using placeholder text in the search box to describe what users can search for in your app. For example, a recipe app could show "Search for recipes."

  • Show placeholder text only when the search box is empty. Clear the placeholder text when the user starts typing in the search box.

  • Set the placeholder text of the search box to a brief description of the searchable content in your app. For example, a music app that supports searching by album name, song name, or artist name could set the placeholder text to "Album, artist, or song name".

  • Use placeholder text to provide context to the user about what is being searched. This is important when a subset of the app is being searched in a given context. For example, use text like "Artist" or "Album" in a music app that searches artists or albums in subsections dedicated to those topics.

Designing a search results page

Craft your search experience around your brand. Search results user experience (UX) should be tailored to your content, similar to how you present content in your app.

When users submit search queries to your app, they see a page that shows search results for the query. Because you design the search results page for your app, you can ensure that the results presented to your user are useful and have an appropriate layout.

Title the search results page, and put the user's query text in the search box to provide context.

Indicate the ranking of search results by ordering and laying them out by relevancy, from best match to weakest.

Indicate why a search result matches the query.

Don't flip the search icon in bi-directional languages.

Highlight the matching search terms to show the part of the suggestion that matches the query. This is valuable in all cases, if the match property is being shown to the user.

Filtering results

  • You can improve your app's search results page by letting users set filters and scopes to refine the set of search results.

  • If you have a large number of results from a query, consider providing a way for the user to filter the results.

  • Let users filter and scope search results from the search results page.

  • Indicate the number of results available with each filter or in each scope. This helps users understand whether they are effectively refining their search.

  • Provide a way to clear the filters and see all results.

Search box sizing

  • When using the in-app search box control, keep in mind the various window sizes and the control's position relative to the title.

  • Avoid clipping the title.

  • At smaller window sizes, you may want to collapse the search box to a button with the search icon, depending on the contents of your title bar. When users click, expand the search box and hide the elements that it would occlude, like the title.

  • Don't occlude the back button, since it's a core piece of navigation and it's important for users to have access to it at all times.

  • The minimum height of the suggestions flyout is 200 pixels.

  • The default maximum height is 300 pixels, and you can change this.

  • The minimum width is 270 pixels. You can change this, but the Input Method Editor (IME) window won't have a smaller width than 270 pixels.

Always pre-populate the query on results pages. The results should persist if the user navigates away and back. Clear the query text on forward navigation, even from a results page.

Maximum placeholder text length is 128 characters. Maximum query text length is 2048 characters. Maximum length of all of the textual fields in a suggestion (text, detailtext, image alt text) is 512 characters.

Enabling type-to-search

If you're using the search box, consider letting people search simply by typing, without having to click or tap in the search box control first. You can do this by enabling searchPane.showOnKeyboardInput or FocusOnKeyboardInput. This is the same kind of behavior users are familiar with from using the Start screen on Windows 8. Many people use a keyboard to interact with Windows 8, and letting users search by typing makes efficient use of keyboard interaction.

Don't enable type-to-search on every page of your app. Consider where type-to-search would be most useful for your users and where it might be a problem. For example, you'd want to disable type-to-search if other controls that take input, like a text box, get focus. Otherwise, the search box continues to take the characters.

Use the following guidelines to help you figure out how to add type to search to your app so that it creates a positive experience for your users.

  • Enable type to search on your app's main page (or pages).

    Do this for your app's main page and any app page that displays, directly or indirectly, all of your app's searchable content. Your main page is the page that is displayed when users enter your app. In some cases an app may offer multiple main pages that offer different presentations for similar content. In this case type to search should be enabled on all of these pages.

  • Enable type to search on your app's search results pages.

    After users get search results they often want to search again. You should enable typing directly into the search box from search results pages, so that keyboard users can perform another search quickly.

  • Disable type to search on most other pages in your app.

    In most cases, you should disable typing directly into the search box on pages that are not your app's main page or a search results page. For pages with one or more input boxes, your app can disable type to search if a text box gets focus.

Using the Search contract

Use the following guidance if your app uses the Search contract.

  • Add a button with the search icon to your app to invoke the search pane programmatically and scope it correctly. Use the search glyph, Segoe UI Symbol 0xE0094 at 15pt, to invoke the pane.

  • A prominent search icon gives users a strong visual cue that tells them where to begin. When users select the icon your app should open the Search charm programmatically so that users can enter their query using the search pane. Using the Search charm in this way helps make your app more intuitive.

  • If you use the search box in your app, you can no longer make calls to the SearchPane APIs; doing so throws an exception with this message: "Cannot create instance of type 'Windows.UI.Xaml.Controls.SearchBox.'" Your app can still use the Search contract; in fact, you should use the Search contract to support search activation code.

See Adding search to an app for more information on search and the Search contract, and Quickstart: Adding search to an app for a code example.

Related topics

For designers
Guidelines for find-in-page
For developers (HTML)
Adding search
Quickstart: Adding search
For developers (XAML)
Adding search
Quickstart: Adding search



© 2015 Microsoft