🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / React InstantSearch / Widgets

middleware

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.

Signature 
function middleware({ instantSearchInstance }) {
  return {
    onStateChange({ uiState }) {},
    subscribe() {},
    unsubscribe() {}
  }
}
See code examples

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 allows you to inject functionality into InstantSearch.js:

Requirements

InstantSearch.js v4.8.3 or later.

Examples

Copy 
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

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

Parameter Description
instantSearchInstance
type: 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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

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

Hooks

Parameter Description
onStateChange
type: ({ uiState }) => void
Required

The function is called with uiState whenever the state changes.
Copy 
1
2
3
4
5
6
7
8
9
10
11

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
type: () => 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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

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

      listener = (event) => {
        // do something
      }
      document.querySelector('<your-selector>').addEventListener('click', listener);
    },
  }
}
unsubscribe
type: () => void
Required

The function is called when the InstantSearch instance is disposed of. You can clean up anything you initiated in the subscribe function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

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

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

      document.querySelector('<your-selector>').removeEventListener('click', listener);
    },
  }
}
Did you find this page helpful?
React InstantSearch v7