Users of assistive technologies must understand what a custom control is and what it does. Custom controls that lack accessibility information become difficult or impossible to understand or operate. Using WAI-ARIA provides a way to fill in missing accessibility information so that assistive technologies can recognize custom controls as controls and not as div or span elements without semantic meaning or value.
- Provide an accessible name for each custom component. An accessible name is effectively the label for a control, explaining what it does. For custom components, the corresponding design pattern defines the best way to provide the accessible name.
- Provide controls for which the visible text label matches the accessible name. [Note: The programmatic label of a control is its accessible name.] When the accessible name is different from the visible label, it essentially becomes an unknown hidden command for speech input users that can be accidentally activated without the user knowing what has happened.
- Provide an accessible role for each custom component. WAI-ARIA defines a large number of values for the role attribute, which are used by assistive technologies to convey the component’s purpose. Give each custom control a suitable role attribute, such as role="button" for custom buttons or role="slider" for slider widgets.
- Provide and maintain an accurate states and values for each custom component. This means giving custom form components, such as sliders, suitable values that represent their current value plus any additional required values, such as maximum and minimum possible. For controls that change visual appearance, such as a menu item with an associated dropdown menu or a button that is a show/hide toggle button for additional content, their current state must reflect whether their associated content is shown.
These are links to design patterns for selected controls and UI widgets:
- Button
- Menu button
- Slider
- Accordion (a set of expandable/collapsible content panels)
- Date picker (calendar)
- Drag and Drop
- Grid (a navigable tabular collection of data) and sortable grid
- Modal dialog box
- Site navigator (navigation bar)
- Tabbed interface
- Tooltip
- Tree view (navigation feature)
Testing
Use a code inspector (see the Tools page for examples) to query each interactive control for its name, role, and current state or value information.
- Is this information provided?
- If so, is it accurate?
- Does the visible name match the accessible name?
- When you interact with the control, is its current state and value updated?
Validate your answers by using a screen reader to interact with the widget. Is this accessibility information exposed meaningfully and understandably?
More information
- Understanding SC 2.5.3—Label in Name (WAI)
- Understanding SC 4.1.2—Name, Role, Value (WAI)
- Léonie Watson: Understanding Screen Reader Interaction Modes (useful background information on how screen readers render web content)
- Accessible Name Calculation (HTML to Platform Accessibility APIs Implementation Guide)—detailed description of accessible name-calculation for elements