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.

#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.

#Show images

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

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

#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.