The Atomic library is designed with close attention to accessibility to adhere to the ARIA guidelines and follow the WCAG. While developing Atomic, we try to make the user experience with screen readers as comfortable and consistent as possible, this is why we test the library with the following screen readers:

However, since Atomic is a customizable library that cannot control a webpage entirely, it can only control some parts of the accessibility experience. This article explains a few things you can do to improve the accessibility of your own search interfaces when using Atomic.

Improve Contrast Ratios

For accessibility, we recommend that you ensure that color contrast ratios in your interface are WCAG AA conformant (see Success Criterion 1.4.3: Contrast (Minimum)).

If you’re using the theme included with Atomic (coveo.css) you can ensure that Atomic is conformant by replacing it with the accessibility theme (accessible.css) instead.

Otherwise, we recommend that you customize colors and font sizes in your interface to be conformant (see Themes and Visual Customization).

Add Headings

According to a survey by WebAIM, 67.7% of respondents were more likely to navigate by headings first when trying to find information in a lengthy webpage. Since Atomic is a components-based library you can use to divide your search interfaces as you desire, the components do not include headings. We recommend that you add headings to make it easy for screen reader users to jump between relevant sections of your page.

    .screen-reader-only {
      height: 0;
      margin: 0;
      overflow: hidden;
    <h1 class="screen-reader-only">Search</h1>
    <h1 class="screen-reader-only">Summary</h1>
    <h1 class="screen-reader-only">Facets</h1>
      <h2 class="screen-reader-only">Brand</h2>
      <atomic-facet field="ec_brand" label="Brand"></atomic-facet>
      <h2 class="screen-reader-only">Rating</h2>
      <atomic-rating-facet field="ec_rating" label="Rating"></atomic-rating-facet>
    <h1 class="screen-reader-only">Results</h1>
    <atomic-result-list display="grid">

Use atomic-aria-live

To notify screen reader users of some changes (e.g., the result list being updated), a webpage needs an ARIA live region. By default, the search interface will define one, but due to some limitations when aria-live is inside the search interface, it may behave inconsistently on some screen readers.

We recommend that you add an atomic-aria-live element outside of the search interface, so every Atomic component that needs it will automatically detect it.

We don’t recommend dynamically adding or removing this element from the page because it could lead to screen readers losing track of it. We rather recommend including atomic-aria-live during the initial rendering of the page.


Improve Result Accessibility

Since results are highly customizable, the relevant components offer limited out-of-the-box accessibility support. However, we recommend the following to help you provide an accessible experience for your users.

Reorder Result Sections


This is only relevant if you use result sections in your result template.

While the visual order of sections is independent of the order in which they were defined in the template, screen readers will try reading sections in the order they are defined. As such, we recommend that you order result sections from most important to least important, with the title section being the most important. This order is highly subjective, so we recommend that you take inspiration from other accessible search pages with a purpose similar to yours.


Hide the Thumbnail

Your results may include not only a detailed title, but also a thumbnail. If your title accurately describes what is depicted in a thumbnail, that means the thumbnail doesn’t contain additional information for screen readers.

In such a case, the thumbnail would slow down navigation for screen reader users so we recommend that you hide the thumbnail from screen readers.

Achieve this by setting its aria-hidden property to true.


Add Roles

We recommend that you add semantic roles to certain result components to better communicate to screen readers what they represent in your particular template. However, be aware that adding a role to a component overwrites its original role and that screen readers may expect some roles to have specific children or support specific keyboard shortcuts.

In general, we recommend making the following adjustments:

  • Add the role="grid" property to the element containing all your fields and:

    • Wrap each field label-value pair in an element with the role="row" property.

    • Add the role="rowheader" property to each field label.

    • Add the role="cell" property to each field value.

  <atomic-result-fields-list role="grid">
    <div role="row">
      <span role="rowheader">Priority:&nbsp;</span>
      <atomic-result-text field="priority" role="cell"></atomic-result-text>
    <atomic-field-condition if-defined="deadline" role="row">
      <span role="rowheader">Deadline:&nbsp;</span>
      <atomic-result-date field="deadline" role="cell"></atomic-result-date>
  • Add the role="note" property to atomic-result-badge components.

<atomic-result-badge field="special" role="note"></atomic-result-badge>
What's next for me?