Guidelines and checklist for search (Windows Store apps)

Use these guidelines to help your app to participate in the Search contract and integrate with the Search charm. The guidelines include help for providing search suggestions and placeholder text in the search pane, and designing a search results page.

When you add search with the Search contract, users can search your app's content, from anywhere in their system, through the Search charm. If your app is the main app on screen, users can search its content immediately by selecting the Search charm. Otherwise, users can select the Search charm and then select your app from the list of apps in the search pane.

Using the Search charm helps you:

• Take advantage of muscle memory that users have built by using the Search charm in the system and in other apps.

• Ensure that users have a consistent and predicable experience when they search and when they change search settings.

• Make your app more visible by placing it at the top of the list of searchable apps if the user searches your app frequently.

Appropriate use of search

• Rely on the Search charm to let users search for content in your app.

  You can and should rely on the Search charm instead of creating search-specific UI to search your app's content.

  Windows ranks apps listed in the Search charm based on how often those apps are searched. The more often users search your app through the Search charm the better your app's rank and position in the list of searchable apps. Additionally, Windows automatically tracks the user's search history with your app if they enter queries through the Search charm.

  Regardless of where your app's content is located (on the local file system, or through a web service), you can use the Search charm to respond to users' queries and display search results in an app page of your own design.

  When a user selects the Search charm, a search pane opens with a search box (where they can enter a query) and a list of searchable apps, as shown in the screen shot. If your app is the main app on screen, it is automatically highlighted in the list of apps in the search pane. For example, Apps is highlighted in the screen shot. Tip  You can use shortcut keys to access the charms, including the Search charm. The Windows Logo Key + C lets you select any of the charms, and the Windows Logo Key + Q selects the Search charm. Learn more about adding search to your app in Quickstart: Adding search.

   

• If users need search to get started using your app, consider adding a search icon to your app canvas.

  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 and helps keep your app's search experience consistent with search in Windows 8 and other apps.

  For example, a reference app like a thesaurus or encyclopedia is likely to emphasize search. Typically, when users open apps like these they want to search for information about a specific topic or word. Having a search icon prominently displayed on the app canvas in apps like an encyclopedia or thesaurus helps to ensure that users know how to get started searching for information.

• If search is the primary purpose of your app and you want to show extensive suggestions, consider adding a search box to your app canvas.

  A prominent search box helps indicate to users that your app specializes in search. When users enter a query, you can use your own custom layouts to display a greater number of more detailed suggestions on your app canvas. If your app requires more depth and flexibility for displaying suggestions than what is available through the Search charm, consider adding a search box to your app canvas.

  For example, the only purpose of the Bing app is to search. The app differentiates itself from other search-based apps by using custom layouts to display detailed search suggestions and interactions. Because the Bing app is entirely based on search and provides deep, variable suggestions, the app adds a search box to its app canvas, as you can see in the screen shot.

  

  However, adding search UI to your app also has disadvantages that you should consider. For example, if you provide an in-app search box, the user might have two different search histories for your app: one history tied to the in-app search box and another tied to the Search charm. Additionally, searches performed using your in-app search box (or other search UI) won't increase your app's rank and visibility in the search pane.

  If you decide to add a search box to your app canvas, use these guidelines to help you maintain consistency between your search box and the search pane:

  • If the user updates the query in your app's search box, use trySetQueryText to set the query in the search pane to the new query.
  • If the user clears the query in your app's search box, use trySetQueryText to clear the query in the Search charm by setting it to an empty string.
  • If your app is snapped, don't update the query in the search pane. When your app is not the main app on screen the search pane can't be opened and calls to trySetQueryText don't work.

  • If the search pane is open, grey-out or hide your app's search box to prevent confusing the user with multiple search boxes. You can see one way to apply this guideline in the Bing search app.

Inappropriate use of search

• If search is not the primary purpose of your app, don't add search UI to your app.

  If users search your app from in-app UI, your app’s rank in the list of apps could suffer making your app less visible to users. Additionally, Windows will not track users' search history for searches performed using in-app search UI.

• Don’t place search UI in the app bar.

  Maintain the app bar as a place to show commands that are unique and specific to your app. Many app developers want to provide a search experience for users, and integrating with the Search charm (by participating in the Search contract) is a great way to do this.

• Don’t use the Search charm to add a "find-in-page" feature to your app.

  When using "find-in-page", users want to stay on the current app page, but the Search charm will navigate them away, replacing the current page with another app page that displays search results.

  Instead, add a control to your app bar that lets users "find-in-page" and group the "find-in-page" feature with related features like "replace". For more info, see Guidelines and checklist for find-in-page. Learn more about adding commands to your app bar in Quickstart: Adding an app bar.

User experience guidelines: customizing suggestions and placeholder text in the search pane

