Accessibility

Search Web Components names every control and announces each search to screen readers. Keyboard focus stays in place after a search. For what a site builder sets, see Accessibility in the Build guide.

What the elements do

Every control has an accessible name. The search forms are search landmarks, the pager is a navigation landmark, and the current page button is marked as the current page.
facet-checkbox and facet-button group their options under the facet's label. A facet's reset button names its facet.
After each search, search-root announces the number of results, that there are none, or that the search failed. The search that runs when the page loads is not announced, and loading is not announced.
search-results has aria-busy="true" while a search runs.
After keyboard use, focus stays on the control used. When that control goes away, e.g., the last applied filter, focus moves to a control nearby. For where focus goes, see Focus.
The HTML dropdowns, facet-dropdown-html and search-sort and search-results-per-page with type="html", follow the W3C select-only combobox example. With multipleSelect on facet-dropdown-html, the list allows several choices, and Tab closes it and keeps the selection.
The filter dialog is named, its toggle tells whether it is open, and Escape closes it.

For every role and ARIA attribute an element sets, see Classes and ARIA attributes.

Attributes that name things

ariaLabelText names:
- the text input of search-input and search-box
- the control of search-sort and search-results-per-page when labelText is empty
- the group of search-results-switcher
- the list of search-results and of search-applied-facets
- the navigation landmark of search-simple-pager
- the dialog of search-dialog-pane
landmarkLabelText names the search landmark of search-input and search-box. Give each one its own name when a page has two.
submitAriaLabelText names the submit button when its text has no letters or digits, e.g., →.
The pager's pageAriaLabelText names each page button, e.g., Page @page. prevAriaLabelText, nextAriaLabelText, firstAriaLabelText, and lastAriaLabelText name those buttons when their text has no letters or digits, e.g., the default < and >.
resetAriaLabelText names a facet's reset button, with the tokens @reset, @label, and @count.
The four announcement texts on search-root:
- resultsAnnouncementText, for two or more results, default @total results
- oneResultAnnouncementText, default 1 result
- noResultsAnnouncementText, default No results found
- searchErrorAnnouncementText, default The search could not be completed. Try again.
The first three take the tokens @total and @searchQuery. An empty text says nothing. noSearchAnnouncement turns the announcement off.

Focus

When a search re-renders the control a keyboard user just used, focus goes to:

after a facet option: the same option, also when the options change order.
after a facet's reset button: the facet's first option.
after a remove button in search-applied-facets: the first of these that is there:
- the remove button for the same filter
- the remove button now in the used one's place
- the last remove button
- the reset button
after the last remove button, or the search-applied-facets reset button: the search-input text input.
after the clear button of search-input: the text input.
after a page number in the pager: the button for that page, now the current page.
after the pager's previous or next button: the same button while it can still be used, otherwise the current page button.
after the pager's first or last button: the current page button.
after a search-did-you-mean suggestion that goes away: the search-input text input.

When that control cannot take focus, focus goes to the first of these that can:

Checked	Focus goes to	Condition
1	The `search-input` text input of the same search root.	The text input is not hidden with `opacity: 0`.
2	The next control after the component in the search root that Tab reaches.
3	The dialog's first control.	The component is inside an open modal `search-dialog-pane`.

These rules apply to every component:

Focus outside the component: never moved.
After a mouse click or a tap: focus returns only to the same control, e.g., a re-ordered facet option.
A control that is not rendered, or is visibility: hidden: skipped. A control hidden with opacity: 0, e.g., a theme's native checkbox under a drawn one, still gets focus.
The page scrolls to show the new control only when all of these are true:
- the new control is not fully on screen
- the used control was on screen
- the page has not scrolled since the render started

A component of your own takes part through _getFocusedControlKey() and _getFocusTargetAfterRender(). For every hook, see Hooks and methods.

Plural forms

The announcement has one text for one result and one for two or more. For a language with more plural forms, override _getSearchAnnouncementText() in a search-root subclass. The hook receives the outcome, ok or error, and returns the text to announce. A returned '' says nothing.

class PolishSearchRoot extends SearchRoot {
  override _getSearchAnnouncementText(outcome: 'ok' | 'error') {
    const total = this.context.response?.search_results_count ?? 0;
    if (outcome === 'error' || total === 0) {
      return super._getSearchAnnouncementText(outcome);
    }
    const texts: Record<string, string> = {
      one: '1 wynik',
      few: `${total} wyniki`,
      many: `${total} wyników`,
      other: `${total} wyniku`,
    };
    return texts[new Intl.PluralRules('pl').select(total)];
  }
}
customElements.define('polish-search-root', PolishSearchRoot);

W3C references

Each component follows the W3C reference in this table for its keys, focus, and ARIA attributes:

Component	Pattern	Example page
`DropdownMixin`: `facet-dropdown-html`, and `search-sort` and `search-results-per-page` with `type="html"`	APG select-only combobox	https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/
`BaseFacetElement`: collapsible facet label, "show more"	APG disclosure	https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-faq/
`facet-checkbox`	APG two-state checkbox, with the options grouped under the facet label	https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/examples/checkbox/ and https://www.w3.org/WAI/tutorials/forms/grouping/
`facet-checkbox` with `useRadios`	APG radio group	https://www.w3.org/WAI/ARIA/apg/patterns/radio/examples/radio/
`facet-button`, `search-results-switcher`, and `search-sort` and `search-results-per-page` with `type="list"`	APG button, toggle button with `aria-pressed`	https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/
`search-applied-facets`, `search-did-you-mean`	APG button, as command buttons	https://www.w3.org/WAI/ARIA/apg/patterns/button/examples/button/
`facet-dropdown`, and `search-sort` and `search-results-per-page` with `type="select"`	No APG pattern for a native `select`: WAI forms tutorial, Labeling Controls	https://www.w3.org/WAI/tutorials/forms/labels/
`search-input`, `search-box`	APG search landmark	https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/search.html
`search-simple-pager`	No APG pattern: WAI menus tutorial, with the APG navigation landmark and breadcrumb examples for `aria-current`	https://www.w3.org/WAI/tutorials/menus/structure/, https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/navigation.html, https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/examples/breadcrumb/
`search-root` announcements, `search-result-summary`, `search-no-results-message`, `search-loading-indicator`	No APG pattern: WCAG technique ARIA22, Understanding 4.1.3. The `role="status"` region belongs to the root. These elements set no role.	https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA22 and https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html
`search-dialog-pane` with `modal`	APG modal dialog	https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/dialog/ and https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
`search-dialog-pane` without `modal`, `search-dialog-toggle`	APG disclosure, with `aria-expanded` and `aria-controls`. The modal dialog example for focus returning to the toggle.	https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-faq/
`search-results`, result elements	No APG pattern: list structure, WCAG 1.3.1	None
Layout Builder and component layouts	Understanding 1.4.10 Reflow	https://www.w3.org/WAI/WCAG22/Understanding/reflow.html

To check a story, open its Accessibility panel in Storybook, which runs axe-core on the story.

Accessibility ​

What the elements do ​

Attributes that name things ​

Focus ​