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).

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

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.

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.

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.

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.)

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.

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)

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.

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.

Focus Target Has Text: When moving or setting focus, the destination element MUST contain discernible text (either standard text or programmatically-associated text).

Keyboard Conventions

best practice

Instructions

Instructions for Custom Widgets: Widgets with non-standard interaction models SHOULD have instructions explaining how to use them.

best practice

Required multiple

Custom Widgets

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

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

Table (Sortable) widgets SHOULD be constructed of a standard HTML table, if possible, and make full use of ARIA sort attributes.

best practice

PreviousDynamic Content (JavaScript, AJAX)NextCAPTCHA

Last updated 5 years ago

Was this helpful?

Custom Widgets (JavaScript, ARIA)

Topic

Technique

WCAG AA Requirement

Name

Required

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

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

Other Semantic Elements Benefitting from a Name: Examples of other semantic elements that SHOULD have an accessible name, according to the 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

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

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

Required

Required (WCAG 2.0) (WCAG 2.1)

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 2.0) (WCAG 2.1)

Keyboard Focus Management During Interactions

Required

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

Focus Target Has Text: When moving or setting focus, the destination element MUST contain discernible text (either standard text or programmatically-associated text).

Required

Keyboard Conventions

See

best practice

Instructions

Instructions for Custom Widgets: Widgets with non-standard interaction models SHOULD have instructions explaining how to use them.

best practice