How to setup custom Algolia Instant Search in Gatsby

Oscar de la Hera Gomez
Algolia Instant Search allows you to search Algolia index's in real time

The following tutorial will walk you through how to setup Algolia Instant Search using custom React components in GatsbyJS.

If you are new to working with Algolia in Gatsby, we recommend that you read our article on Algolia & read Gatsby's Adding Search With Algolia.

Gatsby's guide will offer you to a starter project that can be accessed via the following command line command:

$ gatsby new gatsby-algolia-guide

This starter project demonstrates how to integrate OOTB Algolia React Components, but Algolia's documentation does not support custom cases, which are covered in this tutorial.

Step One: Add the Plugin

Gatsby's Github documentation on their Algolia plugin

In Terminal, in the current directory of your project, run the following line

yarn add gatsby-plugin-algolia

Step Two: Find your API Keys

In Algolia, Go to Settings -> API Keys

Your Algolia keys are found by navigating to, going to settings and selecting API Keys.

Step Three: Add the env variables

If you do not already have one, create a .env file at the root of your directory and add the following environment variables and associated keys from Step 2.


Add the following ENV Variables to your Gatsby App: GATSBY_ALGOLIA_APP_ID, GATSBY_ALGOLIA_SEARCH_KEY & ALGOLIA_ADMIN_KEY. Make sure to match them with your projects API keys from

Step Four: Add dotenv to your gatsby-config.js

If you do not yet have dotenv, please run the following line in Terminal, in the current directory of your project:

yarn add dotenv

Once you have it please add it to the top of your gatsby-config.js using the following line:


This step is centered around adding "dotenv" to your gatsby-config.js

Step Five: Add the configuration

In your gatsby-config.js, under the module.exports add the following item.

{  resolve: gatsby-plugin-algolia,  options: {   appId: process.env.GATSBY_ALGOLIA_APP_ID,   apiKey: process.env.ALGOLIA_ADMIN_KEY,   queries: require("./algolia/queries"),  }, }

Add the following configuration to your Gatsby-config.js

Step Six: Add your Algolia Queries

Create an algolia folder at the base level & create a queries.js file.

The folder structure for your Algolia files in GatsbyJS

Step Seven: Write your Algolia Query

A sample Algolia Index Query

In the newly created queries.js, paste the following code

This javascript file creates two queries for Algolia to index:

  1. Blog Index - which creates an index of all the blog pages.
  2. Pages - which creates an index of all the pages in

If you are new to GraphQL fragments, please visit the following page.

Step Eight: Build your website

In Terminal, in the current directory of your project, run the line below.

yarn build

Once its complete you should see something like this:

After running the build, you should see a message like this.

Algolia prints a post-build message similar to the above.

Step Nine: Verify that your query showed up in Algolia.

Navigate to your app in Algolia, and confirm that your results show up.

Navigate to your index on and confirm that you have indexed your files correctly.

Step 10: Add Algolia's NPM Package

An image of Algolia Search's Github Readme

In Terminal, in the current directory of your project, run the following line

yarn add algoliasearch

Step 11: Add the Algolia Instant Search API Call

An image of the code required to call instant search

Add the following code to your custom search component, please note that searchQuery is the query gathered from the search UI & queryID is Algolia's reference to the search that's required for Analytics.

Step 12: Verify that the search works

In your UI write a search term and verify that it filters results accurately. In the example below that term that we used is metaverse.

A sample Algolia Search of our search page for "Metaverse"

Any Questions?

We are actively looking for feedback on how to improve this resource. Please send us a note to with any thoughts or feedback you may have.

delasign logo

Book a Free Consultation.

An icon of an email.

Click here to email us.

Fill in the details below to book a free consultation or to let us know about something else. Whatever it is, we are here to help.

How can we help you ?

Contact Details