Search Provider Extensibility in Internet Explorer

Starting with Windows Internet Explorer 7, the Instant Search box provides an AutoComplete feature so users can search for similar search terms used in previous searches. Internet Explorer 7 also enables users to add multiple search providers. Search improvements in Windows Internet Explorer 8 focus on helping users search by significantly improving the Instant Search box drop-down menu and supporting search suggestions. This topic addresses two audiences: end users and Web site developers. The first part of this topic focuses on helping end users install search providers, manage search providers, and use a search provider to find what they want. The second part of this topic focuses on Web site developers by showing how to promote a search provider and how to use search suggestions to improve a user's experience with your search provider.

This topic discusses the following subjects:

End User Search Features

The Instant Search feature in Internet Explorer 8 enables the end user to add favorite search providers and quickly switch between providers during a search. Internet Explorer 8 supports search suggestions to help users initiate better search queries. Search providers can also provide instant answers to queries. In addition to using the Instant Search box, users can access all of their search providers through the Accelerators menu. These features are designed to improve search experience and increase productivity for end users. This section covers the following topics:

Adding Search Providers

The Instant Search box in the upper-right corner of the Internet Explorer 7 and Internet Explorer 8 browser window replaced the Windows Search Assistant (or Search Pane). Before you can use a specific search provider, you must add that provider to your list. To add a search provider, browse to the provider's Web site. There are two ways to install a search provider.

First, the provider Web site might display a link or button that you can click to add them as a search provider to your list. By clicking the link or button, the Add Search Provider dialog box is displayed so you can confirm your selection.Add Search Provider dialog box Figure 1. Add Search Provider dialog box. If this particular search provider is already installed, you will get a dialog box saying so or you will get a dialog box with options to upgrade that provider. For example, the search provider may offer search suggestions now where it did not before.

The second way to add a search provider is by discovery. After the provider's Web page loads, the drop-down arrow on the Instant Search box turns orange, indicating that a search provider can be installed. Orange drop-down arrow on the Instant Search box Figure 2. Orange drop-down arrow on the Instant Search box. When you click the orange drop-down arrow, a list of the search providers that are installed and other available options is displayed. A golden icon appears to the left of the search provider's name that Internet Explorer 8 discovered. When you click the Add Search Providers option, a list of the available providers is displayed. The following picture shows the Live Search options: Products, Images, and Videos.Add Search Provider menu showing search providers and search options Figure 3. Add Search Provider menu showing search providers and search options.

Note  To help you get started, there is a list of providers available from the Windows Internet Explorer Gallery. The gallery can be accessed at any time by choosing Find More Providers... from the drop-down arrow on the Instant Search box; as shown in Figure 3.

Adding Your Own Search Provider

If your search provider does not provide a direct way for you to add it as a search provider, you can still add it manually. Follow the instructions on the Windows Search Guide page to create your own search provider. Note that this widget adds the provider only as a search provider without search suggestions. If you know that the provider offers search suggestions, use the search provider's Web site to add the provider.

Managing Search Providers

The maximum number of search providers you can install is 200, which might be challenging to manage.To manage your search providers in Internet Explorer 8, click the drop-down arrow on the Instant Search box, and then click Manage Search Providers. You can reorder providers, change the Default status, and remove a provider, as shown in the following image. Manage Internet Explorer Add-ons dialog box Figure 4. Manage Internet Explorer Add-ons dialog box. To change a search provider's attributes, click the provider name, make your changes, and click Close.

Note  You cannot remove the current Default provider. To remove the default provider, you must set another provider to Default status. To do that, open the Manage Search Providers dialog box, click another provider, click the Set as default button. Then, click the provider you want to remove and click Remove.

Searching With My Favorite Search Providers

