Adding Search with JS Search

Prerequisites

Before you go through the steps needed for adding client-side search to your Gatsby website, you should be familiar with the basics of Gatsby. Check out the tutorial and brush up on the documentation if you need to. In addition, some knowledge of ES6 syntax will be useful.

What is JS Search

JS Search is a library created by Brian Vaughn, a member of the core team at Facebook. It provides an efficient way to search for data on the client with JavaScript and JSON objects. It also has extensive customization options, check out their docs for more details.

The full code and documentation for this library is available on GitHub. This guide is based on the official js-search example but has been adapted to work with your Gatsby site.

Setup

You’ll start by creating a new Gatsby site based on the official hello world starter. Open up a terminal and run the following command:

After the process is complete, some additional packages are needed.

Change directories to the js-search-example folder and issue the following command:

Or if Yarn is being used:

Note:

For this particular example axios will be used to handle all of the promise-based HTTP requests.

Strategy selection

In the next sections you’ll learn about two approaches to implementing js-search in your site. Which one you choose will depend on the number of items you want to search. For a small to medium dataset, the first strategy documented should work out nicely.

For larger datasets you could use the second approach, as most of the work is done beforehand through the use of Gatsby’s internal API.

Both ways are fairly generalistic, they were implemented using the default options for the library, so that it can be experimented without going through into the specifics of the library.

And finally, as you go through the code, be mindful it does not adhere to the best practices, it’s just for demonstration purposes, in a real site it would have been implemented in a different way.

JS-Search with a small to medium dataset

Start by creating a file named SearchContainer.js in the src/components/ folder, then add the following code to get started:

Breaking down the code into smaller parts:

1. When the component is mounted, the componentDidMount() lifecycle method is triggered and the data will be fetched.
2. If no errors occur, the data received is added to the state and the rebuildIndex() function is invoked.
3. The search engine is then created and configured with the default options.
4. The data is then indexed using js-search.
5. When the contents of the input changes, js-search starts the search process based on the input’s value and returns the search results if any, which is then presented to the user via the table element.

Joining all the pieces

In order to get it working in your site, you would only need to import the newly created component to a page. As you can see in the example site.

Run gatsby develop and if all went well, open your browser of choice and enter the url http://localhost:8000 - you’ll have a fully functional search at your disposal.

JS-Search with a big dataset

Now try a different approach, this time instead of letting the component do all of the work, it’s Gatsby’s job to do that and pass all the data to a page defined by the path property, via pageContext.

To do this, some changes are required.

Start by modifying the gatsby-node.js file by adding the following code:

Create a file named ClientSearchTemplate.js in the src/templates/ folder, then add the following code to get started:

Create a file named ClientSearch.js in the src/components/ folder, then add the following code as a baseline:

Breaking down the code into smaller parts:

1. When the component is mounted, the getDerivedStateFromProps() lifecycle method is invoked and it will evaluate the state and if necessary update it.
2. Then the componentDidMount() lifecycle method will be triggered and the rebuildIndex() function is invoked.
3. The search engine is then created and configured with the options defined.
4. The data is then indexed using js-search.
5. When the contents of the input changes, js-search starts the search process based on the input’s value and returns the search results if any, which is then presented to the user via the table element.

Joining all the pieces

Once again to get it to work on your site you would only need to copy over the gatsby-node.js file located here.

And both the template and the search component.

Issuing gatsby develop again, and if all went without any issues one more time, open your browser of choice and enter the url http://localhost:8000/search, you’ll have a fully functional search at your disposal coupled with Gatsby API.

Hopefully this rather extensive guide has shed some insights on how to implement client search using js-search.

Now go make something great!