Custom Widgets (JavaScript, ARIA)
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), oraria-labelledby)Frames, via the
titleattributeIframes, via the
titleattribute
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, oraria-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
Instructions
Instructions for Custom Widgets: Widgets with non-standard interaction models SHOULD have instructions explaining how to use them.
best practice
Custom Widgets
Accordion widgets SHOULD conform to WAI-ARIA Authoring Practices for Accordions.
best practice
Autocomplete widgets SHOULD conform to WAI-ARIA Authoring Practices for Autocomplete widgets.
best practice
Carousel widgets (based on a Tab Panel) SHOULD conform to WAI-ARIA Authoring Practices for Tab Panels.
best practice
Checkbox (Tri-State) widgets SHOULD conform to WAI-ARIA Authoring Practices for Checkboxes.
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
Grid widgets (Interactive Tabular Data and Layout Containers) SHOULD conform to WAI-ARIA Authoring Practices for Grids.
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 (Multi-Thumb) widgets SHOULD conform to WAI-ARIA Authoring Practices for Multi-Thumb Sliders.
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
Window Splitter widgets SHOULD conform to WAI-ARIA Authoring Practices for Window Splitters.
best practice
Last updated
Was this helpful?