The guiding principles of InstantSearch

Sep 27th 2023product

Back in November 2015, we released the first full version of InstantSearch. We’ve received tons of feedback, leading to over 11,000 commits and 3,300 stars on GitHub as we continually refine this library. Now that we’re on v4, we figured this would be a good time to jot down the thought process behind problem-solving with InstantSearch.

We’ll keep this short, so it’ll be a good resource for you to come back to, but the gist is that whenever you need to tackle adding a new feature with InstantSearch, you’ll follow these three steps:

Making good use of premade widgets

Right out of the box, InstantSearch comes loaded with tons of interesting widgets that incorporate nearly every functionality Algolia offers. Almost anything you’d want to build in a typical search interface can be constructed by piecing together these widgets like Lego.

Take a look at this showcase for a good example of how they can be pieced together.

Here’s a good example of our friends at Starschema putting this into action. Before doing anything else, their engineer Soma was able to plan out the entire UI with a simple wireframe, knowing that Algolia’s widgets would fill in the rest. Steps 3.1 to 3.8 show the premade widgets that he chose to include and how he went about implementing them.

There’s more detail in the article, but the gist of it is that you call the addWidgets function on the InstantSearch object, passing it an array of widget objects.

Extending the premade widgets to include custom functionality

To continue the Lego illustration, there’s only so much you can build with the basic blocks. To build something truly interesting, realistic, or complicated, you’d need to start experimenting with colors and dimensions and connection points. Most times, it wouldn’t make sense to design a completely new brick, but to modify an existing one to fit.

That’s the same approach we take with InstantSearch widgets: before jumping all the way to building a new widget, we try to modify an existing one to do what we’re looking for.

This is the guide to customizing an existing widget. It involves hijacking just part of the widget to add some new functionality while not getting rid of what makes InstantSearch so valuable. You could edit just the logic part by creating a connector, or just the textual part for translation purposes, or just the styles to make the widget look different, among other things.

The widgets are made up of their renderer (for styles and markup) and their connector (for logic), and there are myriad ways to mess with either of those.

Building new widgets from scratch into InstantSearch

But say you’re looking for something so radical that there’s no clear path of modifications you can make to get from an existing widget to what you want. Your only way forward is to create your own new widget from scratch.

Like we mentioned, a widget is formed by a renderer (for styles and markup) and a connector (for logic) working together, so to make your own widget, you just need to create those two subcomponents. There’s an excellent guide on that here. 

With these steps, you can build almost anything with InstantSearch, even non-Algolia functionality. We’ve experimented with this process a lot here on the blog and with our customers, and every time it’s proved to be a very flexible and powerful system that gives you a lot of options without being a burden for more straightforward implementations.

We promised we’d keep this short, so if you’ve got any more questions, feel free to ping us on Discourse. Happy building!