Accessibility

Search Web Components gives every control an accessible name, announces each search to screen readers, and keeps keyboard focus in place. For the developer detail, see Accessibility for developers.

Keyboard and page structure

Each component follows the W3C pattern for its kind of control, so keyboard and screen reader users meet the controls they know:

• The search forms are search landmarks, and the pager is a navigation landmark that marks the current page. A screen reader user jumps to them by landmark.
• A facet's options are grouped under the facet's label, as checkboxes, radios, or toggle buttons. A collapsible facet label and a show more button tell whether their options are open.
• The HTML dropdowns, Facet: Dropdown HTML and Sort and Results per page shown as html, are select-only comboboxes: the arrow keys, Home, End, Page Up, and Page Down move through the options, typing jumps to an option, Enter or Space picks it, and Escape closes the list. With several values allowed, Tab closes the list and keeps the selection.
• After a search, keyboard focus stays on the control used, e.g., the facet option just checked, also when the options change order. When that control goes away, e.g., the last applied filter, focus moves to a control nearby.
• The filter dialog is named, its toggle tells whether it is open, and Escape closes it. A modal dialog keeps focus inside until it is closed.
• Each search is announced to screen readers: the number of results, that there are none, or that the search failed.

For every pattern and where focus goes, see Accessibility for developers.

Fields that start with A11y:

Block and Canvas fields whose titles start with A11y: hold text that only screen readers announce. The text never shows on screen. On the Layout Builder layouts the same texts are in the Screen reader announcements group. A field with a default shows the default as a placeholder. A field left empty uses its default.

What to set

• A name for the search input. Without one, the input is named by its placeholder, then by its submit button. Set A11y: Search input name on the Search Input and Search Box blocks, or ariaLabelText from Twig.

• Names when a search page has two of something. Each of these needs its own name when a search page has two:

  • Search forms, e.g., a header Search Box and a Search Input. Set A11y: Search area name, or landmarkLabelText from Twig.
  • Pagers. Set A11y: Pager name.
  • Results lists. Set A11y: Results list name.

• Translated text from Twig and Canvas. The blocks and the Layout Builder layouts pass translated screen reader text. A component placed from Canvas or included from Twig uses the element's English text until the prop is set, e.g., ariaLabelText: 'Pages'|t on search_web_components:search-simple-pager.

• Your own announcement. The announcement has two texts, "One result" and "Two or more results". Turn the announcement off on a search page that announces its own result count, or in a language with more plural forms: check A11y: Do not announce searches on the layout, or set noSearchAnnouncement on search-root. A search-root subclass can instead override _getSearchAnnouncementText(), see Plural forms.

• A message after a failed search. After a failed search, the search root has the class search-error and the No Results Message shows. No error message shows on screen. Screen readers hear "The search could not be completed. Try again." Set Search failed on the layout to change that text. To show your own message, style it to show while the root has search-error. If the No Results Message text does not fit a failure, hide it while the root has search-error:

  search-root.search-error search-no-results-message {
    display: none;
  }

• Styles. The components ship no CSS. The layouts ship only the CSS for their columns. Focus indicators, contrast, and target sizes come from the theme, and the HTML dropdowns need a few classes styled. For the classes, see Styling.

• A screen reader check. The components are tested with axe-core and keyboard tests in Chrome, not with a screen reader. Try your search page with NVDA or VoiceOver before launch.