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-visible rings, and animations stop under prefers-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 id values 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 href and carries role="link" and aria-disabled="true".
  • For an icon-only button, give it a name: attributes: {'aria-label': 'Close'}.

Layout

Card

  • The title is a real heading (h3 by default), so cards show up in the page outline.
  • Set titleLevel so 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 with aria-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-valuetext reads "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

  • warning and danger carry role="alert" (announced at once); the others role="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" with aria-valuenow, aria-valuemin, aria-valuemax and aria-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 with aria-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", or role="alert" for warning and danger.
  • 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 alt is the name; with initials, the avatar is role="img" with an aria-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 an id and pass JxTooltip.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 carries aria-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.

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 carries aria-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", tab and tabpanel, linked by aria-controls and aria-labelledby; the selected tab has aria-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 an aria-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 href and gets aria-disabled.
  • In the browser, Escape closes the list and gives the focus back to the trigger; a click or tap outside closes it too.