createRedirectUrlPlugin

The Redirect URL plugin lets you redirect your Autocomplete results to a specified URL.

The Redirect URL plugin lets you redirect your Autocomplete results to a specified URL.

Redirection works automatically with Algolia Rules with redirect consequences. You can customize this plugin to work with other sources.

Installation

First, install the plugin:

npm

npm install @algolia/autocomplete-plugin-redirect-url

Import it in your project:

JavaScript

import { createRedirectUrlPlugin } from "@algolia/autocomplete-plugin-redirect-url";

Add a CSS theme:

JavaScript

import "@algolia/autocomplete-theme-classic";

The theme is compatible with the autocomplete-theme-classic package.

If you don’t use a package manager, add the following script elements to your HTML:

HTML

<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-redirect-url@1.19.4/dist/umd/index.production.js"
  integrity="qPFIZt5R/aIZRfbsjbVqfEgp3NvSPywPmYS/F84JXSo="
  crossorigin="anonymous"
></script>
<script>
  const { createRedirectUrlPlugin } =
    window["@algolia/autocomplete-plugin-redirect-url"];
</script>

Examples

JavaScript

import { autocomplete, getAlgoliaResults } from "@algolia/autocomplete-js";
import { createRedirectUrlPlugin } from "@algolia/autocomplete-plugin-redirect-url";
import { liteClient as algoliasearch } from "algoliasearch/lite";

import "@algolia/autocomplete-theme-classic";

const appId = "latency";
const apiKey = "6be0576ff61c053d5f9a3225e2a90f76";
const searchClient = algoliasearch(appId, apiKey);

const redirectUrlPlugin = createRedirectUrlPlugin();

autocomplete({
  container: "#autocomplete",
  placeholder: "Search",
  openOnFocus: true,
  plugins: [redirectUrlPlugin],
  getSources({ query }) {
    return [
      {
        sourceId: "products",
        templates: {
          item(params) {
            const { item, html } = params;

            return html`<a class="aa-ItemLink">${item.name}</a>`;
          },
        },
        getItemInputValue({ item }) {
          return item.name;
        },
        getItems() {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: "instant_search",
                query,
                // note: these params are optional and relevant to the source and data used for this demo
                params: {
                  ruleContexts: ["enable-redirect-url"], // triggers rules configured only with this context
                  hitsPerPage: 10, // prevents the dropdown from displaying too many items
                },
              },
            ],
          });
        },
      },
    ];
  },
});

The Redirect URL plugin is initialized with the createRedirectUrlPlugin function. This will handle all Algolia rules that have redirect consequences without the need for any extra configuration. Note that this plugin requires a source to be provided to autocomplete with the sourceId, templates, getItemInputValue, and getItems parameters to work.

By default, redirect data is mapped to response.renderingContent?.redirect?.url from Algolia’s response. If you’ve defined redirects differently in your Rules, you can change the mapping with the transformResponse parameter.

Redirects are stored into the state’s context with the following form:

JavaScript

{
  data: [{ sourceId: "my-source", urls: ["https://www.algolia.com"] }];
}

If your autocomplete source is configured with multiple sources and there are redirects triggered on both for the current query then state.context.redirectUrlPlugin will look like:

JavaScript

{
  data: [
    { sourceId: "my-source-1", urls: ["https://www.algolia.com"] },
    { sourceId: "my-source-2", urls: ["https://www.algolia.com/hello-world"] },
  ];
}

Notice data now has two items in the array, which correspond to each source. Each entry has the sourceId provided to maintain that mapping. If you have two sources and one of them lacks a redirect, then note that rather than be listed with an empty urls array, it will not be listed in state.context.redirectUrlPlugin at all.

If you go a step further and have multiple sources configured with multiple queries, and redirects are found for each, then state.context.redirectUrlPlugin may now look like:

JavaScript

{
  data: [
    { sourceId: "my-source-with-one-query", urls: ["https://www.algolia.com"] },
    {
      sourceId: "my-source-with-two-queries",
      urls: ["https://www.algolia.com", "https://www.algolia.com/hello-world"],
    },
  ];
}

Notice in the preceding example that there are still two entries. However, in the second source, there are two redirect objects in the urls array. These correspond to two queries that were made in the source configuration.

The second parameter provides access to the following properties, { event, navigator, state }. navigator handles the actual redirection with the provided URL. For more information, see Integrating keyboard navigation.

Redirects are triggered when users either submits the form or selects the redirect item from the drop-down menu. By default, the first possible redirect is chosen (the first source in state.context.redirectUrlPlugin.data and its first URL), but this behavior can be overridden with the onRedirect parameter. This callback function gets passed the values directly from state.context.redirectUrlPlugin.data.

Parameters

onRedirect · (redirects: RedirectUrlItem[], options: OnRedirectOptions<RedirectUrlItem>) => void

The function that runs when triggering a redirect—either when submitting the form or when selecting an item.

By default, the first redirect URL is used. When a search might trigger a redirect from multiple sources, you can use onRedirect to control which redirect URL to use.

JavaScript

const redirectUrlPlugin = createRedirectUrlPlugin({
  onRedirect(redirects, { event, navigator, state }) {
    const item = redirects.find(({ sourceId }) => sourceId === "my-source");

    const itemUrl = item?.urls?.find((url) =>
      url.startsWith("https://www.algolia.com"),
    );

    if (!itemUrl) {
      return;
    }

    if (event.metaKey || event.ctrlKey) {
      navigator.navigateNewTab({ itemUrl, item, state });
    } else if (event.shiftKey) {
      navigator.navigateNewWindow({ itemUrl, item, state });
    } else {
      navigator.navigate({ itemUrl, item, state });
    }
  },
});

transformResponse · (response: TransformResponseParams<TItem>) => string | undefined

A callback function for mapping a response to a redirect URL.

• This is useful if you have a non-Algolia source.
• Can be used with Algolia sources as well if using custom user data instead of a redirect consequence.
• Gets passed the redirect data this plugin processes and stores in state.context.redirectUrlPlugin.data.
• Overrides mapping the redirect URL provided from a rule with a redirect consequence.

JavaScript

const redirectUrlPlugin = createRedirectUrlPlugin({
  transformResponse(response) {
    return response.myRedirectData?.url;
  },
});

templates · SourceTemplates<RedirectUrlItem>

Change the default template for rendering redirect items.

JavaScript

const redirectUrlPlugin = createRedirectUrlPlugin({
  templates: {
    item({ html, state }) {
      return html`<a className="myCustomClass">${state.query}</a>`;
    },
  },
});