How to add search to your Gatsby site: Step-by-step guide

If you’re looking for a fail-proof, fast and scalable search functionality to directly add to your static site, the answer is Gatsby search. With just a few clicks, Gatsby search enables any user to look for relevant content across a Gatsby site, so you don’t have to worry about traditional navigation.

Gatsby users can implement search by using plugins such as gatsby-plugin-meilisearch, gatsby-plugin-local-search, or by connecting external search APIs. These tools use GraphQL queries to index data from Markdown, JSON, or HTML files and support client-side or pre-rendered search components.

This article is your guide on how to add a real-time, full-text search engine to your Gatsby site. We’ll also cover details about the plugins, configurations, and writing GraphQL queries. And on top of that, you’ll learn how to transform data and deploy a working search index.

Let’s start by going through the steps to add search to any Gatsby project using Meilisearch.

1. Install the Meilisearch plugin for your Gatsby site

The first step is to install an open-source plugin: gatsby-plugin-meilisearch. Why?

This gatsby-plugin is the connection between your Gatsby site and Meilisearch instance using defined API credentials. The main benefit is that it allows your project to generate a live search index during build time. Additionally, it supports full-text search, filters, and smooth client-side search operations. So, let’s begin.

Use npm:

npm install gatsby-plugin-meilisearch

After installation, go to your gatsby-config.js file. This is where you define site settings and Gatsby plugin options. Add the plugin to the plugins array with the correct host and apiKey for your Meilisearch instance.

// gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-meilisearch',
      options: {
        host: 'http://localhost:7700',
        apiKey: 'masterKey',
      },
    },
  ],
}

You can learn more about this plugin on GitHub.

This sets up the foundation for your search engine. Next, you’ll define the search index and configure the data you want to fetch.

2. Configure the search index and GraphQL query

Once you have installed the gatsby-plugin-meilisearch, you need to define the content you want to send to Meilisearch. This will happen inside gatsby-config.js, where you set up the indexes array.

Each entry represents a search index. This is also where you specify the GraphQL query and index name aligned with how you transform the data.

Here’s an example configuration:

// gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-meilisearch',
      options: {
        host: 'http://localhost:7700',
        apiKey: 'masterKey',
        indexes: [
          {
            indexUid: 'pages_index',
            query: `
              {
                allSitePage {
                  nodes {
                    path
                  }
                }
              }
            `,
            transformer: data =>
              data.allSitePage.nodes.map((node, index) => ({
                id: index,
                path: node.path,
              })),
          },
        ],
      },
    },
  ],
}

This graphql query fetches data from your Gatsby site pages. The transformer function prepares it for indexing by assigning each entry a unique ID. This guarantees Meilisearch can now store and return the relevant search results properly.

3. Build and index your Gatsby content

Now, it’s time to build and index the content. We’ve already configured the search index and GraphQL. When you run gatsby build, gatsby-plugin-meilisearch takes the data from your Gatsby site and pushes it to your Meilisearch instance. This step connects your local content with a real-time search index.

To run the build:

gatsby build

Once complete, you’ll see a message like:

success gatsby-plugin-meilisearch - Documents added to Meilisearch

This is confirmation that your data has been indexed. The Meilisearch dashboard or local instance will help you inspect the indexed content.

If you forget this step, your search query will not return any results since there will be no content to search through.

You can also refer to the official Gatsby plugin documentation for additional options, such as batchSize, skipIndexing, or custom settings like searchableAttributes.

Now that your content is indexed, it's time to connect the search UI.

4. Add a search component to your Gatsby frontend

Building a user interface comes after your Gatsby site content is indexed. To simplify this, you can use a search component like docs-searchbar.js. It works because it integrates with Meilisearch and supports the search functionality we’re building.

Start by installing the package:

yarn add docs-searchbar.js

Then, in your src/components folder, locate the appropriate JS file (like AppBar.js). Now, import the search module and CSS:

import 'docs-searchbar.js/dist/cdn/docs-searchbar.css'

In your React component, use a useEffect hook to initialize the search:

