Search
Full-text search across the site, including these docs, in a pop-up on every page, with no server and no third-party service.
On a wide screen, search from the box in the header, or press / or Cmd+K (Ctrl+K on Windows) on any page. On a phone, Search in the header opens a pop-up (in the menu, on a site whose header has no room for it). The full list, with filters, is on the search page.
When to use it
- A site has more pages than its menu can show: articles, case studies, a catalogue.
- Every Somnia site has it unless it is switched off (
features.search).
Use something else when:
- The site is a handful of pages: the menu is enough, and a search that finds little disappoints.
- People need to narrow a list by its properties (price, place, dates): that is a filter on the list’s own page, not search.
Anatomy
- Header search box (components/HeaderSearch.astro, 1100 px and wider): results drop down as you type, each with arrow links to its matching sections (headings only). Enter, or See all results, opens the search page with the same search. It looks the same before and after it's first used: the same icon, and the Ctrl K hint whenever it's empty and not focused.
- Pop-up (components/SiteSearch.astro): the same results in a dialog, for phones and windows between 800 and 1100 px, where a compact Search link takes the box's place. It has a visible Close button as well as Escape.
- Search page (/search/): every result, with Type (Case studies, Insights, Somnia DS, Pages) and Topic filters (tick several values in one filter to see any of them, for example Case studies and Insights; the two filters together narrow the list), a thumbnail, a type pill such as Case study or Insight, and up to three links straight to matching sections. The search is kept in the page address, so it can be bookmarked or shared.
- Thumbnails: an article's photo or a case study's first screenshot, made small at build time. Other pages get a drawn tile in the page's own light or dark colours: the Media Dreams ring and dot, large and cropped by the right edge, as on the share images; Somnia DS pages show the Somnia mark; the changelog is a commit graph whose newest commit is the dot.
- Results are a plain list with a rule between each, the title in the heading face, and matches tinted and underlined in the accent colour, so they don't rely on colour alone.
Focus and keys
- The result you're on has the accent ring flush round the whole result, on a light tint; a section link is a full-width row with room round its arrow, ringed with no tint. The same in the header dropdown, the pop-up and the search page.
- Up and down arrows move through results; Enter opens the one you're on. Enter before choosing a result opens the full search page.
Keeping content out of search
Search should find each page by its own words. Anything that repeats another page's words, or isn't really words, is left out with data-pagefind-ignore="all" on its outer element:
- Always out: case study mockups (CaseWidget), the homepage carousel, logo walls, card grids and their filters on the case studies and Insights pages, related-article lists, promos and calls to action, breadcrumbs and the Somnia DS toolbar.
- Index pages stay findable by their title and lede ("case studies", "insights"), but their cards are left to the pages they link to.
- A component that is sometimes a repeat takes a prop instead, for example
<SomniaPromo searchable={false} />at the end of an article. - Plain
data-pagefind-ignore(no value) leaves the text out but still reads any filter or metadata tags inside it;"all"leaves out everything, so it's the one to use for content.
How it works
- Pagefind builds a search index from the finished pages at build time. The index is a set of small static files on our own server.
- Only each page's main content is indexed, not the header, footer or navigation.
- Results load as you type, a few kilobytes at a time; nothing is sent anywhere else.
- The interface is Pagefind's Component UI, themed through its
--pf-*variables, which point at Somnia DS tokens, so it follows light, dark, every brand and print (styles/global.css, "Site search"). - The Component UI script (about 175 KB) loads only when someone heads for search (hovering over the header box is enough), so other pages don't pay for it.
- Filters and thumbnails are set on each page at build time (layouts/Base.astro). Breadcrumbs, the Somnia DS sidebar, toolbar and status lines, the dark copy of each example, the focus, keyword and related-article panels, and repeated promos are kept out of the index (
data-pagefind-ignore), so excerpts show the page's own words. - The pop-up is a native dialog: focus moves into it, Tab and Shift+Tab go round its own controls (never onto the dialog itself), Escape or Close leaves it, and focus returns to where it was. Arrow keys move through results. The key hints say what each key does there: Escape closes.
- Open filter menus sit under the sticky header, never over it.
- Without JavaScript, or in the local preview (npm run dev, which has no index), Search in the header is an ordinary link to the search page.
- If search can't run (no JavaScript, or the index fails to load), the page says so in its lede and links to the case studies and Insights instead, so it reads like any other page opening.
Do and don't
Do
- Write page titles and opening lines that say what a page is
- Keep forms and furniture out of the index
- Leave search where it is, in the header, on every page
Don't
- Record what people search for without telling them
- Open results in a new tab
- Send people to the search page when the pop-up will do
Accessibility
What it does for you
- A search box in the header on wide screens; on phones a round Search link that opens a pop-up.
- Keys from anywhere:
/, or Cmd+K (Ctrl+K on Windows), goes to search unless you are typing in a field. - In the pop-up, Tab goes round its own controls and never out to the page behind; Escape or Close always leaves it, and focus goes back to Search.
- Results appear as you type, each with its kind of page in words, and the matched words marked without losing contrast.
- Without script, or with no index, the Search link goes to the search page.
What you need to do
- Page titles and opening lines that say what a page is: they are what a result shows.
- Keep forms and furniture out of the index (
data-pagefind-ignore), so a page is found for its words.
Keyboard
| Key | What it does |
|---|---|
| / or Cmd+K, Ctrl+K | Goes to the search box, or opens the pop-up on a narrow screen. |
| Typing | Searches as you type. |
| Tab, Shift+Tab | Through the box, Clear, the results, See all results and Close. |
| Enter | On a result: opens it. |
| Escape | Closes the pop-up. |
What a screen reader is told
- The box: a combo box named Search.
- On phones: a link named Search. The pop-up: a dialog. Each result: a link named by the page’s title.
This is what the browser reports to assistive technology. What each screen reader then says varies, and has not been listened to yet.
WCAG 2.2
| Criterion | Level | How this meets it |
|---|---|---|
| 2.1.1 Keyboard | A | Every part of search works from the keyboard. |
| 2.1.2 No Keyboard Trap | A | Escape or Close leaves the pop-up. |
| 2.4.3 Focus Order | A | Focus stays inside the pop-up while it is open and goes back to Search when it closes (1.81.0: it had fallen to the top of the page). |
| 1.4.3 Contrast (Minimum) | AA | Marked words keep their contrast in light and dark. |
| 3.2.3 Consistent Navigation | AA | Search is in the same place in the header on every page. |
| 4.1.2 Name, Role, Value | A | The pop-up is a native dialog; its controls have names. The header’s box has a name of its own (1.81.0: its placeholder had been its only name). |
The criteria this component has a part in. A page that uses it still has to meet the rest.
Checked
| Check | How | Result |
|---|---|---|
| Automated (axe-core) | WCAG 2.0, 2.1 and 2.2 rules at A and AA, the page in light and in dark | Passed Nothing found, light or dark |
| Narrow screen | No sideways scrolling at 320px wide (WCAG 1.4.10) | Passed No sideways scrolling |
| Keyboard and what the browser reports | Real key presses on the live example, and the role, name and state given to assistive technology | Passed 7 of 7 checks pass |
| On paper | Somnia’s print check: no overlaps, stranded headings or controls on the page | Passed No faults on 6 sheets |
| Screen reader | Listened to by a person, in VoiceOver and NVDA | Not yet Not yet checked by a person |
The 7 checks made with the keyboard, on the example at the top of this page:
- Passed The / key goes to the search box in the header
- Passed Ctrl+K does the same
- Passed Tabbing on past the search box while it loads doesn’t pull the focus back to it
- Passed The search box has a name
- Passed Typing shows results, each a link to its page
- Passed On a phone, Search opens a dialog; Escape closes it and focus goes back to Search
- Passed In the dialog, Tab stays inside it
Run by script on against Somnia DS 1.89.0, in Chromium with axe-core 4.14.0. How these checks work, and every component's results.
Not yet checked
- How it sounds in a screen reader (VoiceOver, NVDA, TalkBack) has not been checked by a person. The roles, names and states the browser reports are checked by script; what is actually spoken is not.
- Windows high contrast (forced colours) has not been looked at by a person.
- Whether the number of results is announced as it changes has not been checked: that part is Pagefind’s.
Evidence
Where it's used
| Where | For |
|---|---|
| mediadreams.co.uk | Case studies, Insights and these docs. |
| Headland Yachting | Destinations, advice and yachts. |
| The starter | On by default for every new site. |
What we saw, and what changed
| When | What we saw | What changed |
|---|---|---|
| Client login had the place in the header. | Search took it (1.4.0), and left the footer the same day (1.4.1). | |
| Searching meant leaving the page for the search page. | A pop-up on every page, from the header, / or Cmd+K (1.9.0). | |
| Form labels and the contact page’s switch turned up in results. | Forms are kept out of the index (1.22.0). | |
| Phones corrected and capitalised search words. | No autocorrect, spell check or capitals in search boxes (1.35.0). | |
| Writing this page’s checks: after Escape on a phone, focus was at the top of the page, not on Search; the header’s box was named by its placeholder alone; and this page was 4px too wide at 320px, from a file path that could not break. | Focus goes back to Search, the box has its own name, and long words in running text break (1.81.0). | |
| The header’s checks found that tabbing on from the search box before it had loaded pulled the focus back to it a moment later. | The box takes the focus only if the keyboard is still on it (1.83.0). |
From building and using it on real sites, each entry taken from the changelog or the build's own notes. This is observation by the studio and its clients, not research sessions with users.
What it rests on
- Pagefind: The search itself: an index made at build time and read in the browser, with no server and nothing sent anywhere.
- ARIA Authoring Practices: Dialog (Modal): Focus kept inside the pop-up, Escape to close, focus returned.
What we don't know yet
- What people search for is not recorded, by design, so nothing is known about searches that find nothing.
- A search of these docs alone has not been built.