Configuring the Pagefind search in the browser

The behaviour of the Pagefind search API can be configured in the browser.

<pagefind-config base-url="/"></pagefind-config>

<pagefind-input></pagefind-input>
<pagefind-results></pagefind-results>

// If installed via a package manager:
import { configureInstance } from '@pagefind/component-ui';
// If loaded via script tag:
const { configureInstance } = window.PagefindComponents;

configureInstance("default", {
    baseUrl: "/",
    // ... more search options
});

const pagefind = await import("/pagefind/pagefind.js");
await pagefind.options({
    baseUrl: "/",
    // ... more search options
});

Available options

Base URL

Defaults to “/”. If hosting a site on a subpath, baseUrl can be provided, and will be appended to the front of all search result URLs.

<pagefind-config base-url="/docs/"></pagefind-config>

configureInstance("default", {
    baseUrl: "/docs/"
});

await pagefind.options({
    baseUrl: "/docs/"
});

Bundle path

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

<pagefind-config bundle-path="/subpath/pagefind/"></pagefind-config>

configureInstance("default", {
    bundlePath: "/subpath/pagefind/"
});

await pagefind.options({
    basePath: "/subpath/pagefind/"
});

Excerpt length

Set the maximum length for generated excerpts. Defaults to 30.

<pagefind-config excerpt-length="15"></pagefind-config>

configureInstance("default", {
    excerptLength: 15
});

await pagefind.options({
    excerptLength: 15
});

Highlight query parameter

If set, Pagefind will add the search term as a query parameter under the same name.

If using the Pagefind highlight script, make sure this is configured to match.

<pagefind-config highlight-param="highlight"></pagefind-config>

configureInstance("default", {
    highlightParam: "highlight"
});

await pagefind.options({
    highlightParam: "highlight"
});

Exact Diacritics

Defaults to false. When set to true, diacritics (accents such as àéö) are treated as fully distinct characters.

By default, Pagefind normalizes diacritics so that searching for “cafe” will match pages containing “café” and vice versa. When diacritics are normalized, exact matches are still preferred via the ranking.diacriticSimilarity parameter.

When exactDiacritics is set to true:

• Searching for “café” will only match pages containing “café”
• Searching for “cafe” will only match pages containing “cafe”

<pagefind-config exact-diacritics></pagefind-config>

configureInstance("default", {
    exactDiacritics: true
});

await pagefind.options({
    exactDiacritics: true
});

Meta cache tag

By default, Pagefind appends a timestamp to the metadata request to ensure fresh data. If you’re building a PWA or offline-capable site, set this to a fixed string so that your service worker can cache the request. Change this value each time you rebuild your site. A build timestamp or random string works well.

The search index itself is unaffected and can always be cached.

<pagefind-config meta-cache-tag="abc123"></pagefind-config>

configureInstance("default", {
    metaCacheTag: "abc123"
});

await pagefind.options({
    metaCacheTag: "abc123"
});

Ranking

See customize ranking

Index weight

See multisite search > weighting

Merge filter

See multisite search > filtering

Disable web worker

Defaults to false. If set to true, forces Pagefind to run all search operations on the main thread instead of using a web worker.

By default, Pagefind will attempt to use a web worker for search operations when available, which helps keep the main thread responsive during searches. If web workers are not supported or fail to initialize, Pagefind will automatically fall back to running on the main thread.

<pagefind-config no-worker></pagefind-config>

configureInstance("default", {
    noWorker: true
});

await pagefind.options({
    noWorker: true
});