astro-pagefind

For Pagefind 1.5.0+, it is recommended to use Pagefind's native component-based UI instead of the Search.astro component. To ensure the Pagefind bundle path is wired correctly in Astro, you must include the PagefindConfig component on your page.

To implement a searchbox, import PagefindConfig and use the <pagefind-searchbox> web component.

---
import PagefindConfig from "astro-pagefind/components/PagefindConfig.astro";
---

<PagefindConfig />
<pagefind-searchbox></pagefind-searchbox>

Install the astro-pagefind package using npm to integrate Pagefind static site search into your Astro project.

npm i astro-pagefind

Add astro-pagefind to the integrations array in your astro.config.ts file to enable index building during static builds and serving prebuilt indices in astro dev mode.

//astro.config.ts

import { defineConfig } from "astro/config";
import pagefind from "astro-pagefind";

export default defineConfig({
  integrations: [pagefind()],
});

To use astro-pagefind in your Astro project, import the default export from astro-pagefind and add it to the integrations array in your astro.config.mjs or astro.config.ts file.

import astroPagefind from 'astro-pagefind';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [astroPagefind()],
});

You can use the Search component from astro-pagefind/components/Search.astro. Note that this component is currently in maintenance mode and will not receive new UI features. It is useful for simple integrations where you want to pass specific searchboxOptions via props.

Props:

• instance: A unique identifier for the search instance.
• className: CSS class for the component.
• searchboxOptions: An object containing options to pass to the Pagefind Searchbox.

---
import Search from "astro-pagefind/components/Search.astro";
---

<Search instance="search" className="pagefind-ui" searchboxOptions={{ placeholder: "search" }} />

The Search component is the primary entry point for rendering the Pagefind search UI in an Astro project. It wraps the <pagefind-searchbox> web component and allows you to pass configuration for both the Pagefind engine and the search box UI via props.

To use it, import Search from astro-pagefind/components/Search.astro and provide optional props to customize its behavior and appearance.

---
import Search from "astro-pagefind/components/Search.astro";
---

<Search 
  instance="my-search-instance" 
  className="custom-search-class" 
  searchboxOptions={{ placeholder: "Search articles..." }}
  configOptions={{ libPath: "/pagefind/" }}
/>

To use astro-pagefind, add it to your astro.config.mjs file. You can optionally provide an indexConfig object, which is passed directly to Pagefind's createIndex function to customize how the search index is generated.

Note: This integration requires your Astro output mode to be static. If your config.output is set to server, the integration will issue a warning because it requires static *.html pages to function.

import astroPagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [
    astroPagefind({
      indexConfig: {
        // PagefindServiceConfig options go here
      }
    })
  ],
});

The PagefindConfig component accepts several props which are passed directly to the underlying <pagefind-config> web component.

Props

• instance (optional): A string identifying a specific Pagefind instance. This allows you to have multiple independent search instances on a single page.
• ...props: Any other valid attributes for the <pagefind-config> web component (e.g., configuration settings for the Pagefind engine).

The PagefindOptions interface defines the configuration available when initializing the astro-pagefind integration.

export interface PagefindOptions {
  /**
   * `PagefindServiceConfig` passed to pagefind's `createIndex`
   */
  indexConfig?: PagefindServiceConfig;
}

The Search component accepts the following props:

The PagefindConfig component is used to inject Pagefind configuration into your Astro page. It renders a <pagefind-config> web component and automatically handles the bundle-path by pointing it to the pagefind/ directory relative to your BASE_URL.

It also ensures that the @pagefind/component-ui library is imported in the client-side script to initialize the search UI.

import PagefindConfig from "astro-pagefind/components/PagefindConfig.astro";

// Basic usage
<PagefindConfig />

// Usage with a specific instance
<PagefindConfig instance="my-search-instance" />