⚡️ Lightning-fast search for React and React Native applications, by Algolia.

Overview

React InstantSearch

React InstantSearch is a library for building blazing fast search-as-you-type search UIs with Algolia.


Version Build Status License Downloads

React InstantSearch is a React library that lets you create an instant-search result experience using Algolia’s search API. It is part of the InstantSearch family:

React InstantSearch | InstantSearch.js | Angular InstantSearch | Vue InstantSearch | InstantSearch Android | InstantSearch iOS

Why

You should be using React InstantSearch if you want to:

  • Design search experiences with best practices
  • Customize your components at will
  • Follow React principles

Installation

React InstantSearch is available on the npm registry. It relies on algoliasearch to communicate with Algolia APIs.

yarn add react-instantsearch-dom algoliasearch
# or
npm install react-instantsearch-dom algoliasearch

Getting started

Using React InstantSearch is as simple as adding these components to your app:

import React from 'react';
import ReactDOM from 'react-dom';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch-dom';

const searchClient = algoliasearch(
  'latency',
  '6be0576ff61c053d5f9a3225e2a90f76'
);

const App = () => (
  <InstantSearch
    indexName="bestbuy"
    searchClient={searchClient}
  >
    <SearchBox />
    <Hits />
  </InstantSearch>
);

Edit on CodeSandbox

To learn more about the library, follow the getting started guide.

Documentation

The documentation is available on algolia.com/doc.

Demos

E-commerce Media Travel
E-commerce demo preview Media demo preview Tourism demo preview

See more examples on the website.

Playground

You can get to know React InstantSearch on this playground.

Start by adding components and tweaking the display. Once you get more familiar with the library, you can learn more advanced concepts in our guides.

Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our FAQ where you will find answers for the most common issues and gotchas with the library.

Contributing

We welcome all contributors, from casual to regular. You are only one command away to start the developer environment, read our CONTRIBUTING guide.

License

React InstantSearch is MIT licensed.

