Components
Accessibility
How the components handle keyboard, focus and assistive technology, and what remains your responsibility.
Principles
-
Native elements first:
<button>,<dialog>,<details>,<select>and real inputs. The browser provides focus, keyboard and announcements. -
Every field has a visible label linked to its input; hints and errors are linked with
aria-describedby. -
Focus stays visible with
focus-visiblerings, and animations stop underprefers-reduced-motion. - Colors of tones and states keep readable contrast in light and dark mode.
Your part
-
Give icon-only buttons an accessible name with
attributes: {'aria-label': …}. -
Keep
idvalues unique on the page: labels and descriptions rely on them. - Check contrast again when you change the theme colors.
Actions
Button
-
A native
<button type="button">: focusable, activated with Enter and Space. -
A visible focus ring appears on keyboard focus only (
focus-visible). -
While loading,
aria-busy="true"is set and the spinner is hidden from screen readers. -
A disabled link has no
hrefand carriesrole="link"andaria-disabled="true". -
For an icon-only button, give it a name:
attributes: {'aria-label': 'Close'}.
Layout
Card
-
The title is a real heading (
h3by default), so cards show up in the page outline. -
Set
titleLevelso headings never skip a level.
Divider
-
Without a label it is an
<hr>, announced as a separator. -
With a label it carries
role="separator"; the lines are hidden from screen readers and the label is read.
Accordion
-
Each header is a native
<summary>: focusable, toggled with Enter and Space, announced as expanded or collapsed. -
The chevron is decorative (
aria-hidden). - The chevron rotation is disabled when the system asks for reduced motion.
Forms
Text field
-
The
<label for>names the input; the hint or the error is linked witharia-describedby. -
An error sets
aria-invalid="true"and a red border, so the state never relies on color alone: the message is text. - The required asterisk is decorative: the input itself is announced as required.
- The focus ring uses a ring around the border, visible in light and dark mode.
Text area
-
Same wiring as the text field:
label for,aria-describedby,aria-invalid.
Select
-
A native
<select>: the system list, typeahead and arrow keys work everywhere, including on phones. - The chevron is decorative and does not catch clicks.
Checkbox
-
A native checkbox inside its
<label>: the whole text is clickable and Space toggles it. -
Group related checkboxes in a
<fieldset>with a<legend>.
Switch
-
A real checkbox with
role="switch", visually hidden but focusable: Space toggles it and screen readers announce "on" or "off". -
The focus ring is drawn on the track with
peer-focus-visible:. - The thumb does not slide when the system asks for reduced motion.
Radio group
-
A
<fieldset>and<legend>: screen readers announce the question with each option. - Native radios: arrow keys move between options, Tab leaves the group.
Combobox
- The suggestion list is drawn by the browser and the system: keyboard, touch and screen readers work as on any native field.
-
Same wiring as the text field:
label for,aria-describedby,aria-invalid.
Segmented control
-
Native radios in a
<fieldset>with a<legend>: arrow keys move the selection, Tab leaves the group. - The radios are visually hidden, not removed; the focus ring is drawn on the visible segment.
Slider
-
A native
type="range": arrow keys, Page Up/Down, Home and End work everywhere. -
With a
unit,aria-valuetextreads "40%" instead of "40". -
The value is in an
<output for>linked to the input.
Date field
-
Same wiring as the text field:
label for,aria-describedby,aria-invalid. - Each part (day, month, year) is reachable and editable with the keyboard.
Feedback
Alert
-
warninganddangercarryrole="alert"(announced at once); the othersrole="status"(announced politely). - The tone is also carried by the text and the thick left border, not by color alone.
- In dark mode, tones switch to light text on a deep tint.
Badge
-
Plain text in a
<span>: the label is read as is. Keep it meaningful without its color. - Tones use dark text on a light tint (contrast above 7:1).
Spinner
-
With a label, it is a
role="status"region with screen-reader-only text. - It stops spinning when the system asks for reduced motion.
Progress bar
-
role="progressbar"witharia-valuenow,aria-valuemin,aria-valuemaxandaria-label. -
Indeterminate: no value is announced and
aria-busy="true"is set. - With reduced motion, the indeterminate bar pulses in place instead of sliding.
Skeleton
-
Hidden from screen readers (
aria-hidden). Mark the loading region witharia-busy="true". - The pulse stops when the system asks for reduced motion.
Empty state
-
The icon is decorative (
aria-hidden); the title and text carry the message.
Toast
-
Each toast is
role="status", orrole="alert"forwarninganddanger. - Render the region when the page loads, even empty: live regions are only announced when they already exist.
- Leave toasts on screen long enough to be read (five seconds or more), and never put the only way to do something in a toast.
- The slide-up is disabled when the system asks for reduced motion.
Data display
Avatar
-
With a picture, the image
altis the name; with initials, the avatar isrole="img"with anaria-label. - Initials are hidden from screen readers, so the full name is read instead of letters.
Tooltip
-
It appears on hover and on keyboard focus inside the wrapper (
group-focus-within:). -
The bubble has
role="tooltip". Give it anidand passJxTooltip.describedBy(id)to the child so screen readers read it. -
Give icon-only buttons their own
aria-label. - In the browser, Escape hides the bubble until the pointer or the focus leaves (WCAG 1.4.13).
Keyboard key
-
A
<kbd>element, read as text.
Data table
-
A real
<table>with<caption>and<th scope="col">. -
Sortable headers are buttons inside the
<th>, which carriesaria-sort="ascending"or"descending". -
The sort arrow is decorative; the direction is exposed by
aria-sort.
Stat
-
A description list (
dl,dt,dd): the label is announced with its value. - The trend is said in words ("Increase: +12%"), the arrow is decorative: color is never the only signal.
Navigation
Breadcrumbs
-
A
<nav>landmark named "Breadcrumb" with an ordered list. -
The last step carries
aria-current="page"; separators are hidden from screen readers.
Pagination
-
A
<nav>landmark; the current page carriesaria-current="page". -
At the ends, previous or next is disabled (
aria-disabled, removed from the tab order for links). - Gaps (…) are hidden from screen readers.
Tabs
-
role="tablist",tabandtabpanel, linked byaria-controlsandaria-labelledby; the selected tab hasaria-selected="true". - Only the selected tab is in the tab order: Left and Right (Up and Down when vertical) move and select, Home and End jump to the ends, disabled tabs are skipped.
-
Vertical lists carry
aria-orientation="vertical". - Panels are focusable, so keyboard users reach content without interactive elements.
Steps
-
An ordered list
<ol>with anaria-label: screen readers announce the number of steps. -
The current step has
aria-current="step"; complete steps end with a hidden ", completed". -
Numbers, check marks and connectors are decorative (
aria-hidden).
Overlays
Modal
- Native modal: focus moves inside and stays there, the page behind is inert, Escape closes it and focus returns to the trigger.
- Named by its title, described by its description.
- The fade-in is disabled when the system asks for reduced motion.
Drawer
- Same as the modal: focus kept inside, Escape closes, page behind inert, focus returned to the trigger.
- The slide-in is disabled when the system asks for reduced motion.
Dropdown menu
-
A disclosure: the trigger is a native
<summary>announced as expanded or collapsed; Tab moves through the entries. -
Entries are real links and buttons; a disabled link loses its
hrefand getsaria-disabled. - In the browser, Escape closes the list and gives the focus back to the trigger; a click or tap outside closes it too.