Routing and URL syncing in React InstantSearch

How to synchronize your URLs with React InstantSearch.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Synchronizing your UI with the browser URL is considered good practice. It lets your users take one of your results pages, copy the URL, and share it. It also improves the user experience by enabling the use of the back and next browser buttons to keep track of previous searches.

InstantSearch provides the necessary API entries to let you synchronize the state of your search UI (your refined widgets and current ) with any kind of storage.

Use the routing option to synchronize UI state with the browser URL, so users can bookmark, share, and revisit the same search.

This guide covers enabling default routing, customizing URLs, and creating SEO-friendly URLs.

If you’re using server-side rendering, follow the server-side rendering guide. If you’re using Next.js, see createInstantSearchRouterNext.

Don’t configure initialUiState and routing together.

• Use initialUiState to set the UI state when the search first loads, such as for a default query or filter.
• Use routing to keep the UI state synchronized with the URL, so users can bookmark or share a search.

Default URLs

Set routing to true to use the default routing configuration: a history router with simple state mapping. This stores routing-compatible UI state in URL query parameters.

React

import { InstantSearch } from "react-instantsearch";
import { liteClient as algoliasearch } from "algoliasearch/lite";

const searchClient = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_SEARCH_API_KEY");

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={true}
    >
      {/* ... */}
    </InstantSearch>
  );
}

Setting routing to true is equivalent to this configuration:

React

import { InstantSearch } from "react-instantsearch";
import { history } from "instantsearch.js/es/lib/routers";
import { simple } from "instantsearch.js/es/lib/stateMappings";
import { liteClient as algoliasearch } from "algoliasearch/lite";

const searchClient = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_SEARCH_API_KEY");

const routing = {
  router: history(),
  stateMapping: simple(),
};

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={routing}
    >
      {/* ... */}
    </InstantSearch>
  );
}

Assume the following search UI state:

• Query: “galaxy”

• Menu:

  • categories: “Cell Phones”

• Refinement List:

  • brand: “Apple”, “Samsung”

• Page: 2

This produces the following URL:

https://example.org/?instant_search[query]=galaxy&instant_search[menu][categories]=Cell Phones&instant_search[refinementList][brand][0]=Apple&instant_search[refinementList][brand][0]=Samsung&instant_search[page]=2

By default, routing includes state from routing-compatible widgets. With many widgets, this can create long URLs. To create shorter or more descriptive URLs, customize the URL routing.

Customize URL routing

You can customize which values appear and rename the URL parameters.

The stateMapping option maps between InstantSearch’s uiState and the routeState used by the router. Use it to rename parameters or omit values that you don’t want to include in the URL.

React

import { InstantSearch } from "react-instantsearch";
import { history } from "instantsearch.js/es/lib/routers";
import { liteClient as algoliasearch } from "algoliasearch/lite";

const searchClient = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_SEARCH_API_KEY");

const routing = {
  router: history(),
  stateMapping: {
    stateToRoute(uiState) {
      // ...
    },
    routeToState(routeState) {
      // ...
    },
  },
};

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={routing}
    >
      {/* ... */}
    </InstantSearch>
  );
}

InstantSearch stores widget state in uiState. The following example maps that state to shorter URL parameters.

The state contains information about the user’s search, including the query, the selection, the page being viewed, and the widget hierarchy. uiState only stores modified widget values, not defaults.

To persist this state in the URL, InstantSearch converts the uiState into an object called routeState: this routeState then becomes a URL. Conversely, when InstantSearch reads the URL and applies it to the search, it converts routeState into uiState. This logic lives in two functions:

• stateToRoute: converts uiState to routeState.
• routeToState: converts routeState to uiState.

Assume the following search UI state:

• Query: “galaxy”

• Menu:

  • categories: “Cell Phones”

• Refinement List:

  • brand: “Apple” and “Samsung”

• Page: 2

This translates into the following uiState:

JSON

{
  "indexName": {
    "query": "galaxy",
    "menu": {
      "categories": "Cell Phones"
    },
    "refinementList": {
      "brand": ["Apple", "Samsung"]
    },
    "page": 2
  }
}

Implement stateToRoute to flatten this object into a URL, and routeToState to restore the URL into a UI state:

React

import { InstantSearch } from "react-instantsearch";
import { history } from "instantsearch.js/es/lib/routers";
import { liteClient as algoliasearch } from "algoliasearch/lite";

const searchClient = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_SEARCH_API_KEY");

const indexName = "instant_search";

const routing = {
  router: history(),
  stateMapping: {
    stateToRoute(uiState) {
      const indexUiState = uiState[indexName];
      return {
        q: indexUiState.query,
        categories: indexUiState.menu?.categories,
        brand: indexUiState.refinementList?.brand,
        page: indexUiState.page,
      };
    },
    routeToState(routeState) {
      return {
        [indexName]: {
          query: routeState.q,
          menu: {
            categories: routeState.categories,
          },
          refinementList: {
            brand: routeState.brand,
          },
          page: routeState.page,
        },
      };
    },
  },
};

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName={indexName}
      routing={routing}
    >
      {/* ... */}
    </InstantSearch>
  );
}

SEO-friendly URLs

To create more descriptive URLs, move search state from query parameters into the URL path. This is a common pattern for ecommerce category and search pages.

https://example.org/search/Cell+Phones/?query=galaxy&page=2&brands=Apple&brands=Samsung

