Today we are launching react-instantsearch, a new library to build search interfaces with Algolia in React and React native. This new way of implementing Algolia brings ideas that go beyond the creation of widgets using React – we think they will fundamentally influence the way the JS community builds UI libraries!

A year ago we launched instantsearch.js, in order to provide an easy solution for building search interfaces The project now has more than 1000 stars on github and 1500 users, far exceeding our expectations. With the release of instantsearch.js, we tried to help front-end engineers as much as possible and because the framework war was roaring hard back then, we went for the universal choice: Vanilla JS.

It was our first take at building a complete widget library for building search UI’s. With it, we tackled the problems that our users found when building a search interface, namely the lack of packaged options for search UX patterns, and the cumbersome mapping of concepts from the search realm to the UI realm.

To tackle those issues, we took the vanilla JS / framework “agnostic” approach. We created a light framework to be able to consolidate all the search parameters that each widget can set. Our final product was a drop-in search addon for all JS front-ends; however, this light framework is nothing without the widgets that are included. Each of them provides options to customise the search behavior and also their UI – it turns out, you can never provide enough options for UI and behavior.

“You can never provide enough options”

We started with fixed markup, but this was not enough because you might want to use a specific CSS library with its own markup. So we added the ability to customize some parts of the UI with templates, but this wasn’t enough because users wanted customization across the board. We added the possibility to manipulate bigger chunks of the UI, but this created inconsistencies with our own expectations for the markup which led to more options… in the end, the more options you provide, the more complexity you create.

Complexity has two faces. First, it makes it harder to deal with inconsistencies and bugs. Second, it creates API noise. Dealing with inconsistencies and bugs is hard but it’s always a matter of how much you work on it, and eventually it’ll be fixed. On the other hand, the more options you have, the harder it will be to grasp what are the important or critical options. The amount of options creates an artificial sense of complexity, users get the impression that the learning curve is steep. They had to dig through all the options to find the one they need.

Overall the API created for supporting UI options made the library harder to learn and use, and therefore the developer experience suffered from it.

We began to wonder ”What if we could separate the two, and provide options that are only meaningful for the search and limit the UI options?” – this is how react-instantsearch was born.

Decouple search logic from rendering

From the outside, react-instantsearch shares the same philosophy as instantsearch.js. It provides widgets, and each will handle a single part of the search UI. The combination of widgets makes up a search query to Algolia, which in turn updates the UI with new results, which in turn allows the user to further refine the search. Unlike its cousin, however, react-instantsearch handles customization by giving developers complete control over the rendering – the result is worth taking a look at:

react-instantsearch is made of a root component <InstantSearch> and other UI components that we call widgets. These widgets are the composition of a dumb react component with a business logic counterpart called connectors.

And this is where the true originality of react-instantsearch is.

Connectors are higher order components that provides a dual API. For the wrapped component, it exposes the minimal API necessary to let it do what it is supposed to do: set and read the query if it’s a SearchBox, or set filters and get the filter values if it’s a RefinementList. For example, a minimalist implementation of a custom SearchBox would be:

The connector also provides an external API that let the developer set the search settings relevant to the concerned domain. For example, the `hitsPerPage` parameter is set on the Hits widget but is used by the connector to set the number of results to display on a single page.

Now we have a clear and powerful API that provides all manners of customization for developers, and at the same time we can provide ready-to-use widgets that have limited options for UI tweaks. Our widgets are the results of our collective experience with search UX and what we’ve learned from users.

The end result is that beginner users are not left wondering what kind of experience they should implement, while experienced developers can adapt their search experience accordingly. Developers looking for a quick & powerful solution will find exactly that with react-instantsearch – the deeper they dive, the more they will uncover its flexible underbelly by overriding the defaults we provide .

react-instantsearch is a dual-faceted API:

• Opinionated widgets that represent our vision of a good search UX. They have fewer options and therefore provide a faster execution
• Customizable Connectors HOC’s which are UI-free, allowing you to fully adapt them to your desired search experience.

A glimpse of the future for service based UI’s

Algolia is, at its core, a search engine. UI&UX are very important elements that make for a great implementation and differentiate an unused search bar from a central navigation tool. Those improvements are very prominent when binding the search capabilities of an engine to the UI.

This new “flavor” of instantsearch provides more for the UI by channeling the capabilities of the search into abstract widgets. We provide our way of doing those implementations, but we also let you implement new UI widgets through the prism of our experience on how to use our engine.

If you want to have a look at what the next version of instantsearch.js will look like, try react-instantsearch and let us know if we have the right balance of feature and customization (on twitter, gitter or by email).

As a final word, we would like to express our sincerest gratitude to Alexandre Kirszenberg who built the initial POC during his summer internship. Thanks!!!