How to Add Search to an Astro Site With Pagefind

Search is the feature people assume a static site can’t have. It can. Pagefind builds the search index at the same time your site builds, as plain files. The browser does the rest. It’s what powers the search box on this site, and it took about ten minutes.

Step 1: Install Pagefind

In your project folder:

npm install -D pagefind

Step 2: Run it after every build

Open package.json and find the "build" line under "scripts". Change it to run Pagefind right after Astro:

"build": "astro build && pagefind --site dist"

--site dist tells Pagefind where your built site is. Pagefind reads every page in that folder and writes its index into dist/pagefind/.

Step 3: Make a search page

Create src/pages/search.astro:

---
import Layout from '../layouts/Layout.astro';
---
<Layout>
  <main>
    <h1>Search</h1>
    <link href="/pagefind/pagefind-ui.css" rel="stylesheet" />
    <script is:inline src="/pagefind/pagefind-ui.js"></script>
    <div id="search"></div>
    <script is:inline>
      window.addEventListener('DOMContentLoaded', () => {
        new PagefindUI({ element: '#search', showSubResults: true });
      });
    </script>
  </main>
</Layout>

The is:inline parts matter. Those two files don’t exist until after the build, so Astro must not try to process them. is:inline tells it to leave them alone.

Step 4: Build and try it

npm run build
npm run preview

$ npm run build
Running Pagefind v1.6.0 (Extended)
Indexed 1 language
Indexed 5 pages
Indexed 48 words
Finished in 0.027 seconds

Open localhost:4321/search and type a word from one of your pages. Results appear as you type, with the matching text highlighted.

We ran this on a fresh Astro 7.4 project. Five pages indexed, search working, no errors.

Make it better

• Index only the content. Put data-pagefind-body on your <main> or article element. This is the single biggest quality fix.
• Hide pages from search. Add data-pagefind-ignore to anything you don’t want indexed, like a thank-you page.
• Add it to your header. Link to /search/ from your menu, or open it in a dialog like we do. The Pagefind docs show how to call it from your own JavaScript.

Where to go next

• Pagefind’s docs cover filters, sorting and images in results.
• Why is my Astro site slow? if you’re adding more to your pages.