New Pagefind UI

[HiDeoo]

Description

This draft PR is a very early version of a rewrite of the Pagefind UI that is used in Starlight.

This is a work in progress and is not ready for production or even for a full review yet. A lot of work is still needed to get it to a point where it can be used in Starlight. Most of the work has only been done in 1 browser and parts of the UI have been tested in isolation against only 1 screen reader so far so it'll require a lot of testing and improvements before it can be considered ready in its entirety.

The main goal of having more control over the search UI and improving the accessibility of the search experience in Starlight.

A few important points to note:

• Filters are always visible as some have been configured in the content which is not the case in the live version of the documentation.
• Translations are now part of Starlight although I did not port the existing ones from the original Pagefind UI. That was my original idea although after checking the French one, I was not pleased with some of the translations. We can think about it later.
• Most of the UI mimics the original Pagefind UI as closely as possible to iterate faster on a working veersion. Only a few parts may have changed, e.g. always-visible query input or filters disclosure icon now matching the one used in the Starlight Markdown UI, etc.
• The current UI used in the live version of the documentation was potentially limited due to the lack of control when using the original Pagefind UI. Something to potentially consider later is if there are any changes to the original UI that we would like to see in this version.
  • Something coming to mind could be an always-visible query input but that's a decision that should be made later. This PR implements an always-visible query input but it's not looking great and was mostly done to make testing easier (in a dedicated commit so it can be easily reverted later if needed).

An interesting search is upgrade:

• It displays some metadata.
• With this branch not being updated with Exclude banner content from Pagefind indexing #3276, the banner content of the homepage is still indexed and this search will display it as a single root result with an excerpt and no sub-results (which is not broken like in Search display broken due to code marks and other elements #3267).

Development notes:

• This PR adds the pnpm pagefind command to the docs/ directory which should be used when iterating on this PR:
  • It simultaneously runs a dev version of the docs running on the 4321 port and a prod version on the 4322 port.
  • When developing, visiting http://localhost:4321 will use the search indexes from the prod version which allows for using/testing/iterating on the search UI (note that changes that would result in a change to the search indexes will require running the pnpm pagefind command again).

Remaining todos

• Look for any TODO(HiDeoo) remaining comments and address them.
• Add changeset(s)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 703307e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	703307e
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/68de45a8eb9dec0008585d01
😎 Deploy Preview	https://deploy-preview-3335--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 99 (🟢 up 27 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	demo/trigger-filters.md	Source added, will be tracked.
en	demo/trigger-search.md	Source added, will be tracked.
en	guides/i18n.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[HiDeoo]

Alongside some minor changes and improvements, this PR now also includes an always-visible query input. It does not looks great and it's part of the points I initially mentioned in the description of this PR that should be discussed regarding potential changes to the original Pagefind UI.

The main reason I quickly implemented it is to make testing easier as the original design was not very convenient when using the search UI a lot. It's in a dedicated commit so it can be easily reverted later if needed.

[HiDeoo]

Updated the PR to adds support for new features which are currently not supported at all in Starlight. To decide which features to implement first, I looked at the various feature requests that have been opened and also what is currently being done in the ecosystem.

• Adds support for programmatically controlling Pagefind
  • This adds support for the triggerFilters and triggerSearch public API methods.
  • This was motivated by the starlight-versions plugin having to re-implement entirely the Search component just to trigger this functionality.
  • With this, a component override can wrap the default Search component with a custom web component, querySelector the default web component, and call any of the public API methods on it.
  • Demos of this have been temporarilly added to the documentation.
• Adds support for the showEmptyFilters option
  • This was requested in Pagefind Result Filtering/Categories #2391 (comment) and Support for more Pagefind config options #3117
• Adds support for the openFilters option
  • This was requested in Support for more Pagefind config options #3117
• Adds support for the processTerm option
  • This was requested in Ability to add custom values to `PagefindUI` constructor options (in Search component) #1358 (comment)
  • As this is a non-serializable option, a new clientOptionsModule option was added, similar to the DocSearch plugin, that allows a user to define the path to a configuration file exporting the Pagefind configuration.

[HiDeoo]

Updated the PR based on the feedback from T&D (14 August 2025):

• When present, the "Load more results" is now always visible in a footer of the modal. Like the always-visible query input, it's definitely not a definitive or even thought-out design, but more of an experiment.
• Refactor the API design to avoid the need to querySelector some web components. All pagefind related exports are now available from the @astrojs/starlight/pagefind module which exposes a getPagefindApi function that returns an object with methods to trigger filters and search.

[HiDeoo]

Due to various UI changes that happened in the course of this PR, e.g. an always-visible search input or load more button (when applicable), the current UI entirely relying on the previous design feels a bit "heavy" in my opinion around these changes.

Sharing here a few screenshots of more compact versions of the same UI (not included in this PR) for reference and discussion. I am obviously not the best when it comes to design, so only sharing as these parts of the UI have been on my mind while working on this PR. As we now have entire control over the UI, there is also more room for customization depending on where we want to take this in the future.

Current

Experiments

[ematipico]

Tested on Firefox Developer Tools (desktop):

• The height of the modal is smaller than before, which affects the visibility of the results shown. I preferred the previous height

  

One minor (nitpick) drawback on mobile. Now that input search (header) and more results (footer) are sticky, when clicking "More results", you don't have a visual change anymore that shows that new results were loaded.

[HiDeoo]

Thanks for the great feedback 🙌

Definitely agree, and this is also something I've started looking at in #3335 (comment) (screenshots included).

To give a bit more context, this PR initially started by a rewrite to improve the accessiblity, but as we now have more control, some UI/UX changes have also started to make sense. So far, such changes have been added with minimal effort regarding the design aspect which explains such large padding around some elements. As I'm also not the best when it comes to design, this is also something where Chris inputs would be very valuable.

Regarding the last point, definitely something that is missing right now, great reminder. Such indicators have been implemented for screen-readers, but not visually yet. I'm guessing these would be added once we have a better idea of the overall design direction.