pagefind Documentation

File: README.md Copy Chapter

Pagefind

Pagefind is a fully static search library that aims to perform well on large sites, while using as little of your users’ bandwidth as possible, and without hosting any infrastructure.

The full documentation on using Pagefind can be found at https://pagefind.app/.

File: docs/content/docs/components/_index.md Copy Chapter

title: "Component System" nav_title: "Component System" weight: 2 Copy Chapter

The Pagefind Component UI is a set of web components that communicate through shared instances. This allows you to compose search interfaces from individual pieces, or use the prebuilt components that bundle everything together.

How Components Connect Copy Chapter

Components on the same page automatically connect to each other. In this example, pagefind-input triggers searches, pagefind-summary shows the count, and pagefind-results displays the matches.

Named Instances Copy Chapter

Use the instance attribute to create separate, independent search interfaces on the same page:

Components with the same instance value share state. Components with different instance values are completely independent — they maintain separate search terms, filters, and results.

Component Categories Copy Chapter

Full Experiences Copy Section

These components provide complete, ready-to-use search interfaces:

• Modal — A dialog search with keyboard navigation. Supports custom inner structure
• Modal Trigger — A button that opens the modal
• Searchbox — A compact dropdown search

Building Blocks Copy Section

These components can be composed together for custom layouts:

• Input — The search text field
• Results — The list of search results
• Summary — Shows result count and search status
• Keyboard Hints — Shows contextual keyboard shortcuts
• Filter Dropdown — A dropdown to filter by a specific facet
• Filter Pane — A sidebar-style filter panel with checkboxes

Configuration Copy Section

• Config — Set options for the Component UI, or for Pagefind itself

File: docs/content/docs/components/config.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 100 Copy Chapter

Declaratively configure a Pagefind instance. Optionally include this on the page to set options like bundle path.

Attributes Copy Chapter

Bundle Path Detection Copy Section

By default, bundle-path is automatically detected from the location of the Pagefind script. If the script is loaded from /assets/pagefind/pagefind-component-ui.js, the bundle path defaults to /assets/pagefind/. If detection fails, it falls back to /pagefind/.

Important: Attributes Are Read Once Copy Section

Attributes are only read when the component connects to the DOM. Changing attributes dynamically after connection has no effect. For dynamic configuration, use the JavaScript API instead.

Examples Copy Chapter

Custom Bundle Path Copy Section

When your Pagefind files are in a non-standard location:

External Bundle Copy Section

Load from another domain:

Preload Copy Section

Load Pagefind immediately on page load (instead of waiting for first search):

This improves perceived performance for search-only pages but adds initial page weight.

Faceted Search Mode Copy Section

Enable faceted/browse mode for catalog-style interfaces where users filter content without requiring a search term:

When faceted is enabled:

• Searching with an empty term returns all results (instead of showing nothing)
• Results update immediately when filters are changed

Combine with preload to show all results immediately on page load. Without preload, results appear after the first user interaction (e.g., opening a filter dropdown).

Named Instance Copy Section

Configure a specific instance:

Programmatic Configuration Copy Chapter

For complex configuration, use JavaScript instead of the `` element:

<script>
  const { configureInstance } = window.PagefindComponents;

  configureInstance("default", {
    bundlePath: "/pagefind/",
    mergeIndex: [
      { bundlePath: "/other-site/pagefind/" }
    ],
    ranking: {
      termFrequency: 0.8
    }
  });
</script>

Either place this on the page as shown, or compile it into your existing JavaScript bundle.

See Pagefind Search Config for all available options.

File: docs/content/docs/components/filter-dropdown.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 90 Copy Chapter

A dropdown selector for a single filter.

Attributes Copy Chapter

Keyboard Navigation Copy Chapter

Full keyboard support following the ARIA Listbox pattern:

Type-Ahead Behavior Copy Section

When you type characters while the dropdown is open:

• The component jumps to the first option that starts with the typed characters
• Matching is case-insensitive
• The type buffer clears after 500ms of inactivity

Faceted Search Mode Copy Chapter

For catalog-style interfaces where users browse by filters without requiring a search term, enable faceted mode via ``:

In faceted mode, all results are shown initially and update immediately when filters are changed. See the config component documentation for details.

File: docs/content/docs/components/filter-pane.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 80 Copy Chapter

A full filter panel displaying all available filters. Filters automatically populate based on your indexed content.

Attributes Copy Chapter

Auto-open Behavior Copy Section

By default, filter groups are collapsible. If there is only one group, and it has options at or below the auto-open-threshold, it will open automatically.

Groups can also be opened by listing their keys in the open attribute.

Filter Visibility Copy Section

• Options with zero matching results are hidden by default (unless show-empty is set or the option is selected)
• If all options in a group are hidden, the entire group is hidden

Faceted Search Mode Copy Chapter

For catalog-style interfaces where users browse by filters without requiring a search term, enable faceted mode via ``:

In faceted mode, all results are shown initially and update immediately when filters are changed. See the config component documentation for details.

File: docs/content/docs/components/input.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 10 Copy Chapter

A search input field with debouncing.

Attributes Copy Chapter

Behavior Copy Chapter

• Focusing the input begins loading the Pagefind search bundle
• When search is triggered by other components, this input's value is automatically updated
• When focused, the input registers keyboard shortcuts with the instance

Keyboard Behavior Copy Chapter

File: docs/content/docs/components/keyboard-hints.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 50 Copy Chapter

Displays contextual keyboard shortcuts based on which component currently has focus.

