API Reference / InstantSearch.js / middleware

middleware

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

const search = instantsearch({
  // ...
})

search.use(middleware);
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

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

// Declare your instantSearch instance normally
const search = instantsearch({
  // ...
})

// Use your middleware function
search.use(middleware);

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?
InstantSearch.js v4