When the user selects the Search charm and starts typing a query into the search box, search suggestions are shown just below the box in the search pane. These suggestions are supplied by the main app on screen if it has implemented the Search contract. There are two types of suggestions an app can provide: query suggestions and result suggestions. Query suggestions are auto-completions of the user's query text, and provide queries that the user might want to search for. For example, in the screen shot the user entered the query "word" and the "Wordament HD" and "WordPress.com" queries were suggested. If the user selects one of these query suggestions, the Store app will take the user to a search results page for that query. Result suggestions are strong or exact or matches to the user's query that the user may want to view immediately. For example, in the screen shot the Wordament app was suggested as a result (under the Recommendations label) for the "word" query. If the user selects the Wordament result suggestion, the Store app will take the user directly to the Wordament app page in the Store. In the screen shot of the search pane, the Store app provides two query suggestions and one result suggestion for the user's query, "word".

• Always provide 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 is a great way to help 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.

  Your query suggestions should contain the user's current query text. Because your query suggestions should be auto-completions that are based on the current query text, they should actually contain the current query text. For example, the suggested queries provided by the Weather app in the screen shot all contain the current query text, "f". Your query suggestions should directly reflect the results that your app can provide. By reflecting the results your app can provide, your query suggestions can help the user figure out what they can search for in your app. For example, the Weather app in the screen shot automatically completes the user's query to suggest cities for which the app can provide weather reports.

   

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

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

  Use result suggestions to let the user go directly to the details of a particular result without the need to navigate 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, title, and description help the user to determine quickly whether the suggested result is what they were searching for, as shown in the screen shot.

   

• If you want to supply multiple 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 vs. TV shows), use labeled separators to provide a meaningful distinction between the content types.

  Separators can be added to the list of suggestions that your app supplies to the search pane, but each separator counts towards the five-suggestion limit.

• If the user selects a result suggestion, immediately take the user to the details of that result without first taking them to a search results page.

• If you provide both types of search suggestions (queries and results), you should provide only one result suggestion and it should be displayed last, at the bottom of the list of suggestions.

  While the user enters a search query, Windows automatically provides suggestions for possible queries in the search pane. These suggestions are based on the user’s search history with your app and will be shown first, before suggestions that your app provides. Showing your suggested result last helps visually distinguish it from suggested queries, as shown in the screen shot.

   

• Supply no more than five search suggestions.

  The search pane will show only the first five suggestions (for queries and/or results) that are supplied by your app.

• 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 pane, because they are directly related to the query text that the user enters.

• Use placeholder text in the search box to describe what users can search for in your app.

  Placeholder text is shown only when the search box is empty and is cleared if the user starts typing into the box.

  We recommend that you 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 should set the placeholder text to be: "Album, artist, or song name".

User experience guidelines: designing a search results page

When the user submits a search query 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. For example, the screen shot shows the search results page created for the Contoso app, which displays example search results for the "item" query.

• Let users see what they searched for (their query text).

  For example, in the Contoso app's search results page, the "Results for" string next to the "Contoso" app name indicates that the current set of results is for the "item" query.

  

• Use a list view control and Search contract templates to bring the Windows 8 look and feel to your app.

  Using a list view (or grid view) control to display search results helps produce a consistent and predictable user experience and will reinforce what users have already learned in the system. The Microsoft Visual Studio Express 2012 for Windows 8 templates for the Search contract include a list view control.

  For C#/C++/VB, the ListView and GridView controls let you use a list or grid layout, respectively (see Quickstart: Adding ListView and GridView controls).

  For JavaScript, the listView control lets you use either a grid layout or a list layout (see Quickstart: Adding a listView).

  Search results are ranked and typically have a strong order from best match to weakest. You should order the search results on your page based on this search rank. Because grid layouts in Windows 8 use horizontal scrolling, search results that are displayed in a grid layout should be ordered first from top to bottom and then from left to right. Because list layouts use vertical scrolling, search results that are displayed in a list layout should be ordered from top to bottom.

• Avoid putting important or relevant results or information on the right edge of the screen.

  The Search charm is lightweight and quickly gets out of the way whenever the user interacts with the app canvas. However, to help users quickly glance at results, avoid showing the most important or relevant result on the right side, as this side might be temporarily covered up when the search pane is visible.

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

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

  Best practices for letting users filter and scope search results in your app's search results page include:

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

  For example, the Contoso app's search results page provides a set of filters above the results, with counts next to each filter.

  

• Indicate why a search result matches the query.

  For example, the Contoso app's search results page in the screen shot highlights the user's query ("item") in each result. This is called hit highlighting.

  

• Let users navigate back to the last-viewed page after they look at the details for a result.

  When they search, users often look at several results as they gather information. Looking at a specific result and then getting back to the search results page should be easy.

  A common way to accomplish this is to include a back button in the app UI as shown in the screen shot. This back button should be used to go to the page that the user was interacting with before they submitted their search.

  

User experience guidelines: enabling type to search

If your app participates in the Search contract, you should consider enabling searchPane.showOnKeyboardInput. This gives your users the ability to search your app by typing directly into the search box of the Search charm when they begin typing. This is the same kind of behavior users are familiar with from using the Start screen on Windows 8. Many people will use a keyboard to interact with Windows 8, and letting users search by typing makes efficient use of keyboard interaction.

