API Reference / React InstantSearch Hooks / middleware

middleware

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

About this widget

Middleware is a function returning an object with onStateChange, subscribe and unsubscribe functions. With the middleware API, you can inject functionalities in the InstantSearch.js lifecycle.

Requirements

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.
    }
  }
}

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

  React.useLayoutEffect(() => {
    return use(middleware);
  });
}

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

Options

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

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

The function called with uiState every time 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

The function called when the InstantSearch instance starts, i.e., when search.start() is called. You can add event listeners, subscribe to an API, run any side effects here.
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 called when the InstantSearch instance is disposed. 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 Hooks v6