To perform a search, type the search term in the Instant Search box. While you might be familiar with this box in Internet Explorer 7, you will notice significant improvements in how you can search in Internet Explorer 8. After you click in the Instant Search box, a QuickPick menu is displayed. The QuickPick menu shows as many search providers' icons as the width of Instant Search box would allowed, making it easy to switch between providers. To see more search providers in the QuickPick, resize the Instant Search box. You can use the same term to search across these providers without having to navigate to each provider's Web site. QuickPick menu Figure 5. The QuickPick menu. After entering your search term, press ENTER to use the current search provider, or select a provider from the QuickPick menu to perform the search. If the search provider you use supports search suggestions, then search suggestions appear as you type. For example, if you search for "Xbox" by using Live Search, you might see the following list of suggestions.Live Search Suggestions drop-down menu Figure 6. Live Search Suggestions drop-down menu. The top part of the suggestion menu is the AutoComplete section that shows recent searches that match your current search term. The second part of the suggestion menu is the Suggestions section that lists search suggestions provided by the current search provider. The third part of the suggestion menu is the History section that lists previously visited sites showing Web site titles and URLs that match the current search term. Matching terms are highlighted. You can select a matching term to search. The QuickPick menu is displayed at the bottom of the menu for quick access to your top search providers. Internet Explorer 8 enables search providers to display visual suggestions. Search providers can supply a small image and text, as shiown in the following figure, or just an image which can be mixed in with regular text suggestions.Visual and text suggestions for the term Xbox Figure 7. Xbox visual and text search suggestions In addition, a search provider can offer instant answers to your search term. With instant answers, your provider can take you directly to the information you are looking for rather than to a search results page. This can make your search more efficient.

Search Using Accelerators

New to Internet Explorer 8 is the concept of Accelerators. Accelerators enable you to access service providers anywhere on the page. Every time you add a search provider to your list, Internet Explorer 8 automatically converts it to an Accelerator. To use this feature, highlight the text you want to search for and click the Accelerators icon Accelerators icon that appears. A condensed list of the Web services you have installed is displayed. Among them is your default search provider. To use a different search provider, click More Accelerators. The following picture shows the expanded More Accelerators menu.More Accelerators menu showing available Web services Figure 8. The More Accelerators menu showing available Web services.

Another benefit of an Accelerator is the ability to Preview search results. If your search provider supports search preview, you can simply select some text on a Web page, click the Accelerator's icon, mouse over your search provider's name (you may need to open the More Accelerators list to find it), and a preview window appears with search results for the words you selected. This makes it even faster and more convenient to search using your installed search providers. To learn more about Accelerators, see the article OpenService Accelerators Developer Guide.

Find on Page

The Find on Page feature is another improvement to the user experience in Internet Explorer 8. To start a search, click the Find option at the right of the QuickPick menu or use the shortcut key CTRL+F. The Find on Page feature searches the current page using the terms in the Instant Search box. As the following screen shot illustrates, all matches on the page are highlighted, and the first matching term is selected. The number of matches on the page is also displayed.Find on Page feature

Tips and Tricks

Here are some other features and hints not covered above.

  • Search history can be deleted. You can delete previous search terms and history pages from the History list. This is useful when you do not want terms you misspelled to appear in the AutoComplete section. As you type in the Address bar or the Instant Search box, search suggestions are displayed along with AutoComplete and History suggestions. Mouse over the item you want to delete from the AutoComplete or History list, and an X appears next to the item, as shown in the following picture. Click the X to delete the item from the list. Deleting an item from the History list
  • You can initiate a search from the Address bar. When using the Address bar, your current search provider will be used to offer search suggestions; however, the search will be performed by your Default search provider. To initiate a search from the Address bar, start the search with a ? followed by your search term. For example, to do a search for xbox, type ? xbox. If your current search provider offer search suggestions for xbox you will see them listed. Selecting a term or pressing ENTER will perform the search using your Default search provider.
  • The Instant Search box can be resized. To resize the Instant Search box, move the pointer to the left edge of the Instant Search box. When the horizontal pointer appears, drag to resize the Instant Search box.


Web Developer Search Features

Sites can now advertise search providers so that users can perform searches directly from the Windows Internet Explorer chrome without first having to navigate to a particular site. The default search provider is also used to perform searches from the Address bar. The first step in promoting your search provider in Internet Explorer 8 is to enable users to install your Web site as a search provider in the search box. To do this, there are two steps you need to take. The first step is to create an OpenSearch Description file for your search provider and the second step is to expose the description file on your Web site so that users can install it.