Of course, you should not enable type to search on every page of your app. Consider where type to search would be useful for your users and enable type to search only for those pages. 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).

  You should enable type to search so that users can type directly into the search box from your app. 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 example, here is a list of some types of pages where we recommend that you disable type to search:

  • Pages with one or more input boxes. You should disable type to search on pages that have input boxes because if users begin typing while they are viewing such a page, their input should appear in the boxes on that page instead of in the Search charm's search box.

  • Scoped pages that display only a subset of the content that can be searched by your app. If users search your app from a scoped page, it might be unclear whether they can search all app content, or only content within the scope of the page. It's hard to predict what users will want, and having multiple search scopes (content subsets) is more confusing than a single, large scope. We recommend that you disable search when a user is looking at a narrowed set of items, to avoid confusion.

  • Pages where your app supports "find in page" functionality. Often pages that display a single article, image, or item should let users locate a query on the current page ("find in page"). You should disable type to search on these pages because searching through the Search charm will take users away from the current page. For user experience guidelines about using "find in page" in your app, see Guidelines and checklist for find-in-page.

User experience guidelines: implementing form-based search

Some apps implement form-based search functionality, which enables users to locate a specific item based on multiple criteria. The following table presents the practices recommended for implementing form-based search.

• Use form-based search to enable users to find a specific item in a large, potentially dynamic set.

  Travel, booking, or scheduling applications are the most likely kinds of apps to provide form-based search. The primary purpose of these apps is to enable users to locate the item that best matches specific constraints or criteria, and to take action on that item. Form-based search functionality is core to the app’s scenarios and should be located in the body of the app.

• Use the body of the app as the starting point of form-based search.

  If your app provides form-based search, place the form in the body of the app and provide a means to start the search, so that the user experience is independent of the Search charm. If form-based search is only one scenario in your app, it can have its own page. In this case, provide an entry point for the search page through your app’s main page or app bar.

• Provide relevant filters for form-based search results to enable filtering the set and locating target records.

  Frequently, users need to refine a search, based on the same criteria that were used to launch the search, or by using different pivots. Provide controls on the canvas for refining search results.

• Don't use the Search charm to perform searches on multiple distinct criteria.

  Apps that use the Search charm provide an experience in which results related to a single search term or phrase are suggested immediately or returned as users start typing. Often, these results are sorted by using a relevance algorithm.

Tips for responding if your app is activated for search

• Be sure to handle a search activated event for an empty query.

  When users open the search pane (through the Search charm), they can choose an app to search with when they enter a query into the search box. In your activated event handler, when your app is activated for search, you should also check to see if your app was activated with an empty queryText string.

  If your app is activated with an empty queryText string and your app is already running or is suspended, return to the app's last-viewed page. If your app isn't running or suspended, take the user to a landing page appropriate for this search.

  Generally, your app's home page is an appropriate landing page when the queryText is an empty string, but you can also design an app page specifically for this purpose.

  For C#/C++/VB, see QueryText.

  For JavaScript, see queryText.

• Save the previous state of the app when the app is activated for search.

  The power of the Search contract enables users to invoke an application for search from anywhere in the system by using the Search charm. The application must be able to respond to a search activation event at any time. Applications should save their state and provide users with a way to get back to that previous state where appropriate.

  Example: In a mail application, the user might have a partially composed message. At a later time, if the user switches to the mail app to search in it, the mail application should save the message as a draft and provide users with a way to get back to it.

• If your app is snapped, navigate to your search results page while responding to search activation.

  If your app is snapped when the user searches in it, the search activated event fires and your app automatically unsnaps. Unsnapping causes a size changed (or resized) event to fire, and your app becomes the main app on screen.

  The search activated event and the unsnap event are fired in this order:

  1. Search activated event

     In response to this event, your app should display its search results page for the query.

     For C#/C++/VB, see OnSearchActivated.

     For JavaScript, see onactivated.

  2. Size changed event

     In response to this event, check whether your app has unsnapped, and if it has, adjust your app to become the main app on screen. Make sure your response to this event does not take the user away from your app's search results page. If your app doesn’t load the search results page, the user might feel that the app is broken and is not searching properly.

     For C#/C++/VB, see SizeChanged.

     For JavaScript, see onresize.

• Save the search results page, and the filters and scope for the last query in case your app is activated to search for that query again.

  The Search charm lets users switch between multiple apps quickly to compare results for the same search query. The user might submit a search query to your app and set filters for your app's search results. The user might then switch to another app, search that app using the same query, and then come back to view your app's search results again.

  When this happens, your app is activated for search again. Your app's search results page should show the same filters that the user set the first time your app displayed results for this query. If the current query is the same as the last query, you should not get a new set of search results, but instead load your previous search results page, including the filters and scope that the user had applied, and the exact location where the user was focused.

Related topics

Adding search

Quickstart: Adding search

Build date: 11/29/2012