Custom Widgets (JavaScript, ARIA)

Accessibility Techniques for Custom Controls
Topic Technique WCAG AA Requirement
Name

Name of Interactive UI Elements: Every interactive UI element (e.g. links, buttons, controls for custom widgets, form inputs/elements) MUST have a name, according to the accessible name computation.

Note: The name can come from the native text of the element (e.g. link text, <button> text), a value attribute (e.g. <input type="submit" value="Name goes here">), the aria-label text, the text referred to via the aria-labelledby ID value, or other attributes, such as title (depending on context).
Required
WCAG 4.1.2

Name of Static Semantic Elements: The following semantic elements MUST have an accessible name, according to the accessible name computation:

  • Headings (or elements with role="heading")
  • Images (or elements with role="image")
  • Links (or elements with role="link"), via link text, aria-label (e.g. when the link contains only a background image), or aria-labelledby)
  • Frames, via the title attribute
  • Iframes, via the title attribute
Required
WCAG 4.1.2

Other Semantic Elements Benefitting from a Name: Examples of other semantic elements that SHOULD have an accessible name, according to the accessible name computation include:

  • Landmarks (HTML 5 or ARIA landmarks); Names are especially helpful when there are two of the same type of landmark on the same page, such as two navigation landmarks
  • Tables (via <caption>, aria-label, or aria-labelledby)
best practice
Role Role Specified: The semantic meaning of elements MUST be communicated via appropriate native HTML element or ARIA role. Required
WCAG 4.1.2
HTML versus ARIA Role: When an HTML element exists, the HTML element SHOULD be used instead of the equivalent ARIA role, whenever possible. best practice
Value Static ARIA Properties: Static ARIA properties (e.g. aria-valuemax), MUST be specified. Required
WCAG 4.1.2

Static Non-ARIA Properties: Static non-ARIA properties MUST be specified in text (or alternative text).

Note: The static property may be included in the native text of an element, in its label, in associated text (e.g. via aria-describedby), in adjacent text, or in some other way that is available to assistive technologies.

Required
WCAG 4.1.2
Initial State: The initial state of a changeable UI element MUST be programmatically designated (e.g. via ARIA attributes such as aria-expanded="false", aria-selected="true", aria-sort="ascending", etc.) Required
WCAG 4.1.2
ARIA State Changes: When the visual and/or functional state of an element changes (e.g. aria-valuenow, aria-pressed, aria-expanded, aria-checked), the ARIA state MUST be change accordingly. Required
WCAG 4.1.2 (WCAG 2.0)
WCAG 4.1.3 (WCAG 2.1)

Non-ARIA State Changes: If a state change cannot be communicated via a change in an ARIA attribute, when the state change is the result of a user action or request, the state change MUST be communicated to the user visually AND MUST be communicated to assistive technologies using a technique such as:

  • aria-live announcement
  • ARIA alert (inject text into a pre-existing container with role="alert")
  • Move keyboard focus to the announcement (warning: moving the focus can be disorienting, so should be used with caution)