This section focuses on helping developers understand and take advantage of Internet Explorer 8 search features to improve user search experience. This section covers the following topics:

Creating an OpenSearch Description File

Before promoting your services and provide users with options to install your search provider, you must create an OpenSearch Description file. OpenSearch Description files are small XML files that describe your search provider to Internet Explorer 8. The following table describes the values in the OpenSearch Description file.

ShortName (required)This is the search provider's name that is displayed in the Instant Search box when your provider is selected.
URL (required)The URL for basic search queries to your search provider. It has to be an absolute URL.
Image (optional)Pointer to a favicon file of your search provider on your Web site. This icon is displayed next to the provider name in the Instant Search box. The icon must be a valid shortcut icon file otherwise a generic icon will be used. For more information, see the "Creating Icons in the Correct Format" section of the How to Add a Shortcut Icon to a Web Page article for instruction on how to create a favicon.
Suggestions URL (JSON) (optional)This is the URL where JavaScript Object Notation (JSON) suggestions can be retrieved.
Suggestions URL (XML) (optional)This is the URL where XML-based suggestions can be retrieved.
PreviewUrl (optional)URL to display results in an Accelerator Preview Window.


The following sample OpenSearch Description file defines the type of search services you intent to offer.

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="" xmlns:ie="">
	<ShortName>My Custom Search</ShortName>
	<Image height="16" width="16" type="image/icon"></Image>
	<Url type="text/html" template="{searchTerms}&amp;source=IE"/>   
	<Url type="application/x-suggestions+json" template="{searchTerms}"/>
	<Url type="application/x-suggestions+xml" template="{searchTerms}"/>
	<ie:PreviewUrl type="text/html" template="{searchTerms}"/>

All OpenSearch Description files must include the search provider name and search URL. Without these elements, Internet Explorer 8 cannot install your search provider. All search URLs must contain "{searchTerms}" somewhere in the query string. When Internet Explorer 8 navigates to this provider to get search results, "{searchTerms}" is replaced by the query string that the user typed into the Instant Search box. you should include an icon within the OpenSearch Description file. If Internet Explorer 8 cannot find an icon specified by the "Image" attribute it will use a generic icon Generic search provider icon to represent your search provider in the QuickPick menu.

A quick way to generate an OpenSearch Description file is to use a widget from the Windows Search Guide to Create Your Own XML file. Follow the instructions in the widget, and then click the View XML link from step 5. The widget creates XML syntax similar to the preceding code snippet. Save the output to an XML file, and then upload the file to your Web server. Make sure you have a valid XML file, and that the "&" characters in your URL are encoded.

Note  The widget only produces a basic XML file that you can use and customize. However, it does not generate any icon or suggestion URL. You would have to add those yourself.

Adding Search Suggestions to OpenSearch Description Files

In Internet Explorer 8, search providers can offer suggestions to users. By using search suggestions, users can create better search terms and find what they are looking for faster. To offer search suggestions for JSON and XML format, add the following elements to your description file.

<Url type="application/x-suggestions+json" template="{searchTerms}"/>
<Url type="application/x-suggestions+xml" template="{searchTerms}"/>

When you add additional URL elements, make sure the "text/html" type is listed first. This is for backward compatibility. The other types can follow in any order. By default, Internet Explorer uses the URL of "text/html" as the generic search URL when search suggestions are not available or not supported by earlier versions. However, when both URL for the XML and JSON exists, Internet Explorer 8 will use the XML suggestions URL.

Note  If users had added your search provider before it supported suggestions, they must add your search provider again. Internet Explorer 8 will detect that your search provider had already been installed but is now offering suggestions. The Add Search Provider dialog box will display an Upgrade Provider button and enable the checkbox for search suggestion.

Supporting Search Previews

All installed search providers are automatically converted to Accelerators. Because Accelerators support previews, this allows you to support search previews as well by adding a PreviewUrl to your OpenSearch Description file as shown here.

<ie:PreviewUrl type="text/html" template="{searchTerms}/>

With this element added to your OpenSearch Description file, you can offer a lightweight view of the search results page. The preview shows up in a 320 x 240 window when the user selects some text on a Web page, clicks the Accelerators icon, and mouses over your search provider name. For more information about Accelerators and the Preview feature, see the article on OpenService Accelerators Developer Guide.

Note  The ie:PreviewUrl is using the namespace provided by Internet Explorer's namespace declarations. When using this feature, make sure this declaration is defined in your OpenSearchDescription tag: xmlns:ie="".

Promoting Search Providers

After you create your OpenSearch Description file, you can promote your services to users. There are two primary ways to promote search providers. The first option is to provide your users with a link or button that points to your description file. The users will need to take action to install your provider. The second option is to make your provider discoverable. It requires one line of code at the top of your Web page and allows Internet Explorer 8 to discover your provider as users browse your site.

The following code adds a search provider when a user clicks a link.

<a href="#"
   >Add Search Provider Example</a>

The code makes a call to the AddSearchProvider method. The AddSearchProvider method is available from the external object of window. When you run this code from an HTML page in Internet Explorer 8, the Add Search Provider dialog box is displayed.

Making Search Provider Discoverable

The second way to promote a search provider is to make the search provider discoverable. The OpenSearch specification describes how to advertise search providers by adding a link element to the head of the Web page. The following code enables Internet Explorer 8 to discover your search provider.

<link title="My Provider" rel="search"

The rel attribute must be "search," and type must be "application/opensearchdescription+xml." The value of title is displayed in the Instant Search box drop-down menu. The href attribute contains an absolute or relative URL that specifies the location of the OpenSearch Description file.

When the page is loaded in Internet Explorer 8, the drop-down arrow on the Instant Search box turns orange to indicate that new search providers have been added to the drop-down menu. The three newest discoverable search providers are listed; these must be installed before additional providers can be included in the list. When the user browses to another domain, the previously discovered search providers are removed. Users can try out the new providers before adding them to their list. When a user decides to install a search provider, the Add Search Provider dialog box is displayed.

Offering Search Suggestions

Starting with Internet Explorer 8, the Instant Search box supports search suggestions. With search suggestions, as the user is typing in the search box, Internet Explorer 8 can send requests to your search provider with the current query string and you can supply suggestions which might enable the user to create a better search term. Internet Explorer 8 supports two search suggestions formats: JSON format and XML format. The JSON format enables text-based search suggestions that can be augmented with descriptions and URL. The XML format enables all the content available with JSON suggestions, and further support visual suggestions and section titles. More details on XML search suggestions format can be found from this article: XML Search Suggestions Format Specification.

Note  This section covers the formatting of individual suggestion responses only. To fully support search suggestions, you must generate these suggestions and provide the right suggestions at each request. Since this part of supported suggestions is unique to each provider, it is not addressed here.

Using JSON Suggestions Format

JSON search suggestions are returned as a Microsoft JScript array of arrays. The array contains four values:

Query string (required)The search term that was requested. If the browser requested suggestions for "xbox," then the query string is "xbox". Returning the query string in the array ensures that the returned suggestions are for the requested search term.
Completions array (required)The suggestions for the given query string.
Descriptions array (optional)Alternate strings that provide additional information or context about a given completion.
Query URLs array (optional)A list of URLs that should be used if the user selects a given suggestion. This acts as an instant answer to the search term by taking the user to the URL rather than a search results page.


A JSON response must return the query string and the search suggestions in the completions array. The following is an example of a simple JSON response where the descriptions and query URLs are omitted.

	["Xbox 360", "Xbox cheats", "Xbox 360 games"]]

Note  A maximum of ten search suggestions are displayed at a time. Adding descriptions, visuals, and sections limits the number of suggestions that can be provided. It is important to send the most relevant suggestions at the beginning of the completions array.

To help users create better search terms, descriptions can be offered along with the suggestions. A query URLs might be offered as a form of an instant answer. When a query URL is offered, and the user clicks on that suggestion, Internet Explorer 8 takes the user to that query URL directly rather than to a search results page. The following is an example of a detailed JSON response.

	["Xbox 360", "Xbox cheats", "Xbox 360 games"], 
	["The official Xbox website from Microsoft", "Codes and walkthroughs", "Games and accessories"],	
	["","", ""]]

