Guides / Building Search UI / UI & UX patterns

Implement the OpenSearch protocol with React InstantSearch

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

This page describes how to implement the OpenSearch protocol with React InstantSearch.

This is a separate project and unrelated to AWS OpenSearch.

The OpenSearch protocol lets you describe a search engine for your website, so that browsers or other search clients can use that search engine.

How OpenSearch works

In your website or web application, you include a link to an OpenSearch description document. In this document, you describe how browsers can interact with an underlying search engine. This interaction is based on URL templates, for example,{searchTerms}, which tell browsers how to make search requests.

Since the interaction between the browser and search engine is based on a URL, you need to enable URL synchronization.

Create an OpenSearch description document

The OpenSearch description document is an XML file following the OpenSearch specification.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="">
  <ShortName>Example Web Search</ShortName>
  <Description>Search content.</Description>
  <Url type="text/html" method="get" template="{searchTerms}"/>
  <Image height="32" width="32"type="image/png">linkToImage</Image>

To adapt this example to your website, update these parts:

  • <ShortName> is the name of your app or website search. It must be 16 or fewer characters.
  • <Description> is a human readable description of your search engine. It must be 1024 or fewer characters.
  • <Url> has the template attribute, that browsers use to create the URL to your search engine.
  • <Image> has a URL (linkToImage) to a PNG image that represents your website, for example, the favicon.

The XML document must be served with Content-Type: application/opensearchdescription+xml media type.

For more information, see OpenSearch description elements.

Include the OpenSearch description document in your website

You can reference the XML document in the <head> of your web pages:


For more information, see Autodiscovery in HTML

Did you find this page helpful?