middleware

Adds custom logic to your React InstantSearch apps.

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.

Signature

function middleware({ instantSearchInstance }) {
  return {
    onStateChange({ uiState }) {},
    subscribe() {},
    unsubscribe() {},
  };
}

About this widget

The middleware function returns an object with onStateChange, subscribe, and unsubscribe functions.

The middleware function doesn’t perform any actions itself but lets you inject logic into InstantSearch.js, for example, sending events to Google Analytics. To send Algolia click and conversion events, use the insights middleware.

Requirements

• InstantSearch.js v4.8.3 or later.

Examples

JavaScript

function middleware({ instantSearchInstance }) {
  return {
    onStateChange({ uiState }) {
      // Do something with `uiState` every time the state changes.
    },
    subscribe() {
      // Do something when the InstantSearch instance starts.
    },
    unsubscribe() {
      // Do something when the InstantSearch instance is disposed of.
    },
  };
}

function Middleware() {
  const { addMiddlewares } = useInstantSearch();

  React.useLayoutEffect(() => {
    return addMiddlewares(middleware);
  }, [addMiddlewares]);
}

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

Options

instantSearchInstance · object · required

You have access to the instance of instantsearch which lets you read values from the instance or call instance methods like addWidgets, setUiState, and refresh.

JavaScript

function middleware({ instantSearchInstance }) {
  return {
    onStateChange({ uiState }) {
      // ...
    },
    subscribe() {
      // ...
    },
    unsubscribe() {
      // ...
    },
  };
}

Hooks

onStateChange · ({ uiState }) => void · required

The function is called with uiState whenever the state changes.

JavaScript

function middleware({ instantSearchInstance }) {
  return {
    // ...
    onStateChange({ uiState }) {
      const indexName = "<your-index-name>";
      const { query } = uiState[indexName];
      const title = document.querySelector("<your-selector>");
      title.innerText = query ? `Query: ${query}` : `No query`;
    },
  };
}

subscribe · () => void · required

This function is called when the InstantSearch instance starts (when search.start is called). This is where you can add event listeners, subscribe to an API, and run any side effects.

JavaScript

function middleware({ instantSearchInstance }) {
  let subscription;
  let listener;

  return {
    // ...
    subscribe() {
      subscription = someAPI.subscribe();

      listener = (event) => {
        // do something
      };
      document
        .querySelector("<your-selector>")
        .addEventListener("click", listener);
    },
  };
}

unsubscribe · () => void · required

The function is called when the InstantSearch instance is disposed of. You can clean up anything you initiated in the subscribe function.

JavaScript

function middleware({ instantSearchInstance }) {
  let subscription;
  let listener;

  return {
    // ...
    unsubscribe() {
      subscription.unsubscribe();

      document
        .querySelector("<your-selector>")
        .removeEventListener("click", listener);
    },
  };
}