Required
WCAG 4.1.2 (WCAG 2.0)
WCAG 4.1.3 (WCAG 2.1)
Keyboard Focus Management During Interactions Set Keyboard Focus: The focus MUST be purposely moved or set (via JavaScript) onto the appropriate element when the user's action requires a change of context or location for effective keyboard or touch interaction. Required
WCAG 2.4.3
No Lost Focus: The focus MUST NOT become lost or reset to the top of the page, except when loading or re-loading a page. Required
WCAG 2.4.3
Focus Target Has Text: When moving or setting focus, the destination element MUST contain discernible text (either standard text or programmatically-associated text). Required
WCAG 1.3.1
Keyboard Conventions See https://www.w3.org/TR/wai-aria-practices-1.1/#keyboard best practice
Instructions Instructions for Custom Widgets: Widgets with non-standard interaction models SHOULD have instructions explaining how to use them. best practice
See also the requirements for Form Inputs, Labels, and Instructions. Required
multiple
Custom Widgets Accordion widgets SHOULD conform to WAI-ARIA Authoring Practices for Accordions. best practice
Alert widgets SHOULD conform to WAI-ARIA Authoring Practices for Alerts. best practice
Alert Dialog widgets SHOULD conform to WAI-ARIA Authoring Practices for Alert Dialogs. best practice
Autocomplete widgets SHOULD conform to WAI-ARIA Authoring Practices for Autocomplete widgets. best practice
Breadcrumb widgets SHOULD conform to WAI-ARIA Authoring Practices for Breadcrumbs. best practice
Button widgets SHOULD conform to WAI-ARIA Authoring Practices for Buttons. best practice
Button (Toggle) SHOULD conform to WAI-ARIA Authoring Practices for Buttons. best practice
Carousel widgets (based on a Tab Panel) SHOULD conform to WAI-ARIA Authoring Practices for Tab Panels. best practice
Checkbox widgets SHOULD conform to WAI-ARIA Authoring Practices for Checkboxes. best practice
Checkbox (Tri-State) widgets SHOULD conform to WAI-ARIA Authoring Practices for Checkboxes. best practice
Combobox widgets SHOULD conform to WAI-ARIA Authoring Practices for Comboboxes. best practice
Dialog (Simple Modal) widgets SHOULD conform to WAI-ARIA Authoring Practices for Modal Dialogs. best practice
Dialog (Simple Alert Modal) widgets SHOULD conform to WAI-ARIA Authoring Practices for Modal Dialogs. best practice
Dialog (Message Modal) widgets SHOULD conform to WAI-ARIA Authoring Practices for Modal Dialogs. best practice
Dialog (Message Alert Modal) widgets SHOULD conform to WAI-ARIA Authoring Practices for Modal Dialogs. best practice
Disclosure (Show/Hide or Expand/Collapse) widgets SHOULD conform to WAI-ARIA Authoring Practices for Disclosures. best practice
Disclosure (Based on Details/Summary) widgets SHOULD conform to WAI-ARIA Authoring Practices for Disclosures. best practice
Feed widgets SHOULD conform to WAI-ARIA Authoring Practices for Feeds. best practice
Grid widgets (Interactive Tabular Data and Layout Containers) SHOULD conform to WAI-ARIA Authoring Practices for Grids. best practice
Link widgets SHOULD conform to WAI-ARIA Authoring Practices for Links. best practice
Listbox widgets SHOULD conform to WAI-ARIA Authoring Practices for List Boxes. best practice
Menu widgets SHOULD conform to WAI-ARIA Authoring Practices for Menus. best practice
Menubar widgets SHOULD conform to WAI-ARIA Authoring Practices for Menubars. best practice
Menu Button widgets SHOULD conform to WAI-ARIA Authoring Practices for Menu Buttons. best practice
Navigation (Hierarchical) widgets with Expand/Collapse widgets SHOULD conform to WAI-ARIA Authoring Practices for Disclosures. best practice
Progress Bar (Bounded) widgets SHOULD conform to WAI-ARIA Authoring Practices for Progress Bars. best practice
Progress Bar (Unbounded) widgets SHOULD conform to WAI-ARIA Authoring Practices for Progress Bars. best practice
Radio and Radio Group widgets SHOULD conform to WAI-ARIA Authoring Practices for Radio Groups. best practice
Slider widgets SHOULD conform to WAI-ARIA Authoring Practices for Sliders. best practice
Slider (Multi-Thumb) widgets SHOULD conform to WAI-ARIA Authoring Practices for Multi-Thumb Sliders. best practice
Spinbutton widgets SHOULD conform to WAI-ARIA Authoring Practices for Spinbuttons. best practice
Tab Panel widgets SHOULD conform to WAI-ARIA Authoring Practices for Tab Panels. best practice
Table widgets SHOULD conform to WAI-ARIA Authoring Practices for Tables. best practice
Table (Responsive, Collapsible) widgets SHOULD maintain data relationships through table structure, list hierarchy, and/or headings. best practice
Table (Sortable) widgets SHOULD be constructed of a standard HTML table, if possible, and make full use of ARIA sort attributes. best practice
Toolbar widgets SHOULD conform to WAI-ARIA Authoring Practices for Toolbars. best practice
Tooltip widgets SHOULD conform to WAI-ARIA Authoring Practices for Tooltips. best practice
Tooltip Dialog widgets SHOULD conform to WAI-ARIA Authoring Practices for Dialogs. best practice
Tree View widgets SHOULD conform to WAI-ARIA Authoring Practices for Tree Views. best practice
Window Splitter widgets SHOULD conform to WAI-ARIA Authoring Practices for Window Splitters. best practice