In this JSON response, the first search suggestion consists of the following elements:

  • First element in the first array ("Xbox 360")
  • First element in the second array ("The official Xbox website from Microsoft")
  • First element in the third array ("").

The preceding response produces the following results:JSON search suggestions

Using XML Suggestions Format

The preceding JSON response can be represented in XML suggestions format, as shown in the following example. This example contains the same suggestions response as in the preceding JSON suggestions and produces the exact same result.

<?xml version="1.0"?>
<SearchSuggestion xmlns="">
		<Text>Xbox 360</Text>
		<Description>The official Xbox website from Microsoft</Description>
		<Text>Xbox cheats</Text>
		<Description>Codes and walkthroughs</Description>
		<Text>Xbox 360 games</Text>
		<Description>Games and accessories</Description>

The JSON suggestion format does not allow section titles to be specified in the suggestion menu. In Internet Explorer 8, the section title will be the name of your search provider plus the word "Suggestions." For example, if your search provider is named "Joe's Search," then your suggestions would be titled "Joe's Search Suggestions." In the following example, the search provider is named "My Custom Search" and the title is displayed as "My Custom Search Suggestions." If you want to organize your suggestions in multiple sections, use the XML suggestions format. In addition to section titles, the XML suggestions format supports visual suggestions. More details on XML search suggestions format can be found from this article: XML Search Suggestions Format Specification.

XML search suggestions support the same features as JSON search suggestions, and additional features that are not available in JSON. These additional features include the following:

  • Customizing the title of the suggestions section.
  • Splitting suggestions across multiple section separators.
  • Including visual suggestions.

To customize section titles, you can add a "title" attribute to the Section element, or you can add a Separator. Separators may or may not have a title. The following example adds a separator for "My Text Suggestions" and another separator without a title.

<?xml version="1.0"?>
<SearchSuggestion xmlns="">
	<Separator title="My Text Suggestions"/>
		<Text>Xbox 360</Text>
		<Description>The official Xbox website from Microsoft</Description>
		<Text>Xbox cheats</Text>
		<Description>Codes and walkthroughs</Description>
		<Text>Xbox 360 games</Text>
		<Description>Games and accessories</Description>
	<Separator />
		<Text>xbox 360 lowest price</Text>
		<Text>xbox 360 news</Text>

The code above produces the following result.XML search suggestions with custom title and section separators

Offering Visual Suggestions

Search suggestions generally consist of text suggestions or related terms that users might want to search for. In Internet Explorer 8, the concept of a search suggestion has been expanded to include a query string, a link, or a visual suggestion. A visual suggestion includes an image. Your search provider can supply an image with text or just an image as a search suggestion for the user's search term. To add a visual suggestion to your response, add an Image element to the Item element of that suggestion. Be sure to also specify the image's width and height dimentions. For example, to offer a visual suggestion for the term "Xbox," you might return the following:

 <Separator title="My Visual Suggestions" />
  	<Text>Xbox 360 Game Consoles</Text>
  	<Description>Game console systems and packages at a great deal.</Description>
  	<Image source="" alt="Xbox 360 Consoles" width="75" height="75"/> 
  	<Text>Xbox 360 Wireless Controller</Text> 
  	<Image source="" alt="Xbox 360 Wireless Controller" width="75" height="75"/> 
  	<Text>Xbox 360 Live Games</Text> 
  	<Image source="" alt="Xbox 360 Live Games" width="75" height="75"/> 
  	<Url>"Xbox 360"</Url> 

The preceding code produces the following results. Xbox visual suggestions

This example offers a URL with two of the suggestions. Internet Explorer 8 takes the user directly to the page specified by the URL. If URL is not offered, then the value of the Text element ("Xbox 360 Wireless Controller") is used as the search term. If you want to offer a visual suggestion with no Text or Description, you must offer a URL so Internet Explorer 8 knows where to send the user.

By default, if you include text with an image, the text is centered vertically next to the image. By setting the align attribute value to "top", "middle", or "bottom", you can specify the text alignment of the Text element and Description element relative to the image.

To align your text, add the align attribute to your image element. The example below sets the align attribute to "top".

<Image source="" alt="Xbox 360 Consoles" width="75" height="75" align="top"/> 

