next-instantsearch

Server side rendering with Next.js and React InstantSearch

What is it?

next-instantsearch is a plugin for Next.js projects that allows you to easily configure your Algolia powered InstantSearch app with SSR and URL sync out of the box.

The current version of this library is only compatible with InstantSearch v6 or greater. See the upgrade guides for more info.

View a live demo of the simple example based on the react-instantsearch next example.

Installation

npm install next-instantsearch
# or
yarn add next-instantsearch

Getting started

Use the withInstantSearch HOC to configure InstantSearch and enable SSR:

import algoliasearch from "algoliasearch/lite";
import { withInstantSearch } from "next-instantsearch";
import {
  Configure,
  Highlight,
  Hits,
  Pagination,
  RefinementList,
  SearchBox,
} from "react-instantsearch-dom";

const searchClient = algoliasearch("your_app_id", "your_api_key");

const HitComponent = ({ hit }) => <Highlight attribute="name" hit={hit} />;

const Page = () => (
  <>
    <Configure hitsPerPage={12} />
    <SearchBox />
    <RefinementList attribute="categories" />
    <Hits hitComponent={HitComponent} />
    <Pagination />
  </>
);

export default withInstantSearch({
  indexName: "your_index",
  searchClient,
})(Page);

You may also configure via getInitialProps:

import algoliasearch from "algoliasearch/lite";
import { withInstantSearch } from "next-instantsearch";
import {
  Configure,
  Highlight,
  Hits,
  Pagination,
  RefinementList,
  SearchBox,
} from "react-instantsearch-dom";

const searchClient = algoliasearch("your_app_id", "your_api_key");

const HitComponent = ({ hit }) => <Highlight attribute="name" hit={hit} />;

const Page = () => (
  <>
    <Configure hitsPerPage={12} />
    <SearchBox />
    <RefinementList attribute="categories" />
    <Hits hitComponent={HitComponent} />
    <Pagination />
  </>
);

Page.getInitialProps = async () => ({
  indexName: "your_index",
  // You may want to set some default searchState.
  // This will be merged on to state from the url.
  searchState: {
    refinementList: {
      categories: ["Appliances"],
    },
  },
});

export default withInstantSearch({
  searchClient,
})(Page);

Advanced Usage

Out of the box next-instantsearch will trigger a shallow route replace when your search state changes. This may not work for you if you're using a non standard router or maybe you want to prevent this route change with a no-op.

import { withInstantSearch, createURL, onSearchStateChange } from "next-instantsearch";
import { Router } from "../i18n";

withInstantSearch({
  indexName: "your_index",
  searchClient,
  onSearchStateChange: (searchState) => onSearchStateChange(searchState, Router),
  // or
  onSearchStateChange: () => {}, // Prevent route change
  // or
  onSearchStateChange: (searchState, Router) => {
    // ... Some custom implementation ...
  },
})(Page);

During SSR react-instantsearch will call renderToString on your component, meaning your component is rendered outside of the context of your app. For this reason you may need to wrap your component with some context providers etc. More info on react-instantsearch SSR can be found here.

withInstantSearch({
  indexName: "your_index",
  searchClient,
  decorate: ({ ctx, component }) => (
    <Provider store={ctx.store}>{component()}</Provider>
  ),
})(Page);