Comments
  • Add react hooks

    Add react hooks

    Problem:

    Connector HOCs add boilerplate and can be unwieldy. When you have an existing component already the modification to make it connected is a hassle. It also interferes with Flow type-checks because it adds "invisible" props and is hard to compose when you need multiple things.

    For example:

    // Base component
    const Title = () => {
      return <h1>Search results</h1>;
    };
    
    // With results
    import { connectStateResults } from "react-instantsearch/connectors";
    const Title = ({ searchResults }) => {
      return <h1>{searchResults.hits.length} search results</h1>;
    };
    export default connectStateResults(Title);
    

    Redacted from these examples is Flow type checking and our styles HOC that makes it even more messy.

    Solution:

    React hooks offer a more encapsulated and concise way to do this:

    // With results from hook
    import { useStateResults } from "react-instantsearch/hooks";
    const Title = () => {
      const searchResults = useStateResults();
      return <h1>{searchResults.hits.length} search results</h1>;
    };
    export default Title;
    

    It is also much easier to deal with composing multiple things like results and searchState:

    // With results and searchState from hook
    import { useStateResults, useSearchState } from "react-instantsearch/hooks";
    const Title = () => {
      const searchResults = useStateResults();
      const searchState = useSearchState();
      return <h1>{searchResults.hits.length} search results for {searchState.query}</h1>;
    };
    export default Title;
    
    // Or alternatively in one:
    import { useSearch } from "react-instantsearch/hooks";
    const Title = () => {
      const { searchState, searchResults } = useSearch();
      return <h1>{searchResults.hits.length} search results for {searchState.query}</h1>;
    };
    export default Title;
    

    This seems like a small change but having the Algolia parts decoupled from the props and export makes a big difference in aggregate.

    Feedback 
    opened by GriffinSauce 33
  • Add a widget to retrieve a single hit

    Add a widget to retrieve a single hit

    Use case

    You have an instant search page with results and wants to add a link on each one of them to redirect to a detailed page with only one result.

    Need

    We need a new widget that will be able to fetch one result (through getObject).

    Proposal

    TBD

    ♨ API Difficulty: ❄️❄️ medium ♻️ Needs IS sync 
    opened by mthuret 32
  • In some cases there are multiple identical requests

    In some cases there are multiple identical requests

    Do you want to request a feature or report a bug?

    bug

    Bug: What is the current behavior?

    a single refinement (any of them) cases N requests with the exact same parameters

    Bug: What is the expected behavior?

    one request per exact same parameters

    What is the version you are using? Always use the latest one before opening a bug issue.

    4.0.10

    This is visible in

    As discussed with @vvo, we should deduplicate requests either at the React InstantSearch or Helper level, since this might be hard to solve otherwise.

    Type: ❤️ Bug Difficulty: ❄️❄️❄️ hard 
    opened by Haroenv 30
  • Feature Request - Ability to prevent search on init

    Feature Request - Ability to prevent search on init

    By default <InstantSearch> performs search with an empty query on init.

    Feature: What is your use case for such a feature? Performance and network optimization. Currently page doesn't finish loading until this initial search is finished. Also, I want to prevent searches with less than a few characters.

    Feature: What is your proposed API entry? The new option to add? What is the behavior?

    This is available in instantsearch.js with the searchFunction hook. Docs: https://community.algolia.com/instantsearch.js/v1/documentation/#hide-results-on-init

    I'd love if that hook can be used via a prop on <InstantSearch>. Ideally, every possible option for instantsearch.js would automatically be usable on <InstantSearch>.

    Thank you!

    Type: Feature request ♨ API Difficulty: ❄️❄️ medium Feedback 
    opened by flybayer 28
  • docs(refining-hits): add a tutorial on how to refine within hits

    docs(refining-hits): add a tutorial on how to refine within hits

    this is a guide that finishes with https://codesandbox.io/embed/oY1klpZYB

    fixes #244 and is obviously quite advanced

    can be found in the deploy preview under guide/Refining_hits.html

    Documentation: Guide 
    opened by Haroenv 27
  • Error: Unable to retrieve InstantSearch's server state in `getServerState()`. Did you mount the <InstantSearch> component?

    Error: Unable to retrieve InstantSearch's server state in `getServerState()`. Did you mount the component?

    🐛 Bug description

    Hey folks, having some issues with SSR and the getServerState function. I followed the steps from the docs and it's still the same. I cannot set Sandbox since it's a private repo, and if I do it from scratch I cannot reproduce the issue. I'll provide some screenshots below, maybe you see something I don't.

    💭 Expected behavior

    Is there any other way to connect the provider with the InstantSearch instance? What is the other best way to fetch initial results on the serverSide?

    🖥 Screenshots

    Screenshot 2022-08-29 at 09 12 43 Screenshot 2022-08-29 at 09 12 51

    Environment

    • React InstantSearch Hooks version: 6.31.1
    • React version: 17.0.2
    • Browser: Brave Version 1.41.100 Chromium: 103.0.5060.134 (Official Build) (x86_64)
    • OS: macOS
    opened by sasastevcic 25
  • useRange not returning any values.

    useRange not returning any values.

    🐛 Bug description

    I'm trying to convert from the old HOC version and convert to hooks, the HOC version worked but the hook version gives the response from below.

    What happens is we have some values that are range values and this doesn't work.

    This is the console log that i've done.

    const {
        range: { min, max },
        start: [minValue, maxValue],
        canRefine,
        refine,
    } = useRange({ attribute: category });
    
    console.log('HERE', category, min, max, minValue, maxValue, canRefine);
    
    'HERE' milge 0 0 -Infinity Infinity false
    

    🔍 Bug reproduction

    Nothing public that can be worked on. Unfortunately.

    💭 Expected behavior

    Nothing should change from the older HOC version.

    Environment

    • React InstantSearch Hooks version: 6.26.0
    • React version: 17.0.2
    • Browser: 103.0.5060.114
    • OS: macOS
    opened by The-Code-Monkey 25
  • Maximum call stack size exceeded. Related to cache ?

    Maximum call stack size exceeded. Related to cache ?

    Describe the bug 🐛

    I got a 500 from SSR response. In my log I get RangeError: Maximum call stack size exceeded

    To Reproduce 🔍

    Infortunately, I have only this problem on production, not on staging or local.

    If I restart my instance, everything back to normal. My memory was around 25%, I have a total o 2040 mo for my instance.

    So I assume it's a problem on Algolia's cache.

    Environment:

    Next JS 9.3.4, Algolia javascript 4.1, ReactInstantSearch 6.4.0.

    Never had the problem with Algolia 3.35.1 and ReactInstanceSearch 6.3.0

    Additional context

    14:30:24
    RangeError: Maximum call stack size exceeded
    RangeError: Maximum call stack size exceeded
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    14:30:24
    at client.search (/usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:344:50)
    14:30:24
    at /usr/src/app/node_modules/react-instantsearch-core/dist/cjs/core/createInstantSearchManager.js:348:29
    14:30:24
    at Object.get (/usr/src/app/node_modules/@algolia/cache-common/dist/cache-common.cjs.js:43:27)
    
    opened by YoannDelpierre 25
  • `offset` and `length` based pagination broken in controlled mode

    `offset` and `length` based pagination broken in controlled mode

    🐛 Bug description

    When managing the searchState in controlled mode it’s currently not possible to manage the searchState.configure.offset and searchState.configure.length without using the <Configure /> component. This means it’s impossible to build our own pagination without multiple renders/requests for a single page change, unless I’m mistaken.

    Related to this, other widget components also set searchState.page to the state when pagination resets to ‘first page’ (e.g. a refinement list).

    💭 Expected behavior

    I’d expect that we could pass any valid state into searchState and this impact the UI as in the same way as if we’d used a widget component.

    In respect to other widgets setting the searchState.page prop, these should really reset the searchState.configure.offset to 0 if searchState.configure.length is set.

    opened by joshuabaker 22
  • "Error: [ssr]: no widgets were added " - A breaking change in v6.8.0, not properly documented.

    Describe the bug 🐛

    After updating to version v6.8.0 my code stopped working for SRR on NextJS. After digging in the PR's of this repository, I noticed that it is highly likely caused by pull request #2973, which was released a few days ago under v6.8.0.

    I think this should have been marked as a breaking change. It changes the way SSR works using the WidgetsCollector which isn't properly documented in the documentation.

    See SSR docs here.

    The documentation shows that the <App /> component now receives a prop for widgetsCollector but this prop is never actually passed down by the server. Also, the related examples and type definitions were not properly updated, like the NextJS example.

    To Reproduce 🔍

    Steps to reproduce the behavior:

    1. Run the NextJS example and open in your browser.
    2. It will popup the following error: Error: [ssr]: no widgets were added, you likely did not pass the `widgetsCollector` down to the InstantSearch component.

    Expected behavior 💭

    I expected this to be either backward compatible or released as a breaking change like the industry-standard semver suggests.

    Environment:

    • OS: Linux
    • Browser: Chrome
    • Version: 36

    Additional context

    • Related pull request: https://github.com/algolia/react-instantsearch/pull/2973

    ** For people running into the same problem ** I needed install and / or revert back and freeze the version of the packages react-instantsearch, react-instantsearch-dom and react-instantsearch-core to v6.7.0 in order to fix this problem. I specifically had to install react-instantsearch-core separately too and freeze at v6.7.0 because of react-instantsearch is set to resolve all "^6.7.0" (all 6.. versions), which means it will install the 'broken' version too, v6.8.0 and above. Installing and freezing the core package worked for me.

    opened by ItsWendell 22
  • Optional searchState cleanup when unmounting a connector

    Optional searchState cleanup when unmounting a connector

    Do you want to request a feature or report a bug?

    Feature

    Feature: What is your use case for such a feature?

    I'm rendering a custom refinement list in an overlay with the connectRefinementList connector. I'd like the filters applied to stay on after the overlay is closed and unmounted. The connector currently runs the cleanUp method on unmount, which removes all refinements selected. I can create my own connector but it seems like a hassle to have to copy everything but the cleanup behaviour from the existing connectRefinementList.

    Feature: What is your proposed API entry? The new option to add? What is the behavior?

    I'm not sure what the best way to change the API would be here. Perhaps just a boolean prop stating whether or not to modify searchState on unmount?

    What is the version you are using? Always use the latest one before opening a bug issue.

    4.4.1

    Type: Feature request Difficulty: ❄️❄️❄️ hard Feedback 
    opened by denkristoffer 22
