Adding search with Algolia

Once you’ve added some content to your site, you’ll want to make it easy for your visitors to find what they’re looking for. This guide will run you through the process of setting up a custom search experience powered by Algolia on any Gatsby site. You’ll be writing functional components that rely on React Hooks so following this guide requires you to be using React 16.8 or higher.

Two things before you begin:

Beyond this guide, you may also want to checkout Algolia’s extensive docs on how to get started in React.
If you’re looking to add search to a documentation site, you can let Algolia handle most of the steps outlined below by using their Docsearch functionality. For other types of sites and more fine-grained control over exactly what data should be indexed, read on.

Configuring the Algolia plugin

First, you’ll need to add gatsby-plugin-algolia and react-instantsearch-dom to your project. react-instantsearch is Algolia’s library containing off-the-shelf React components which you can import to save yourself a lot of work. You’ll also be using dotenv which gets shipped with Gatsby by default. You’re going to need it to specify your Algolia app ID and both the search and admin API keys without commiting them to version control.

npm install --save gatsby-plugin-algolia react-instantsearch-dom algoliasearch dotenv

You will be using styled-components to design the search UI in this guide but you can use whichever CSS solution you prefer. If you’d like to start using styled-components as well, you also need to install

npm install --save styled-components gatsby-plugin-styled-components

Next, add gatsby-plugin-algolia and gatsby-plugin-styled-components to your gatsby-config.js.

gatsby-config.js

const queries = require("./src/utils/algolia")

require("dotenv").config()

module.exports = {
  siteMetadata: {
    title: `Gatsby+Algolia`,
    description: `How to setup Algolia search in Gatsby`,
    author: `<your name>`,
  },
  plugins: [
    {
      resolve: `gatsby-plugin-algolia`,
      options: {
        appId: process.env.GATSBY_ALGOLIA_APP_ID,
        apiKey: process.env.ALGOLIA_ADMIN_KEY,
        queries,
        chunkSize: 10000, // default: 1000
      },
    },
    `gatsby-plugin-styled-components`,
  ],
}

Notice that you’re loading queries from a file at ./src/utils/algolia.js (you can of course put it wherever you like) and your Algolia ID and API key from .env so let’s add those files.

.env

GATSBY_ALGOLIA_APP_ID=KA4OJA9KAS
GATSBY_ALGOLIA_SEARCH_KEY=lkjas987ef923ohli9asj213k12n59ad
ALGOLIA_ADMIN_KEY=lksa09sadkj1230asd09dfvj12309ajl

These are random character sequences but yours should be the same length. Also, it’s good practice to commit a .env.example to version control so that if someone forks your repo, they know which environment variables they need to supply.

.env.example

# rename this file to .env and supply the values listed below
# also make sure they are available to the build tool (e.g. Netlify)
# warning: variables prexifed with GATSBY_ will be made available to client-side code
# be careful not to expose sensitive data (in this case your Algolia admin key)

GATSBY_ALGOLIA_APP_ID=insertValue
GATSBY_ALGOLIA_SEARCH_KEY=insertValue
ALGOLIA_ADMIN_KEY=insertValue

The queries allow you to grab the data you want Algolia to index directly from Gatsby’s GraphQL layer by exporting from src/utils/algolia.js an array of objects, each containing a required GraphQL query and an optional index name, transformer function and settings object.

src/utils/algolia.js

const pageQuery = `{
  pages: allMarkdownRemark(
    filter: {
      fileAbsolutePath: { regex: "/pages/" },
      frontmatter: {purpose: {eq: "page"}}
    }
  ) {
    edges {
      node {
        objectID: id
        frontmatter {
          title
          slug
        }
        excerpt(pruneLength: 5000)
      }
    }
  }
}`

const postQuery = `{
  posts: allMarkdownRemark(
    filter: { fileAbsolutePath: { regex: "/posts/" } }
  ) {
    edges {
      node {
        objectID: id
        frontmatter {
          title
          slug
          date(formatString: "MMM D, YYYY")
          tags
        }
        excerpt(pruneLength: 5000)
      }
    }
  }
}`

const flatten = arr =>
  arr.map(({ node: { frontmatter, ...rest } }) => ({
    ...frontmatter,
    ...rest,
  }))
const settings = { attributesToSnippet: [`excerpt:20`] }

const queries = [
  {
    query: pageQuery,
    transformer: ({ data }) => flatten(data.pages.edges),
    indexName: `Pages`,
    settings,
  },
  {
    query: postQuery,
    transformer: ({ data }) => flatten(data.posts.edges),
    indexName: `Posts`,
    settings,
  },
]

module.exports = queries

It might look a little intimidating at first, but basically you’re just letting gatsby-plugin-algolia know how to acquire the data with which to populate your indices on their servers. The example above uses separate queries passing data to separate indices for pages and blog posts.

Transformers allow you to modify the data returned by the queries to bring it into a format ready for searching. All you’re doing here is ‘flattening’ posts and pages to ‘unnest’ the frontmatter fields (such as author, date, tags) but transformers could do much more for you if required. This makes the whole process of indexing your data really flexible and powerful. You could for instance use them to filter the results of your queries, format fields, add or merge them, etc.

If you’ve come this far, then the “backend” is done. You should now be able to run gatsby build and see your indices in Algolia’s webinterface be flooded with your data.

Adding a search interface to your site

Next, let’s build a user-facing search interface for your site. It needs a way for the user to enter a search string, send that string to Algolia, receive matching results (hits in Algolia speak) from your indices and finally display those to the user. Let’s dive right in.

You’re going to assemble everything you need into a React Search component that you call from anywhere on your site where you want the user to be able to search. Even though design varies strongly from site to site, I’ll also go through the styles implemented with styled-components in this guide since working out the CSS transitions to have the search field slide out as the user clicks on it and the results pane to appear once Algolia returns matches took some time.

The Search components is made up of the following files:

index.js: the main component
input.js: the text input field
hitComps.js: the components that will render matching posts/pages
styles.js: the styled components

There’s quite a lot happening in these files so let’s break them down one by one and piece by piece.