Quick Start with Searchkit

Quick Start with Searchkit and instantsearch.js

This guide will show you how to get started with Searchkit and instantsearch.js.

Download an Example Project

You can check out a vite + Instantsearch.js project with Searchkit here:

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

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

Index Example E-Commerce Dataset

We are going to use the ecommerce dataset from bestbuy.

Download the sample dataset from sample-data/electronics-ecommerce/bulk.json (opens in a new tab) and index the documents via the bulk API.

curl -H 'Content-Type: application/x-ndjson' -XPOST 'localhost:9200/_bulk?pretty' --data-binary "@bulk.json"

This will add 10000 products to the products index.

The bulk API requires a newline delimited JSON file. The last line of the file must be a newline character.

Add CDN scripts to your page

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

<script src="https://cdn.jsdelivr.net/npm/@searchkit/instantsearch-client@latest"></script>
<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@4"></script>
<script src="https://cdn.jsdelivr.net/npm/searchkit@latest"></script>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/instantsearch.css@7/themes/algolia-min.css"
/>

Building the Frontend

Add the html and javascript to your page:

<div class="ais-InstantSearch">
 
  <div class="left-panel">
    <h2>Categories</h2>
    <div id="categories-list"></div>
  </div>
  <div class="right-panel">
    <div id="searchbox" class="ais-SearchBox"></div>
    <div id="hits"></div>
    <div id="pagination"></div>
  </div>
</div>
 
    <script type="text/javascript">
      /* global instantsearch algoliasearch */
 
      const sk = new Searchkit({
        connection: {
          host: "http://localhost:9200",
          // cloud_id: "my-cloud-id" // if using Elastic Cloud
          // if you are authenticating with username/password
          // https://www.searchkit.co/docs/guides/setup-elasticsearch#connecting-with-usernamepassword
          //auth: {
          //  username: "elastic",
          //  password: "changeme"
          //},
          // if you are authenticating with api key
          // https://www.searchkit.co/docs/guides/setup-elasticsearch#connecting-with-api-key
          // apiKey: "######"
        },
        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 search = instantsearch({
        indexName: "products",
        searchClient: SearchkitInstantsearchClient(sk)
      });
 
      search.addWidgets([
        instantsearch.widgets.searchBox({
          container: "#searchbox"
        }),
        instantsearch.widgets.refinementList({
          container: "#categories-list",
          attribute: "categories"
        }),
        instantsearch.widgets.hits({
          container: "#hits",
          templates: {
            item(hit, { html, components }) {
              return html`
                <h2>
                  ${hit.__hitIndex}:
                  ${components.Highlight({ attribute: 'name', hit })}
                </h2>
                <p>${components.Snippet({ attribute: 'description', hit })}</p>
              `;
            }
          }
        }),
        instantsearch.widgets.pagination({
          container: "#pagination"
        })
      ]);
 
      search.start();
    </script>

Video Tutorial

And that's it! You can now search your data in Elasticsearch using instantsearch and Searchkit. Customise the search experience by adding widgets and customising the search settings.

Adding Refinements

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

See the Refinements to add refinements to your search.

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.

Deploying to Production

TODO - Contributions welcome

Overview With React