Releases(v6.38.1)
Owner
Algolia
Open source tools for building search. Learn more at community.algolia.com
Algolia
The simple but very powerful and incredibly fast state management for React that is based on hooks

Hookstate The simple but very powerful and incredibly fast state management for React that is based on hooks. Why? • Docs / Samples • Demo application

Andrey 1.5k Jan 7, 2023
🔍 Holmes is a 0 config, fast and elementary state orchestrator for React

React Holmes ?? - Elementary State Orchestrator for React ?? Holmes is a 0 config, fast and elementary state orchestrator for React. Holmes has a very

null 49 Oct 15, 2022
A blazing fast, dependency free, 1kb runtime type-checking library written entirely in typescript, meant to be used with it.

A blazing fast, dependency free, 1kb runtime type-checking library written entirely in typescript, meant to be used with it.

Gabriel Vaquer 90 Dec 9, 2022
Centrally manage state for React applications with CSP

State Trooper Install npm npm install state-trooper Yarn yarn add state-trooper Example Usage Call StateTrooper.patrolRunLoop in your route handler/ma

Swipely 15 May 14, 2022
React library for ux4iot for easily building IoT web applications

React library for ux4iot for easily building IoT web applications

Device Insight 15 Oct 31, 2022
React, React Native and Vue UI components for building data-driven apps with Elasticsearch

