React InstantSearch 3.0.0

React InstantSearch 3.0.0

Today marks the relase of React InstantSearch 3.0.0 with many bugfixes and new features along
with a better documentation website.

In fact many features were silently released in 2.x.x versions so we summarize them here.

A new major version?

Your code should be working fine with React InstantSearch v3.0.0. We did a single
breaking change that is we do not automatically unmount widgets and connectors
when “we think they are no more relevant”.

Before v3.0.0 when RefinementList or connectRefinementList were used and had no more items in it
we were removing it from the DOM with render() { return null; }.
We stopped doing so to allow users to express things like “When my RefinementList is empty, I want to render the list with manual items”.

New features

withSearchBox (bool)

Since 2.2.0, passing withSearchBox (bool) prop to Menu or RefinementList will add a search box on
top of the widget.

It’s also available for your connected components as the searchForItems (function) provided prop
when using connectRefinementList or connectMenu.

This means that you might have to handle more cases on your side than before, but this will
also give you more flexibility than before.


We are now providing a Panel widget.
You can configure a title (string) and it has a default rendering. You can wrap any widget or connected
components and it will automatically add the necessary CSS class names.

.noRefinement {} and canRefine

Most of the widgets now implement the .ais-WidgetName__noRefinement {} CSS class name
as a way for you to easily change the display of widgets where no more refinements are available
for usage (example: empty refinement list).

The canRefine (bool) provided prop is available to your connected components to easily
know when you have to deal with non refinable filter (example: no available ranges for the current query).

<Configure distinct={1} />

<Configure /> is a new way to pass Algolia search parameters in React InstantSearch. It provides
a dynamic way (if you mount/unmount it) to configure any search parameter. It’s useful for cases like
geo search.

Read the search parameters guide to know more.


If you were already using searchForFacetValues (bool), we renamed it to withSearchBox (bool) props on Menu and RefinementList widgets.
We also renamed searchForFacetValues (function) to searchForItems (function) provided props in
connectRefinementList and connectMenu.

In React InstantSearch we try to avoid using the facet word on the user API because not everyone
knows what is a facet list while many people can understand what is a category menu.

Important bug fix

Many small bug fixes were done for specific cases, but there’s one that was pretty annoying: updating
props on the <InstantSearch> root component was not working (which is weird in the React world).

This is fixed and you can now update any property of the <InstantSearch> component like appId and it will update
it and trigger a new search. This is useful in situations where you want to change the index name
given some user cookies or any similar need given the user context.

What’s next?

We want to ease the implementation of autocomplete like interfaces with React InstantSearch and
will work on that in the coming weeks.

How can you help?

We definitely need and take all your feedback into account so please give it right on discourse or
on GitHub as soon as you think:

  • “Well, this is a weird behaviour”
  • “This is obviously not working”
  • “The provided API is wrong”

We know some people are in love with the current API but we also know it has caused headaches in
some situations.

In those situations, we can only help you if you give us feedback as soon as possible on GitHub or

Happy coding!


Configure is adding to the search state only after chaning other values. Ex: I pass in data to configure, onSearchStateChanged is not called. After changing the query then onSearchStateChanged is called with the configure options. This is problematic for me. If you add a bounding box it wont show up in the url. Also, setting the props to nothing doesn’t trigger a search state change either.

@development Have you implemented componentWillReceiveProps on the component that wraps InstantSearch? The method should parse the URL into a search state and then call setState to trigger a re-render and pass the updated state into the InstantSearch component. You can see this pattern in action in the react-router example.

@development Could you open a more detailed GitHub issue if you faced a bug in React InstantSearch? Thanks.

404 on “panel” link, I believe the correct link is:

1 Like

Its been sometime, I have looked into react-instantsearch. I will be upgrading and checking out the new features soon!