Handling Response Errors

When you offer search suggestions, chances are, there may be terms you may not have any suggestions for or you may not recognize the search term. In that case, you are still required to send back a valid XML response otherwise your users will get a message that says An error occurred. To avoid this message, send back a valid XML response when you have no suggestion for the search term. The code snippet below sends a response without any suggestion for the search term xbox. This response will show the No results. message.

<?xml version="1.0"?>
<SearchSuggestion xmlns="">

For a JSON respond, return the following:


Besides not having any suggestion for a search term, you might have cases where you know the suggestion exist but you are still getting the error message. In that case, check the request for encoding. By default, search terms are encoded using UTF-8 though the HTTP GET request method. That means if the user type in any accented characters, the characters are encoded to an ASCII (text) equivelent. For example, if your search term is café then the term that is send to you is q=caf%c3%a9 where the accented é has been encoded to an ASCII equivelent of %c3%a9.

Note  Search providers must use the HTTP GET request method; the POST request method is not supported.

Getting Dimensions for the Search Suggestions Menu

You should include the height and width of your image when you provide a visual suggestion. If you do not include these values, Internet Explorer 8 allocates a default space for the image and scales the image to fit within that space. The default amount of space, in this case, is the vertical equivalent of one line of text.

The Instant Search box can be resized, so the dimensions of the search suggestions drop-down menu may vary. To find out the dimensions of the search suggestions menu, you can add parameters to the OpenSearch Description URL that return the size of the search suggestions drop-down menu. Available parameters include the following.

{maxWidth}The width of the drop-down menu, in pixels.
{sectionHeight}The height of the entire suggestions section.
{rowHeight}The height of a single line of text, which is equivalent to one line of text.


The following example shows these parameters added to the URL of the OpenSearch Description file.

<Url type="application/x-suggestions+xml" 

The following picture identifies the area for each parameter.Search suggestions menu parameter

Identifying Search Referrers

Starting from Internet Explorer 7 the OpenSearch Referrer Extension is supported. When the user initiates a search, Internet Explorer adds a referrer attribute to the search query that indicates whether the search was initiated by the Instant Search box or by the Address bar. If the search was initiated by the Instant Search box, the referrer attribute is set to IE-SearchBox. If the search was initiated from the Address bar, either through a favorite or direct typing, the referrer attribute is set to IE-Address.

Localizing Search Suggestions

If you offer your services in multiple languages you can determine which localize suggestions to send by adding the "{Language}" attribute to your query string . The example below shows how to receive language information from the user to serve localize requests:

<Url type="application/x-suggestions+xml" 

When Internet Explorer requests suggestions, it will replace "{Language}" with the Internet Explorer accepted language that's defined on the user's system's locale. The user's system's locale can be set from the Control Panel and from language settings of Internet Explorer from the Internet Options dialog box.

Note  See the section on "Handling Response Errors" above for more information about character encoding that may affect your locale responses.


Keep the following guidelines in mind.

  • A Web site cannot automatically launch the Add Search Provider dialog box. It is locked down in the same way that a pop-up blocker locks down Web sites, and can only be launched as the direct result of a user action.
  • Titles should be short, ideally, 16 characters or less. This string is used by the Instant Search box. If the title is longer then the search box, it might be clipped.
  • The title in the link tag should be the same title used by the XML description file. These strings must match so that Search Discovery recognizes that a provider has been installed so that the Instant Search box drop-down arrow doesn't turn orange, or an installed provider doesn't add itself to the list of discovered providers.
  • When a user restores default Internet Explorer settings, all custom search providers are removed.
  • If you are using scripts to add aprovider, you may also want to call the IsSearchProviderInstalled helper method to check if your provider has already been installed.
  • When you create description files, make sure the file is of valid XML syntax and that all characters in your query strings are encoded and that all "&" characters are escaped to "&amp;".
  • Because users can resize the Instant Search box, you can query Internet Explorer 8 to return the search suggestions drop-down dimensions by adding parameters to the URL of your XML description file.

Related topics

XML Search Suggestions Format Specification
Installing a Search Provider and Setting the Default
Other Resources
Windows Search Guide
OpenSearch Description