Docs
Quick Start
With React

Quick Start with Searchkit and React instantsearch

This guide will show you how to get started with Searchkit and React Instantsearch components.

If you use Next.js, checkout the Next.js guide for a simpler setup.

Download an Example Project

You can check out a Next.js project with Searchkit here:

curl https://codeload.github.com/searchkit/searchkit/tar.gz/main | \
tar -xz --strip=2 searchkit-main/examples/with-ui-nextjs-react

or view the example codebase on github here (opens in a new tab)

Code Sandbox Example

You can also check out the code sandbox example here:

Quick Start

For this quick start, we are going to run Elasticsearch locally and build a small e-commerce search experience using Searchkit and instantsearch.

Running Elasticsearch

This quick start will need CORS enabled as we will be calling Elasticsearch / Opensearch directly from the browser. See Enable CORS to do this.

Alternatively, you can proxy the Elasticsearch / Opensearch requests. See Proxy Elasticsearch for more details.

Going to use Elasticsearch via Docker for this quick start.

For other options, see Setup Elasticsearch.

Below we are running Elasticsearch with CORS enabled and security disabled. For production, you should enable security and use an API key. See Setup Elasticsearch for more ways of connecting with authentication.

docker pull docker.elastic.co/elasticsearch/elasticsearch:8.6.2
docker network create elastic
docker run --name elasticsearch --net elastic -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -e "xpack.security.enabled=false" -e http.cors.enabled=true -e "http.cors.allow-origin='*'" -e http.cors.allow-headers=X-Requested-With,X-Auth-Token,Content-Type,Content-Length,Authorization -e http.cors.allow-credentials=true -e network.publish_host=localhost -e xpack.security.enabled=false docker.elastic.co/elasticsearch/elasticsearch:8.6.2

Create an Index & index some data

Our data model will have the following structure:

  • A products has many product documents
  • Each product document has a name, price, description and categories attributes

Lets create an index called products and add some data.

curl --location --request PUT 'http://localhost:9200/products' \
--header 'Content-Type: application/json' \
--data-raw '{
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "description": {
        "type": "text"
      },
      "price": {
        "type": "integer"
      },
      "categories": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword"
          }
        }
      }
    }
  }
}'

Now lets add some data to our index.

curl --location --request POST 'http://localhost:9200/products/_doc' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Apple iPhone 12 Pro Max",
  "description": "The iPhone 12 Pro Max is the most powerful iPhone ever. It has a 6.7-inch Super Retina XDR display, a Ceramic Shield front cover, and a triple-camera system with a LiDAR scanner. It also has a 5G connection, a 6-core CPU, and a 4-core GPU. The iPhone 12 Pro Max is available in 128GB, 256GB, and 512GB storage options.",
  "categories": ["phones", "apple"],
  "price": 800
}'
 
curl --location --request POST 'http://localhost:9200/products/_doc' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Apple iPhone 12 Pro",
  "description": "The iPhone 12 Pro is the most powerful iPhone ever. It has a 6.1-inch Super Retina XDR display, a Ceramic Shield front cover, and a triple-camera system with a LiDAR scanner. It also has a 5G connection, a 6-core CPU, and a 4-core GPU. The iPhone 12 Pro is available in 128GB, 256GB, and 512GB storage options.",
  "categories": ["phones", "apple"],
  "price": 700
}'

Installation

Installing both the API and instantsearch-client is easy. You can install them with npm or yarn.

For more details on installation and usage, see Installation.

npm install searchkit @searchkit/api @searchkit/instantsearch-client react-instantsearch-dom

Building the Frontend

Add the following code to your React app:

import React from "react";
import ReactDOM from "react-dom";
import Client from "@searchkit/instantsearch-client";
import Searchkit from "searchkit";
import { InstantSearch, SearchBox, Hits, RefinementList } from "react-instantsearch-dom";
 
// Create a Searchkit client
// This is the configuration for Searchkit, specifying the fields to attributes used for search, facets, etc.
const sk = new Searchkit({
  connection: {
    host: "http://localhost:9200",
  },
  search_settings: {
    highlight_attributes: ["name"],
    snippet_attributes: ["description"],
    search_attributes: [{ field: "name", weight: 3 }, "description", "categories"],
    result_attributes: ["name", "description", "price", "categories"],
    facet_attributes: [{
      field: "categories.keyword",
      type: "string",
      attribute: "categories",
    }, {
      field: "price",
      type: "numeric",
      attribute: "price",
    }],
  },
})
 
const searchClient = Client(sk);
 
const App = () => (
  <InstantSearch indexName="bestbuy" searchClient={searchClient}>
    <SearchBox />
    <RefinementList attribute="categories" />
    <Hits />
  </InstantSearch>
);
 
export default App;

Adding Refinements

Refinements provide your users with a way to narrow down their search results.

See the Refinements to add refinements to your search.

Customising the UI

TODO - contributions welcome

Query Rules

Query rules allow you to customize the search results based on the user's query.

Follow the query rules guide to add query rules to your search.


Apache 2.0 2023 © Joseph McElroy.
Need help? Join discord