Store categories in the URL path

This example stores the category in the path and the query, page, and brands as query parameters.

React

import { InstantSearch } from "react-instantsearch";
import { history } from "instantsearch.js/es/lib/routers";
import { liteClient as algoliasearch } from "algoliasearch/lite";

const searchClient = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_SEARCH_API_KEY");

// Convert a category name to a URL slug.
// Replace spaces with "+" and encode other characters.
function getCategorySlug(name) {
  return name.split(" ").map(encodeURIComponent).join("+");
}

// Convert a category slug to a category name.
// Replace "+" with spaces and decode other characters.
function getCategoryName(slug) {
  return slug.split("+").map(decodeURIComponent).join(" ");
}

const routing = {
  router: history({
    windowTitle({ category, query }) {
      const queryTitle = query ? `Results for "${query}"` : "Search";

      if (category) {
        return `${category} – ${queryTitle}`;
      }

      return queryTitle;
    },

    createURL({ qsModule, routeState, location }) {
      const urlParts = location.href.match(/^(.*?)\/search/);
      const baseUrl = `${urlParts ? urlParts[1] : ""}/`;

      const categoryPath = routeState.category
        ? `${getCategorySlug(routeState.category)}/`
        : "";
      const queryParameters = {};

      if (routeState.query) {
        queryParameters.query = encodeURIComponent(routeState.query);
      }
      if (routeState.page !== 1) {
        queryParameters.page = routeState.page;
      }
      if (routeState.brands) {
        queryParameters.brands = routeState.brands.map(encodeURIComponent);
      }

      const queryString = qsModule.stringify(queryParameters, {
        addQueryPrefix: true,
        arrayFormat: "repeat",
      });

      return `${baseUrl}search/${categoryPath}${queryString}`;
    },

    parseURL({ qsModule, location }) {
      const pathnameMatches = location.pathname.match(/search\/(.*?)\/?$/);
      const category = getCategoryName(pathnameMatches?.[1] || "");
      const {
        query = "",
        page,
        brands = [],
      } = qsModule.parse(location.search.slice(1));
      // `qs` does not return an array when there's a single value.
      const allBrands = Array.isArray(brands)
        ? brands
        : [brands].filter(Boolean);

      return {
        query: decodeURIComponent(query),
        page,
        brands: allBrands.map(decodeURIComponent),
        category,
      };
    },
  }),

  stateMapping: {
    stateToRoute(uiState) {
      const indexUiState = uiState["instant_search"] || {};

      return {
        query: indexUiState.query,
        page: indexUiState.page,
        brands: indexUiState.refinementList?.brand,
        category: indexUiState.menu?.categories,
      };
    },

    routeToState(routeState) {
      return {
        instant_search: {
          query: routeState.query,
          page: routeState.page,
          menu: {
            categories: routeState.category,
          },
          refinementList: {
            brand: routeState.brands,
          },
        },
      };
    },
  },
};

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName={indexName}
      routing={routing}
    >
      {/* ... */}
    </InstantSearch>
  );
}

This example configures the default history router. The router reads and writes URLs, while stateMapping maps uiState to routeState and back.

When you configure the history router, you can customize these functions:

• windowTitle: returns the browser window title for a routeState.
• createURL: creates a URL from routeState. InstantSearch calls it when synchronizing the browser URL, rendering links in the menu widget, or when a connector calls createURL.
• parseURL: creates routeState from the URL when users load or reload the page or use the browser’s back or forward navigation.

Make URLs more discoverable

Shorter category URLs can be more readable and memorable. Use a mapping object to map category names to shorter URL slugs.

Given the dataset in this guide, you can make some categories more discoverable:

• “Cameras and camcorders” → /Cameras
• “Car electronics and GPS” → /Cars

When users open https://example.org/search/Cameras, InstantSearch selects the “Cameras and camcorders” category.

Define mappings between category names and URL slugs:

JavaScript

// Map URL slugs to category names.
const encodedCategories = {
  Cameras: "Cameras and camcorders",
  Cars: "Car electronics and GPS",
  Phones: "Phones",
  TV: "TV and home theater",
};

// Map category names to URL slugs.
const decodedCategories = Object.keys(encodedCategories).reduce((acc, key) => {
  const newKey = encodedCategories[key];
  const newValue = key;

  return {
    ...acc,
    [newKey]: newValue,
  };
}, {});

// Use the mappings when converting category names and slugs.
function getCategorySlug(name) {
  const encodedName = decodedCategories[name] || name;

  return encodedName.split(" ").map(encodeURIComponent).join("+");
}

function getCategoryName(slug) {
  const decodedSlug = encodedCategories[slug] || slug;

  return decodedSlug.split("+").map(decodeURIComponent).join(" ");
}

You can build these dictionaries from your Algolia .

With such a solution, you have full control over what categories are discoverable from the URL.

About SEO

For your search results to be part of a public search engine’s results, you must be selective. Trying to index too many search results pages could be considered spam.

To do that, create a robots.txt and host it at https://example.org/robots.txt.

Here’s an example based on the URL scheme you created.

robots.txt

User-agent: *
Allow: /search/Audio/
Allow: /search/Phones/
Disallow: /search/
Allow: *

Basic routing demo

Explore basic InstantSearch routing in CodeSandbox.

SEO-friendly routing demo

Explore SEO-friendly routing in CodeSandbox.