Want more control over your search setup? Discover our flexible infrastructure pricing.

Go to homeMeilisearch's logo
Back to articles

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

Learn how to easily add search to your Gatsby site with this detailed and easy-to-follow step-by-step guide.

11 Jun 20257 min read
Ilia Markov
Ilia MarkovSenior Growth Marketing Managernochainmarkov
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.

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.

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.

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.

Meilisearch offers fast, typo-tolerant, full-text search that fits right into your Gatsby setup. It’s open source, easy to configure, and built for modern site search.

Semantic search vs Vector search: Key differences, uses, & more

Semantic search vs Vector search: Key differences, uses, & more

Discover the key differences between semantic and vector search, their use cases, strengths, and how to choose the right approach for your search needs.

Ilia Markov
Ilia Markov30 Jul 2025
Elasticsearch vs Typesense (vs Meilisearch): Which search engine actually fits your needs in 2025?

Elasticsearch vs Typesense (vs Meilisearch): Which search engine actually fits your needs in 2025?

Compare Elasticsearch's enterprise-scale power, Typesense's developer-friendly speed, and Meilisearch's AI-powered simplicity to find the search engine that matches your needs, team capabilities, and growth trajectory.

Ilia Markov
Ilia Markov29 Jul 2025
Most personalized search experiences are a lie

Most personalized search experiences are a lie

Learn what true search personalization looks like – and how to implement it without bloated, ineffective solutions.