Redirects in 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.

Redirects can enhance the search experience. For example:

• Searching for “help” redirects users to a support page
• Searching for a category, such as, “TV” redirects users to a category page
• Searching for a specific product or brand redirects users to a seasonal promotional page for it
• Searching for specific keywords related to an ongoing event, such as, “masks”, redirects users to a more specific landing page

This guide explains how to add redirects to InstantSearch through Rules and using custom data.

Redirects are handled by Autocomplete’s redirect plugin. However, if you don’t use Autocomplete, you must handle redirects in InstantSearch:

• If a redirect was created in the Manual Editor, handle it with InstantSearch’s queryRuleCustomData widget.
• If a redirect was created in the Visual Editor, you must create a custom InstantSearch widget to handle redirects.

Handle a Visual Editor rule redirect

Configure the redirect with a custom widget

If a redirect was created in the Visual Editor, the API response contains the renderingContent.redirect property which, in turn, contains the redirect URL. To access this property from InstantSearch, you must create a custom widget.

Custom widgets have lifecycle hooks for each of the widget stages: init, render, and dispose. The render stage runs when Algolia sends results: in other words, when a user types something.

Use it as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
search.addWidgets([
  {
    render({ results }) {
      if (
        results &&
        results.renderingContent &&
        results.renderingContent.redirect
      ) {
        window.location.href = results.renderingContent.redirect.url;
      }
    },
  }
]);

Handle a Manual Editor rule redirect

If a redirect was created in the Manual Editor, handle it with InstantSearch’s <QueryRulesCustomData> widget.

Configure a rule

To set up a rule that returns custom data whenever the query matches specific keywords, see Create a rule for returning custom data.

Configure the queryRuleCustomData widget

After setting up a rule that returns the custom redirect data, you can use the <QueryRulesCustomData> widget to update the page location when userData contains a redirect.

1
2
3
4
5
6
7
8
9
10
import { useQueryRules } from 'react-instantsearch';

function Redirect() {
  const { items } = useQueryRules();
  const match = items.find(data => Boolean(data.redirect));
  if (match && match.redirect) {
    window.location.href = match.redirect;
  }
  return null;
}

Offer a suggested redirect rather than a hard redirect

The preceding is an example of a “hard redirect”, which forces users to a specific URL. This works in most situations, but sometimes you might want to suggest a redirect URL rather than force it onto them.

To do this, create the rule similarly but distinguish between “hard” and “suggested” redirects by ensuring the returned data is a JSON object. The object’s properties are:

• name (used to display the link)
• URL
• force (true for a hard redirect, false for a suggested redirect).

1
2
3
4
5
6
7
  { 
    "redirect": {
      "name": "help",
      "url": "https://www.algolia.com/support",
      "force": true
    }
  }

With this change applied, the <QueryRulesCustomData> widget that had been previously defined needs updating to decide what happens to a user based upon the returned data.

To do this, the redirect check (within transformItems) needs updating to decide whether to force the redirect onto users or not. The default template also needs setting to display a user message with the specific redirect URL.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
  search.addWidgets([
  instantsearch.widgets.queryRuleCustomData({
    container: '#queryRuleCustomData', 
    templates: {
-      default: '',
+      default({ items }, { html }) {
+        const customData = items.find(data => Boolean(data.redirect));
+
+        if (!customData) {
+          return null;
+        }
+
+        return html`
+          <div>
+            <a href="${customData.redirect.url}">
+              Click to view more on: '${customData.redirect.name}'
+            </a>
+          </div>
+       `;
+     },  
    },
    transformItems(items) {
      const match = items.find(data => Boolean(data.redirect));
-      if (match && match.redirect) {
+      if (match && match.redirect && match.redirect.force) {
        window.location.href = match.redirect;
+       return [];
      }

-      return [];
+      return items;
    },
  })
]);