Create Your Own Widgets

Creating Angular InstantSearch widgets is the third layer of our API. Read about the two others possibilities in the main concepts guide.

Introduction

You are trying to create your own widget with Angular InstantSearch and that’s awesome 🎉. But that also means that you could not find the widgets or built-in options you were looking for.
We’d love to hear about your use case as our mission with our InstantSearch libraries is to provide the best out-of-the-box experience. Don’t hesitate to send us a quick message explaining what you were trying to achieve either using the form at the end of that page or directly by submitting a feature request.

When do I need to create widgets?

By creating widgets we mean being able to create completely new widgets with completely new behaviors that are not today available in the existing widgets. Do not create new widgets if all you want is extending widgets like redefining the DOM of existing widgets.

This is a very advanced way to use the library, we advise you to only create new widgets when both using widgets and extending widgets have failed to answer your needs.

How to create a new widget

To create new widgets, the process is the same as for extending widgets, but instead of reusing an existing connector you would create your own connector.

The most simple connector starts with the following boilerplate.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const connector = (renderFn, unmountFn) => (widgetParams = {}) => ({
  init({ instantSearchInstance }) {
    renderFn(
      {
        /* anything you put here ends up in this.state */
      },
      true
    );
  },

  render({ results, instantSearchInstance }) {
    renderFn(
      {
        /* anything you put here ends up in this.state */
      },
      false
    );
  },

  dispose() {
    unmountFn();
  },
});

The best way to learn connectors is to look at some of those we have built, for example stats connector code in the InstantSearch.js project.

Head over to our community forum if you have more question about creating your own widget.