Reactive Search UI components library for Elasticsearch: Available for React, Vue and React Native Read how to build an e-commerce search UI a.) with

appbase.io 4.7k Jan 4, 2023
🤯 zART-stack — Zero-API, React [Native], & TypeScript

?? zART-stack — Zero-API, React [Native], & TypeScript

Alex Johansson 674 Jan 3, 2023
Maple.js is a React webcomponents based framework mixing ES6 with Custom Elements, HTML Imports and Shadow DOM. It has in-built support for SASS and JSX, including a Gulp task for vulcanizing your project.

Heroku: http://maple-app.herokuapp.com/ npm: npm install maple.js Bower: bower install maple.js Maple is a seamless module that allows you to organise

Adam Timberlake 430 Dec 23, 2022
CSS media queries in react - for responsive design, and more.

react-responsive Information Package react-responsive Description Media queries in react for responsive design Browser Version >= IE6* Demo The best s

contra 6.5k Dec 30, 2022
A performant, scalable and pluggable approach to instrumenting your React application.

react-i13n react-i13n provides a performant, scalable and pluggable approach to instrumenting your React application. Typically, you have to manually

Yahoo 369 Dec 25, 2022
Configure and build views using JSON schemas mapped to React components

react-json-schema npm install react-json-schema Construct React elements from JSON by mapping JSON definitions to React components. Use react-json-sch

Club OS 161 Dec 22, 2022
React UI Components for macOS High Sierra and Windows 10

React UI Components for macOS High Sierra and Windows 10. npm install react-desktop --save Help wanted! I am looking for developers to help me develop

Gabriel Bull 9.4k Dec 24, 2022
:postbox: A simple and customizable React notifications system

Reapop A simple and customizable React notifications system Summary Compatibility Demo Installation Integration & usage With React & Redux With React

Louis Barranqueiro 1.4k Jan 5, 2023
Useful components and utilities for working with React

react-extras Useful components and utilities for working with React Install $ npm install react-extras Usage import React from 'react'; import {If} f

Sindre Sorhus 695 Jan 7, 2023
A way to seamlessly integrate React and AngularJS

angulareact A way to seamlessly integrate React and AngularJS. Great for projects slowly migrating from AngularJS to React, supports using React compo

tonkean 18 Oct 3, 2022
A tiny state manager for React, Svelte, Vue and vanilla JS

dotto.x Dotto.x is a tiny state manager for React, Svelte, and vanilla JS. Lightweight. Core is less than 135 bytes (minified and gzipped). Zero depen

null 108 Nov 2, 2022
Teaful - Tiny, easy and powerful React state management

Tiny, easy and powerful React state management library What advantages does it have? ✨ ?? ・Tiny: Less than 1kb package to manage your state in

Teaful 668 Dec 18, 2022
Lightweight react-like library. Support for asynchronous rendering and hooks.

Recept · Lightweight react-like library. Like the name, this project is mainly based on the architectural idea of react, which can feel react more int

RuiLin Dong 52 Sep 17, 2022
react-pdf-highlighter is a React library that provides annotation experience for PDF documents on web.

☕️ Buy me a coffee react-pdf-highlighter react-pdf-highlighter is a React library that provides annotation experience for PDF documents on web. It is

Vladyslav 9 Dec 2, 2022