Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 39 ยท Forms and Accessibility

ARIA and ElementInternals for Accessible Components

Give custom elements roles, names and states for assistive technology using ElementInternals ARIA properties, default semantics and custom :state() pseudo-classes.

A browser knows that <button> is a button because the element name carries meaning. A custom element named <x-switch> carries none. To screen readers it is just a generic container, so keyboard users and assistive technology cannot tell what it does. Your job as a component author is to supply the semantics the browser cannot guess: a role, a name, and the current state.

You can do it with ARIA attributes on the host, but the modern approach is ElementInternals, which sets default semantics from inside the component without writing attributes onto the host that the page owner might override or be confused by.

Roles, names and states

Three questions every interactive component must answer for assistive tech:

  1. Role: what is it? (switch, slider, tab, listbox, dialog...)
  2. Name: what is it called? (from a label, aria-label or content)
  3. State and value: what is it doing now? (aria-checked, aria-expanded, aria-valuenow...)

A fourth requirement is keyboard operability, covered in Focus and Keyboard Support. Roles promise behavior; you must implement it.

An ARIA role does not add behavior. Writing role="switch" on a div does not make it focusable or respond to Space. If you can use a native element, do: a wrapped <button> or <input type="checkbox"> gives you focus, keyboard and semantics for free.

Default semantics with ElementInternals

ElementInternals mirrors the ARIA attributes as camel-cased properties: role, ariaChecked, ariaExpanded, ariaLabel, ariaValueNow, ariaDisabled and the rest. Values are strings, like the attributes. They act as defaults: if the page author puts a real attribute on the host, the attribute wins.

A switch with internal ARIA

Click or press Tab then Space. The log shows the role and checked state that a screen reader would be told. The visual "on" look comes from a custom state (:state(on)), explained next. The try/catch falls back to a data attribute in browsers that do not yet support states as a set; real code usually picks one approach.

Custom states: internals.states

Native elements expose states through pseudo-classes (:checked, :disabled, :open). A custom element can do the same. Add a token to internals.states and style it with :state(token):

JavaScript
this.#i.states.add("loading");   // matches :state(loading)
this.#i.states.delete("loading");
CSS
x-button:state(loading) { opacity: .6; cursor: progress; }

Because the state lives in the internals, outsiders cannot corrupt it, and your visual state does not leak into the DOM as extra attributes. Where :state() is unavailable, fall back to a reflected attribute, as in the demo.

Names from labels

A form-associated control can be named by a <label>. The internals.labels list gives you those labels, and the browser wires the accessible name for you when the element is form-associated and labelable. For others, set ariaLabel from an attribute or a slot's text:

JavaScript
this.#i.ariaLabel = this.getAttribute("label") ?? this.textContent.trim();

If the visible text already says what the control is (as with "Wi-Fi" in the demo), the content becomes the name automatically for roles that allow name from content, such as switch and button.

Live regions

When a component changes something the user does not directly focus on (a toast, a validation message, a loading indicator) announce it. A role="status" element (polite) or role="alert" (assertive) inside the component does that.

Announcing changes with a live region

A screen reader will speak the status text when it changes. Keep the live region in the DOM from the start; inserting a new live region and filling it at the same moment is unreliable.

Testing your semantics

  • Open the browser's Accessibility panel in DevTools and inspect the host: check role, name and state.
  • Tab through the page using only the keyboard.
  • Try a screen reader (VoiceOver, NVDA, Narrator) for at least a quick pass.
  • Remember that shadow DOM boundaries affect ARIA references such as aria-labelledby="id" and for: IDs do not cross a shadow root, so a label outside cannot point at an element inside. Use internals.labels, aria-label, or put the labelled element in the same tree.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does role="switch" on a div do by itself?

    ARIA roles describe semantics only. Focus and keyboard handling must be coded.
  2. 2. What is the benefit of ElementInternals ARIA properties?

    Internals provide defaults from inside the component, and a real attribute on the host can still override them.
  3. 3. How do you style a custom state added with states.add("loading")?

    Custom states match the :state() pseudo-class.
  4. 4. Why keep a role="status" region in the DOM from the start?

    Assistive tech watches existing live regions for changes; a region created and filled at once is often missed.

Summary

  • Supply role, name and state; the browser cannot infer them for a custom tag.
  • ElementInternals offers default ARIA properties and states for :state() styling.
  • Prefer native elements inside your component whenever they fit.
  • Use live regions for announcements and test with DevTools and a screen reader.

Next: Focus and Keyboard Support