Using the default Pagefind UI

Pagefind provides a UI component that supports searching, filtering, and metadata out of the box.

#Adding the Pagefind UI to a page

Pagefind UI can be added to any page with the following snippet. The /_pagefind/ directory and containing files will be created for you when running the Pagefind CLI.

<link href="/_pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/_pagefind/pagefind-ui.js" type="text/javascript"></script>

<div id="search"></div>
<script>
    window.addEventListener('DOMContentLoaded', (event) => {
        new PagefindUI({ element: "#search" });
    });
</script>

#Customising the styles

The Pagefind UI is styled using CSS custom properties which can be overridden. To tweak the existing stylesheet, set any of the following variables on your site:

--pagefind-ui-scale: 1;
--pagefind-ui-primary: #034ad8;
--pagefind-ui-text: #393939;
--pagefind-ui-background: #ffffff;
--pagefind-ui-border: #eeeeee;
--pagefind-ui-tag: #eeeeee;
--pagefind-ui-border-width: 2px;
--pagefind-ui-border-radius: 8px;
--pagefind-ui-image-border-radius: 8px;
--pagefind-ui-image-box-ratio: 3 / 2;
--pagefind-ui-font: sans-serif;

If your website features a dark/light toggle using a classname, a good idea is to set the colour variables alongside that class. For example, the following snippet will swap Pagefind to a darker theme when the page body contains a dark class:

body.dark {
  --pagefind-ui-primary: #eeeeee;
  --pagefind-ui-text: #eeeeee;
  --pagefind-ui-background: #152028;
  --pagefind-ui-border: #152028;
  --pagefind-ui-tag: #152028;
}

#Styling Pagefind UI yourself

Pagefind UI can be styled manually by omitting the /_pagefind/pagefind-ui.css stylesheet. In this case it will function as a pure HTML component.

The classnames within Pagefind UI that begin with pagefind-ui should be targeted. These may change, so if you are styling them yourself make sure to test new releases of Pagefind with your stylesheet. Changes to classnames will be highlighted in the release notes, but will not be signalled by a major release.

#Using custom Pagefind UI strings

Pagefind UI will attempt to use translated text based on the language tag of the active page. If built in tanslations are not found, the UI will fall back to English text. Custom text can instead be supplied using the translations option.

#Overriding the URL of a result

The Pagefind UI will look for a value under the metadata key url, and use that for result links if present. This allows you to override the URL of a single page by tagging metadata on that page, for example:

<link 
    data-pagefind-meta="url[href]"
    rel="canonical" 
    href="https://example.com/other-url">

#PagefindUI options

These options configure Pagefind UI itself. Any extra keys in this object will be passed on to configure the Pagefind search API.

#Element

new PagefindUI({ element: "#search" });

A selector for the HTML element to attach Pagefind UI to. This is the only required argument.

#Translations

new PagefindUI({
    element: "#search",
    translations: {
        placeholder: "Search my website",
        zero_results: "Couldn't find [SEARCH_TERM]"
    }
});

A set of custom ui strings to use instead of the automatically detected language strings. See the translations/en.json file for all available keys and their initial values.

The items in square brackets such as SEARCH_TERM will be substituted dynamically when the text is used.

#Show images

new PagefindUI({
    element: "#search",
    showImages: false
});

Whether to show an image alongside each search result. Defaults to true.

#Process result

new PagefindUI({
    element: "#search",
    processResult: function (result) {
        result.meta.image = someCustomFunction(result.meta.image);
        return result;
    }
});

Provides a function that Pagefind UI calls before displaying each result. This can be used to fix relative URLs, rewrite titles, or any other modifications you might like to make to the raw result object returned by Pagefind.

#Show empty filters

new PagefindUI({
    element: "#search",
    showEmptyFilters: true
});

By default, Pagefind UI shows filters with no results alongside the count (0). Pass false to hide filters that have no remaining results.

#Reset styles

new PagefindUI({
    element: "#search",
    resetStyles: false
});

By default, Pagefind UI applies a CSS reset to itself. Pass false to omit this and inherit from your site styles.

#Bundle path

new PagefindUI({
    element: "#search",
    bundlePath: "/subpath/_pagefind/"
});

Overrides the bundle directory. In most cases this should be automatically detected from the URL of pagefind-ui.js. Set this if search isn’t working and you are seeing a console warning that this path could not be detected.

#Debounce user input

new PagefindUI({
    element: "#search",
    debounceTimeoutMs: 500
});

The number of milliseconds to wait after a user stops typing before performing a search. Defaults to 300. If you wish to disable this, set to 0.