Skip to content

list-box: missing roles and properties #154

Closed

Description

@TetraLogicalHelpdesk

WCAG Level

Level A

Priority

High

Pages/screens/components affected

Description

A listbox must expose its purpose and state programmatically so that users of assistive technologies such as screen readers are able to understand the purpose, current state, and method of interaction with the component.

There are a number of issues with the vaadin-list-box component, combined in this issue as they are related and have overlapping effects; they therefore should be corrected together to achieve an accessible outcome.

User impact

Assistive technology users navigating through the listboxes won't know which of the options is selected or how many options can be selected (i.e. if it a single or multi-select listbox).

Required solution

Ensure that all information about the component, from its role to its current state, are exposed programmatically.

Implementation guidance

The List Box component displays a list of multiple items, zero, one, or more of which can be selected, depending on the configuration of the component. It is similar to a native <select> element with a size attribute value greater than "1" and an option multiple attribute.

The documentation, however, indicates that it is not intended to be used as form control and therefore does not require an accessible name for the component as a whole, and this has led to implementation decisions that unfortunately make it inaccessible.

The custom item presentation variation of the list box, showing an image and two lines of text to describe each option

<list-box-custom-item-presentation-imported>
  # shadow-root
  <vaadin-list-box multiple="" role="list" aria-orientation="vertical">
    # shadow-root
    <div part="items">
      <slot></slot>
    </div>
    # end shadow-root

    <vaadin-item aria-selected="true" tabindex="0" selected="" active="">
      # shadow-root
      <div part="items">
        <slot></slot>
      </div>
      # end shadow-root

      <div style="display: flex;">
        <img style="…" src="data:image/jpeg;base64,…" alt="Portrait of Aria Bailey">
        <div>
          Aria Bailey
          <div style="…">
            Manager of Department of Pulmonology
          </div>
        </div>
      </div>
    </vaadin-item>

    <vaadin-item aria-selected="false" tabindex="-1">
      # shadow-root
      <div part="items">
        <slot></slot>
      </div>
      # end shadow-root

      <div style="display: flex;">
        <img style="…" src="data:image/jpeg;base64,…" alt="Portrait of Aaliyah Butler">
        <div>
          Aaliyah Butler
          <div style="…">
            Manager of Department of Pediatric
          </div>
        </div>
      </div>
    </vaadin-item>

    <vaadin-item aria-selected="true" tabindex="-1" selected="">
      # shadow-root
      <div part="items">
        <slot></slot>
      </div>
      # end shadow-root

      <div style="display: flex;">
        <img style="…" src="data:image/jpeg;base64,…" alt="Portrait of Eleanor Price">
        <div>
          Eleanor Price
          <div style="…">
            Pediatrician
          </div>
        </div>
      </div>
    </vaadin-item>
    …
  </vaadin-list-box>
  # end shadow-root
</list-box-custom-item-presentation-imported>

This is a complex component, with multiple nested elements with their own shadow DOM, but the basic structure is that the <vaadin-list-box> element has a role="list" and contains <vaadin-item> elements. These <vaadin-item> elements have an aria-selected attribute, which is either "true" or "false" depending on whether the item is selected or not.

The first issue is that the <vaadin-item> elements do not have a role and therefore default to being presentational elements in the accessibility tree. The consequence is that despite the aria-selected their state is not exposed, not will screen readers announce that they can be interacted with, to either select or deselect them.

The only permitted child role of a list is a listitem, however aria-selected is not a permitted attribute for an element with a listitem role. This role indicates that an element is an item in a list (as the name suggests), but not that it interactive in any way.

Further, there is no indication that either single or multiple items can be selected.

The usual solution for these issues would be to use a listbox role. The required child elements of listbox have a role of option, and elements with an option role can take an aria-selected attribute because they are exposed as interactive elements. An element with a role of listbox may also take an aria-multiselectable="true" attribute to indicate that multiple options can be selected; its absence or a value of "false" indicate that only one option can be selected. The result would look like:

<list-box-custom-item-presentation-imported>
  <div id="vaadin-list-box-label">Staff members</div>
  <vaadin-list-box role="listbox" aria-multiselectable="true" aria-orientation="vertical" aria-labelledby="vaadin-list-box-label" aria-activedescendant="opt-2" tabindex="0">
    <vaadin-item role="option" aria-selected="false" id="opt-1">Aria Bailey</vaadin-item>
    <vaadin-item role="option" aria-selected="true" id="opt-2">Aaliyah Butler</vaadin-item>

    <vaadin-item role="option" aria-selected="true" id="opt-3">Eleanor Price</vaadin-item>
    …
  </vaadin-list-box>
</list-box-custom-item-presentation-imported>

The standard keyboard behaviour when using the listbox role in this way is to have the listbox focusable but the individual option elements unfocusable, instead requiring the use of arrow keys to navigate through the content. You've implemented something similar with a roving tabindex, but it could be simplified as per W3C WAI-ARIA Authoring Practices 1.1 Example Listboxes with Rearrangeable Options, which uses the aria-activedescendant property to indicate which option currently has virtual focus.

Note, however that this example has an aria-labelledby attribute that references the id of a <div> element with a text label. This is because elements with a role of listbox require an accessible name in the same way as form elements.

As this you have stated the lack of an accessible name as a stated difference between this and other components there are few options available to you.

The first is to require an accessible name, as this enables you to use this pattern in the way that it is commonly used and understood.

Another alternative is to reimplement this in a way similar to either the Checkbox or Radio Button components, depending on whether they are multi or single-select. However while it could be argued that in this circumstances the group of controls does not require an group label, as there isn't a visual label, there is still the visual appearance of a group and therefore that would need to be exposed in some way such as containing them within a list.

Similar to using Checkbox or Radio Button components, the third option is to treat each one as a toggle button. As with the Checkbox or Radio Button component approach, you would need to indicate that the individual controls are part of a group. It would look like:

<ul>
  <li><button aria-pressed="false">Aria Bailey</button></li>
  <li><button aria-pressed="true">Aaliyah Butler</button></li>
  <li><button aria-pressed="true">Eleanor Price</button></li>
  …
</ul>

This has a similar problem to the lack of visible label, in that there is no good way to indicate how many can be selected at a time. This is not necessarily a problem as this information is not conveyed in any of the examples given either. Additionally, while it could be implemented so that when one is selected the others are deselected, but that would not automatically be announced by a screen reader without implementing a live region to announce the changing state.

Test procedure(s)

Use these steps to confirm that the solution has been correctly applied to issues identified within the test sample, and to test the rest of the website for instances of the same issue:

  1. Turn on your screen reader
  2. Navigate through the list box component
  3. Make sure that it is possible to navigate through the options
  4. Make sure that the current state of each option is announced

Definition of done

Complete all of these tasks before closing this issue or indicating it is ready for retest:

  • All issues identified within the test sample have been resolved.
  • The rest of the components, their variants, and the documentation website have been tested for the same issue.
  • All issues identified throughout the rest of the components/website have been resolved or filed as new issues.

Related standards

More information

Test data

Test date: March 2021
Website: vaadin.com/components, vaadin.com/docs-beta

Activity

  1. rolfsmeds commented on Dec 21, 2021

    @rolfsmeds
    Contributor

    Decided to research what would be needed to fix this: dynamically changing aria-attributes depending on mode, or something.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    a11yAccessibility issuea11y phase 3Candidates for a 23.1 batch of a11y fixesneeds researchMore information needed to estimatevaadin-list-box

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions