How To Add Lunr Search To Your Gatsby Website

Static sites built with Gatsby offer exceptional performance and security, but implementing search functionality requires careful consideration. Unlike server-side solutions, client-side search with Lunr.js enables full-text search capabilities without external services. This guide walks through building a complete search implementation for your Gatsby website.

For teams building static websites with modern JavaScript frameworks, implementing robust search functionality is essential for content-rich sites. Lunr.js provides a lightweight, self-contained solution that maintains the performance benefits of static hosting.

Understanding Lunr.js for Static Sites

Lunr.js is a lightweight JavaScript library that provides full-text search functionality directly in the browser. For Gatsby static sites, this means search works without any server-side infrastructure, maintaining the core Jamstack benefits of performance and simplicity.

Why Choose Client-Side Search

Client-side search with Lunr.js offers several advantages for static websites. First, there's no need for external search services or APIs, eliminating recurring costs and reducing dependencies. The search index is built at build time and bundled with your site, enabling instant search responses without network latency. Since all search logic runs in the browser, there are no server-side search queries to manage or scale.

For content-driven Gatsby sites with hundreds or thousands of pages, Lunr.js provides an efficient solution. The index stores word-to-document mappings, allowing quick retrieval of matching content without server round-trips.

How Lunr.js Works

Lunr.js uses an inverted index as its core data structure. This index stores mappings from words to the documents containing them, enabling fast lookups. When you search for a term, Lunr.js doesn't scan every document--instead, it consults the index to find matching documents immediately.

The library allows you to define which fields to index (title, content, description) and provides options for boosting certain fields to influence search relevance. This flexibility means you can tune search results to prioritize titles over body content, for example. For more details on Lunr.js capabilities, refer to the official Lunr.js documentation.

Setting Up Your Gatsby Project

Before implementing search, ensure your Gatsby project is ready. The implementation works with any Gatsby site, but for demonstration purposes, we'll reference the official Gatsby blog starter as a reference point.

The striptags package is essential for clean indexing. When extracting content from HTML, you'll want to strip markup tags to avoid indexing HTML syntax as searchable content. This ensures your search results contain actual page content, not HTML elements.

This approach aligns with best practices for search engine optimization in static site development, ensuring your content remains both searchable and properly indexed.

Creating the Search Index in Gatsby Node

The search index is generated during Gatsby's build process, leveraging the node API to access all site content and create a searchable structure.

Using Gatsby's createResolvers API

This resolver queries all MarkdownRemark nodes (or your content nodes of choice), processes them through the index creation function, and returns the serialized index ready for client-side use. This implementation pattern follows the approach documented in the CSS-Tricks guide on implementing Lunr.js search in Gatsby.

Building the Index Function

The createIndex function processes all content nodes, extracting searchable text and generating the Lunr.js index structure.

The function serves two purposes. First, it builds the Lunr index with title and content fields for searching. Second, it creates a store mapping each document slug to its title and excerpt--information that Lunr doesn't include in search results but is essential for displaying meaningful results to users.

This dual-purpose approach, as demonstrated in the CSS-Tricks implementation guide, ensures your search results are both accurate and user-friendly.

Building the Search Form Component

The search form provides the user interface for entering queries. We'll create a reusable component that works with both traditional form submission and instant search patterns.

Creating the SearchForm Component

This component uses React hooks for state management and supports both immediate updates (for instant search) and traditional form submission. The @reach/router package, included with Gatsby, handles navigation to the search results page with the query parameter.

Accessibility Considerations

The form includes proper labeling with htmlFor linking the label to the input. The role="search" attribute identifies the landmark for assistive technologies. These accessibility features ensure all users can effectively use your search functionality.

Implementing accessible search is a key aspect of inclusive web development practices that serve all users effectively.

Implementing the Search Results Page

The search results page receives the query, executes the search against the Lunr index, and displays matching results.

Querying the Index

The page queries the LunrIndex field, loads the index using Lunr.js's Index.load() method, and executes the search. Results are mapped to include display information from the store, providing users with clickable titles and relevant excerpts.

This implementation follows established patterns for building efficient search functionality in Gatsby sites, ensuring users can quickly find the content they're looking for.

Adding Instant Search Functionality

For sites with rich content, instant search--updating results as the user types--provides a superior user experience. This requires a different component structure that uses useStaticQuery since it's not a page component.

Creating the Search Widget

The instant search widget uses useStaticQuery since it's not a page component. Results update on every keystroke, providing immediate feedback to users.

Performance Considerations

Client-side search requires careful attention to performance, as the index and search logic execute in users' browsers.

Index Size Management

The search index grows with your content. For sites with thousands of pages, consider segmenting indexes by content type or category. Gatsby's node API allows filtering which nodes to include in the index. For larger sites, implementing search result pagination and limiting index fields to essential content reduces bundle size while maintaining search quality.

Bundle Optimization

Lazy load the Lunr.js library and search components to avoid impacting initial page load times. The search functionality only needs to load when users interact with search, not on initial page render. Dynamic imports with React.lazy() allow you to defer loading until needed.

Search Query Efficiency

Lunr.js supports advanced query syntax including wildcards, boosting, and boolean operators. For most use cases, simple term matching provides excellent results. Avoid complex queries that might slow down the search experience. You can boost title matches over content matches using syntax like ${query}^3 for prioritized results.

These performance optimizations align with best practices for Gatsby performance optimization, ensuring your site remains fast and responsive.

Best Practices for Content Indexing

Effective search depends on quality content indexing. Follow these practices for optimal results.

Clean Content Extraction

Always strip HTML tags from content before indexing. Raw HTML includes markup that shouldn't be searchable and can bloat the index unnecessarily. The striptags package handles this efficiently by removing HTML markup while preserving text content.

Multiple Field Indexing

Index multiple fields to improve search relevance. Title matches should carry more weight than body content matches, and you might include tags, categories, or custom fields for enhanced searchability. Use the field() method in Lunr.js to define which document fields are searchable.

Excerpt Generation

Store excerpts with your documents for display in search results. This provides context for why a result matched and helps users decide which result to click. Generate excerpts during indexing rather than on search time to improve performance.

Conclusion

Implementing Lunr.js search in Gatsby provides a powerful, self-contained search solution without external dependencies. By creating the index during build time and executing searches client-side, you maintain the performance and simplicity that static sites offer while adding sophisticated search functionality.

The key to success lies in thoughtful index design--choosing which fields to index, how to weight them, and how to present results. With the implementation patterns covered in this guide, you can adapt Lunr.js search to any Gatsby project, from simple blogs to complex documentation sites.

Looking to implement advanced search functionality on your website? Our web development team specializes in building high-performance static sites with custom features like full-text search.

Sources

1. CSS-Tricks: How to Add Lunr Search to Your Gatsby Website
2. Gatsby Plugin: gatsby-plugin-lunr-search
3. Lunr.js Official Documentation