useEffect(() => {
  const docsSearchBar = require('docs-searchbar.js').default
  docsSearchBar({
    hostUrl: 'http://localhost:7700',
    apiKey: 'masterKey',
    indexUid: 'your-index',
    inputSelector: '#search-bar-input',
    meilisearchOptions: { limit: 5 },
    enhancedSearchInput: true,
  })
}, [])

Finally, add the search input field in your JSX:

<input type="search" id="search-bar-input" placeholder="Search..." className="searchbox" />

This setup connects your static frontend to a live search index. Users get results as they type, and search query parsing, autocomplete, and typo tolerance are fully supported.

Next up is customization. You will learn how to modify a search experience to better match your site’s design and structure.

5. Customize your search experience

To unlock customization for your Gatsby site, you need a working search component. Once it’s working, you can modify the search experience according to your site’s structure and design.

To begin, you will modify the transformer function in gatsby-config.js.

This function determines how your data appears in Meilisearch. You can enrich each search index item with metadata like frontmatter.title, description, slug, or any custom fields.

transformer: (data) =>
  data.allMdx.edges.map(({ node }) => ({
    id: node.id,
    title: node.frontmatter.title,
    description: node.frontmatter.description,
    url: node.slug,
  }))

Prioritization is a significant part of customization. To prioritize which fields Meilisearch should match first, you will update searchableAttributes in the plugin settings:

settings: {
  searchableAttributes: ['title', 'description', 'content']
}

Meilisearch brings several other perks to your customization process. For instance, you can easily adjust query behavior, such as typo tolerance and filtering. Plus, you can always tweak the CSS styles of your search input and add a classname to match your design system.

Building components manually through React components? You might refer to the React Search Engine guide for increased frontend control. Customization is all about enhancing the user experience, and this is no exception.

6. Build and deploy your Gatsby site with search

With the search functionality in place and customization all done, it’s time for the final step: to build and deploy your Gatsby site. Let’s run the protection build command:

gatsby build

During build, gatsby-plugin-meilisearch runs your GraphQL query, applies the transformer, and pushes data to the search index. This process runs on every deployment if your Gatsby site is hosted on platforms like Netlify.

Once live, test your searchbox, confirm search input behavior, and validate query results. On Meilisearch Cloud, you also get access to built-in analytics.

Use the official Gatsby plugin documentation or this Gatsby search tutorial for full setup steps.

How is search used in Gatsby?

Search adds speed and usability to static content—Gatsby sites often power blogs, documentation, ecommerce, and marketing pages.

With gatsby-plugin, content in Markdown, JSON, or HTML becomes searchable. This improves navigation and makes your site search fast and efficient.

Let’s have a look at some of the key use cases:

• Site search: A quick way to help users locate what they are looking for on your Gatsby site.
• Docs search: Makes it easier to look up commands in developer documentation built with Markdown and frontmatter.
• Blog search: Filtering by tag, category, or title makes it way easier to find the content you care about.
• e-Commerce search: Helps shoppers look up products and see suggestions as they type.
• Static knowledge bases: It is responsible for fast client-side search across indexed content.

In short, search is responsible for the user experience and engagement across all these formats.

Does Gatsby support server-side search?

No, it does not. Gatsby is a static site generator, so it builds all your content ahead of time and shows pre-made HTML pages. An outside tool like Meilisearch could be the answer if you want to add live search to your site. It works by handling queries and returning the results through the API. For example, one way to add the desired search on your site is by using the Meilisearch React integration.

Does Gatsby support local search?

Yes. Gatsby supports local search using plugins like gatsby-plugin-local-search and lunr. These tools index content at build time and provide lightweight, browser-based search without relying on external APIs. While this suits smaller projects, larger sites often use Meilisearch for faster indexing, typo tolerance, and advanced search functionality. For complex content-driven sites, Meilisearch is a more flexible option.

Building powerful search in Gatsby sites

Search is a must-have on any content-rich Gatsby site. Fast search is invaluable for blogs, docs, and especially online stores. Tools like gatsby-plugin-meilisearch bring real-time, typo-tolerant search functionality to your React components.

Meilisearch connects through your gatsby-config.js using a GraphQL query, a transformer function, and a defined search index. It supports Markdown, JSON, and nested content structures. With minimal setup, your static Gatsby site can offer dynamic search query handling and a modern user experience.