Attributes Copy Chapter

How It Works Copy Chapter

Keyboard hints are contextual. Different components register their shortcuts when focused:

When no component has focus, the keyboard hints area is empty.

Accessibility Copy Chapter

This component is marked aria-hidden="true" because it's a visual aid for sighted keyboard users.

The Component UI shortcuts are either the expected controls for WAI-ARIA patterns, or they are optional alternatives to standard tab navigation patterns.

Touch Devices Copy Section

Keyboard hints are automatically hidden on touch-only devices.

File: docs/content/docs/components/modal.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 40 Copy Chapter

A modal overlay container for search. Opens over the page content and traps focus until closed. Users can close it by pressing Escape, clicking the backdrop, or using the close button in the header (visible on mobile).

Attributes Copy Chapter

Default Structure Copy Chapter

When used without child elements, the modal auto-generates a default structure:

If you want to customize the contents of your own modal, the above is a good starting point.

Structure Components Copy Chapter

The modal uses three structural components. These are optional if you're providing your own modal contents, but it's recommended to place your components within them.

`` Copy Section

Fixed header area that stays pinned to the top of the modal. Typically contains the search input. Automatically includes a close button that is visible on mobile viewports.

`` Copy Section

Scrollable content area for results and other search content. Scroll is contained within this element so the header and footer remain visible.

`` Copy Section

Optional fixed footer area, pinned to the bottom of the modal. Typically contains keyboard hints or other supplementary information.

File: docs/content/docs/components/modal-trigger.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 60 Copy Chapter

A button that opens the associated modal.

Attributes Copy Chapter

Keyboard Shortcut Copy Chapter

By default, the trigger listens for Cmd+K (Mac) or Ctrl+K (Windows/Linux) to open the modal. The keyboard listener is attached at the document level, so the shortcut works from anywhere on the page.

Customizing the Shortcut Copy Section

You can customize the keyboard shortcut using the shortcut attribute:

Example with / key:

Supported syntax:

• Platform modifier: mod (Ctrl on Windows/Linux, Cmd on Mac)
• Explicit modifiers: ctrl, shift, alt, cmd/meta
• Keys: Any single character (e.g. k, /) or key name
• Case-insensitive: Keys are normalized to lowercase

The shortcut display auto-detects the platform to show the correct modifier key (⌘ on Mac, Ctrl on other platforms).

File: docs/content/docs/components/results.md Copy Chapter

title: "" nav_title: "" nav_section: Components weight: 20 Copy Chapter

Displays search results with automatic lazy loading. Results load their full data only when scrolled into view.

Attributes Copy Chapter

Keyboard Navigation Copy Chapter

When results are focused, use these keys to navigate:

Custom Templates Copy Chapter

Customize result rendering using <script type="text/pagefind-template"> elements inside the component. Templates use a simple syntax with variables, conditionals, and loops.

Basic Template Copy Section

<script type="text/pagefind-template">
    <li class="my-result">
      <h3>{{ meta.title }}</h3>
      [{{ url }}]({{ url | safeUrl }})
      {{+ excerpt +}}
    </li>
  </script>

Your template must have a single root element (e.g. a single <li>). Keyboard navigation moves between <a> elements in the results list, so ensure your main result link is an <a> tag.

The full templating syntax can be seen in the adequate-little-templates package.

Available Data Copy Section

Templates receive this data structure:

Each sub-result has: title, url, excerpt.

Template Filters Copy Section

The template engine provides built-in filters. The Component UI registers the following additional filters:

`resolveUrl(pageUrl)`

Resolves a relative URL against a page URL. Absolute URLs are returned unchanged.

"images/hero.png" | resolveUrl("/blog/post/")  →  /blog/post/images/hero.png

Placeholder Template Copy Section

While results are loading, a skeleton placeholder is shown. You can customize it with a second template using data-template="placeholder", as shown in the full example below. The placeholder template receives no data — it is static HTML.

Full Template Example Copy Section

Here's the built-in template. Copy and customize it:

<script type="text/pagefind-template">
    <li class="pf-result">
      
        {{#if and(options.show_images, meta.image)}}
        
        {{/if}}
        
          
            <a class="pf-result-link" href="{{ meta.url | default(url) | safeUrl }}"{{#if options.link_target}} target="{{ options.link_target }}"{{/if}}{{#if eq(options.link_target, "_blank")}} rel="noopener"{{/if}}>{{ meta.title }}</a>
          
          {{#if excerpt}}
          {{+ excerpt +}}
          {{/if}}
        
      
      {{#if sub_results}}
      
        {{#each sub_results as sub}}
        <li class="pf-heading-chip">
          <a class="pf-heading-link" href="{{ sub.url | safeUrl }}"{{#if options.link_target}} target="{{ options.link_target }}"{{/if}}{{#if eq(options.link_target, "_blank")}} rel="noopener"{{/if}}>{{ sub.title }}</a>
          {{+ sub.excerpt +}}
        </li>
        {{/each}}
      
      {{/if}}
    </li>
  </script>
  <script type="text/pagefind-template" data-template="placeholder">
    <li class="pf-result" aria-hidden="true">
      
        
        
          
          
        
      
    </li>
  </script>

Results Layout Copy Chapter

By default, results display in a single column. You can change the layout of the results container using CSS variables, for example a grid layout:

:root {
    --pf-results-display: grid;
    --pf-results-columns: repeat(auto-fill, minmax(250px, 1fr));
    --pf-results-gap: 16px;
}

See CSS Variables for all available layout variables.