Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Forms and Accessibility

Accessibility Basics for Lit Components

Make Lit and web components accessible: native elements first, ARIA roles and states, delegatesFocus, labels across shadow DOM, keyboard support and ElementInternals ARIA.

An accessible component works for everyone: people who use only a keyboard, screen reader users, people who zoom or use high-contrast modes. Custom elements start with no built-in semantics at all; to a screen reader <my-button> is an anonymous box. That makes accessibility something you have to design in, not something you get for free.

The good news is that a few habits cover most cases. This lesson goes through them in order of importance, with examples you can run and inspect.

Rule one: use native elements inside

The most reliable accessible component is one that renders native elements. A real <button> already has a role, keyboard activation (Enter and Space), a focus ring and a disabled state. A <div role="button"> has none of those until you add all of them by hand.

Native button versus div

Press Tab in the preview: the good button receives focus and activates with Enter or Space; the div never gets focus at all. Make a habit of asking "which native element does this?" first: button, a, input, select, details, dialog.

Rule two: ARIA only when native is not enough

ARIA (Accessible Rich Internet Applications) attributes describe roles, states and relationships to assistive technology. They change only what is announced, never how an element behaves. So an ARIA role must always come with the matching keyboard and focus behavior.

Common pieces:

Attribute Purpose Example
role What the element is role="switch", role="tablist"
aria-label / aria-labelledby Accessible name an icon-only button
aria-expanded Open or closed a disclosure button
aria-pressed, aria-checked, aria-selected State toggles, tabs
aria-live Announce changes status messages
aria-disabled Not available keeps it focusable

Lit makes dynamic ARIA easy because attribute bindings update automatically.

A disclosure with ARIA

The state is reflected in aria-expanded and in hidden from the same property, so the visual and the announced state cannot drift apart.

The first rule of ARIA: if a native element or attribute already gives you the role, state or property, use it instead. <button aria-expanded> plus real show/hide is better than a custom role.

Labels across shadow boundaries

ID references (for, aria-labelledby, aria-describedby, aria-controls) only resolve within the same tree. A <label for="x"> in the page cannot point at an <input id="x"> inside a component's shadow root, and the reverse is also true. Solutions:

  1. Render the label inside the component from a property or slot, so both are in one tree.
  2. Pass the name down as a property (label="Email") and use aria-label on the inner control.
  3. Use form-associated internals (internals.ariaLabel, or <label> wrapping the host, which works with FACE elements; see Form-Associated Custom Elements).
A labeled field

Both references stay inside one shadow root, so they resolve. A newer platform feature, ARIA element reflection (element.ariaLabelledByElements), can point across boundaries in supporting browsers, but it is not yet a safe baseline, so keep related parts in one tree.

Focus: delegatesFocus and tabindex

By default, calling host.focus() on a custom element does nothing useful, because the host itself is not focusable. Create the shadow root with delegatesFocus: true and the browser forwards focus() (and clicks on non-focusable parts) to the first focusable element inside.

In Lit, set it through shadowRootOptions:

JavaScript
static shadowRootOptions = { ...LitElement.shadowRootOptions, delegatesFocus: true };
delegatesFocus

When the user focuses a custom element, document.activeElement is the host (retargeted); host.shadowRoot.activeElement is the real inner element.

Rules for tabindex: 0 puts an element in the Tab order, -1 makes it focusable by script only, and positive values should never be used.

Keyboard support

Every interactive thing must work without a mouse. Typical expectations:

  • Buttons: Enter and Space. Links: Enter.
  • Menus, tabs, radio groups, listboxes: arrow keys move within the group; Tab moves out of it.
  • Dialogs: Escape closes; focus moves in and returns to the trigger.

Handle keydown in the template and call preventDefault() for keys you consume (arrow keys scroll the page otherwise). The next lesson builds full patterns.

Semantics on the host with ElementInternals

Instead of putting role and aria-* attributes on the host (where the page author can overwrite them), ElementInternals can hold default semantics. Page authors can still override them with real attributes.

Default role through ElementInternals

ARIA reflection through internals is widely supported in current evergreen browsers. Where you must support older ones, fall back to attributes on the host.

Respect user preferences

Accessibility also covers motion and contrast. Inside a component's styles:

CSS
@media (prefers-reduced-motion: reduce) {
  * { animation: none !important; transition: none !important; }
}
@media (forced-colors: active) {
  button { border: 1px solid ButtonText; }
}

Do not remove focus outlines without replacing them; use :focus-visible to show a clear ring for keyboard users only.

A quick checklist

  • Native element used wherever one fits.
  • Every control has an accessible name (visible label, aria-label, or aria-labelledby within one tree).
  • State is exposed (aria-expanded, aria-checked...) and updated from the same property that drives the UI.
  • Tab reaches every control; arrows work in composite widgets; Escape closes overlays.
  • Focus is never lost: after closing something, return focus to its opener.
  • Color is not the only signal; contrast is sufficient.
  • Test with a keyboard, a screen reader, and 200% zoom.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is <button> preferable to <div role="button" tabindex="0"> inside a component?

    Native elements bring semantics and behavior; a div needs all of it re-implemented and tested.
  2. 2. A <label for="x"> is in the page and <input id="x"> is inside a component's shadow root. What happens?

    ID references do not cross shadow boundaries; keep label and control in one tree or pass the name as a property.
  3. 3. What does delegatesFocus: true do?

    With delegatesFocus the host becomes a focus proxy to its first focusable internal element.
  4. 4. Where can a component keep default ARIA semantics that the page author may still override?

    Internals hold default semantics; real attributes on the host take precedence.

Summary

  • Custom elements have no built-in semantics: render native elements and add ARIA only when needed.
  • Keep ID references (labels, aria-describedby) within one shadow tree.
  • Use delegatesFocus, proper tabindex and full keyboard support.
  • ElementInternals provides overridable default role and ARIA state.
  • Respect reduced motion, forced colors and visible focus.

Next: Accessible Widget Patterns