Notoriously Punctual Manatee
    Have ideas to improve npm?Join in the discussion! »

    gatsby-plugin-local-search
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.1 • Public • Published

    gatsby-plugin-local-search

    Gatsby plugin for providing client-side search for data available in Gatsby's GraphQL layer using a variety of engines.

    The following engines are supported:

    This plugin provides a search index and store using the selected engine. To display search results, pair the index and store with a compatible React hook or component. See Displaying the search results.

    Install

    npm install --save gatsby-plugin-local-search

    How to use

    // gatsby-config.js
    
    module.exports = {
      plugins: [
        // You can have multiple instances of this plugin to create indexes with
        // different names or engines. For example, multi-lingual sites could create
        // an index for each language.
        {
          resolve: 'gatsby-plugin-local-search',
          options: {
            // A unique name for the search index. This should be descriptive of
            // what the index contains. This is required.
            name: 'pages',
    
            // Set the search engine to create the index. This is required.
            // The following engines are supported: flexsearch, lunr
            engine: 'flexsearch',
    
            // Provide options to the engine. This is optional and only recommended
            // for advanced users.
            //
            // Note: Only the flexsearch engine supports options.
            engineOptions: 'speed',
    
            // GraphQL query used to fetch all data for the search index. This is
            // required.
            query: `
              {
                allMarkdownRemark {
                  nodes {
                    id
                    frontmatter {
                      path
                      title
                    }
                    rawMarkdownBody
                  }
                }
              }
            `,
    
            // Field used as the reference value for each document.
            // Default: 'id'.
            ref: 'id',
    
            // List of keys to index. The values of the keys are taken from the
            // normalizer function below.
            // Default: all fields
            index: ['title', 'body'],
    
            // List of keys to store and make available in your UI. The values of
            // the keys are taken from the normalizer function below.
            // Default: all fields
            store: ['id', 'path', 'title'],
    
            // Function used to map the result from the GraphQL query. This should
            // return an array of items to index in the form of flat objects
            // containing properties to index. The objects must contain the `ref`
            // field above (default: 'id'). This is required.
            normalizer: ({ data }) =>
              data.allMarkdownRemark.nodes.map((node) => ({
                id: node.id,
                path: node.frontmatter.path,
                title: node.frontmatter.title,
                body: node.rawMarkdownBody,
              })),
          },
        },
      ],
    }

    How to query

    A new node type becomes available named localSearch${name}, where ${name} is the name provided in the options. In the above example, the node would be accessed with localSearchPages.

    The search index and store are made available as fields on the node.

    • index: (String) The search index created using the engine selected in the plugin options.
    • store: (JSON) The store used to map a search result's ref key to data.

    Note that store is an object but does not require you to explicitly query each field.

    {
      localSearchPages {
        index
        store
      }
    }

    Lazy-loading the index and/or store

    The index and store can become large depending on the number of documents and their fields. To reduce your bundle size and delay fetching these pieces of data until needed, you can query a URL for both the index and store like the following.

    {
      localSearchPages {
        publicIndexURL
        publicStoreURL
      }
    }

    Both publicIndexURL and publicStoreURL will return a public URL that can be fetched at run-time. For example, you could call fetch with the URLs to load the data in the background only as the user focuses your interface's search input.

    The files contain data identical to querying for index and store directly and will be saved in your site's /public folder. This functionality if very similar to gatsby-source-filesystem's publicURL field.

    Displaying the search results

    This plugin provides a search index and store object but leaves presentation and search functionality up to you.

    The following React components/hooks are recommended pairings:

    Install

    npm i gatsby-plugin-local-search

    DownloadsWeekly Downloads

    3,465

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    38.1 kB

    Total Files

    14

    Last publish

    Collaborators

    • avatar
    • avatar