Skip to content

Instantly share code, notes, and snippets.

What would you like to do?

Hi react-instantsearch alpha beta testers! (Yes we are now beta!)

With this new release we are nearing a stable code state. Our vision is now to provide default widgets with a better styling and connectors to implement your own DOM or any advanced use case.

We wanted to reduce our API surface by removing options, widgets and focusing on what's currently used. While leaving the door open to adjustements and additions in the future, instead of deletions.

We now that we are yet not covering all usecases and we will work on that right after this release.


Export strategy

To allow future react-native, server use cases and avoid importing the full widgets code when you only use connectors, we changed our export strategy.

You should now use:

import {InstantSearch, SearchBox} from 'react-instantsearch/dom'; // widgets
import {connectRefinementList} from 'react-instantsearch/connectors'; // connectors
import {createConnector} from 'react-instantsearch'; // low level/utils

Removed widgets and connectors

We removed some widgets and connectors:

  • Loading, Loading.connect, Error, Error.connect, NoResults, NoResults.connect, EmptyQuery, EmptyQuery.connect now doable via simple custom widgets
  • Range.Slider, there are a lot of already very good Sliders, linking one to react-instantsearch is simple.
  • SortByLinks, RefinementListLinks, MenuSelect, if a different markup that the default one is needed use the connector

Updated widgets

We updated some widgets:

  • There's now a ClearAll widget
  • There's no more "Clear all" button in the CurrentFilters, use the ClearAll widget
  • HitsPerPageSelect was renamed to HitsPerPage. Also the old HitsPerPage was removed

Connector API

We tried to stick to a very simple interface that has almost no difference between connectors so that you never ask yourself too much how to access data or refine values.

Forwarded props

Every connector now forward those props:

  • refine() method to refine the widget
  • items (when relevant: in list of refinements)
  • items[].value to be passed to refine() method
  • items[].label to be displayed as the value textual representation
  • items[].isRefined if the current element is refined (selected)
  • currentRefinement (could be the current page or the currently selected values of a RefinementList)

We removed those forwarded props:

  • selectedItem, selectedItems, selectedIndex, hitsPerPage, page. You can now always use either items[].isRefined or currentRefinement

Exposed props

Every connector now exposes those props:

  • defaultRefinement to preconfigure the refinement handled by the connector

We removed those props:

  • defaultSelectedIndex, defaultRefinement, defaultSelectedItems, defaultHitsPerPage. You can now always use defaultRefinement

List of values

Connectors exposing list of values to be displayed will now always forward an items props. Previously those list of values could be given in different ways (items, filters, ..).


There's no more theme prop available on our widgets.

The only API available for styling is now regular CSS class names (BEM style). We first tried to use and provide but it was too broad as an API layer. Too many options.

We want to see how only CSS class names will go and ultimately how companies like Facebook are gonna solve (or maybe not solve) the theming issues within reusable libraries.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment