Guide

Accessibility comes from the platform

mx has no accessibility layer because it doesn't need one. ARIA is plain attributes, semantics come from real elements, and focus, keyboard and announcements are DOM APIs you call directly.

Use the platform#

ARIA attributes and role are plain attributes - they flow through render() and $attrs() like any other. The accessible name of an icon button is one prop. The hard parts - focus management, keyboard interaction, live regions - are platform APIs you call directly, not features a framework gates behind its own abstractions.

A real <button> is already keyboard-operable and announced as a button. A real <label for> already names its input. Reach for ARIA only to fill the gaps the platform leaves - and when you do, mx puts no friction between you and the attribute.

Key ideas

  • Real elements first. A native element brings focus, keys and role with it.
  • ARIA is attributes. No special syntax, but watch how a boolean false behaves.
  • Focus and keys are DOM APIs. inert, .focus() and onkeydown - nothing to wrap.
  • Announce what focus can't see. One live region for changes away from the user.

aria-* and role pass straight through#

There's no special syntax. Put aria-* and role in the attributes object alongside everything else:

aria-attributes.jsJS
let { button } = mx;

// aria-* attributes are just attributes - they pass straight through
button({
    'aria-label': 'Close dialog',
    'aria-expanded': String(open),   // boolean: String keeps "false"; a bare false removes the attr
    'aria-controls': 'menu-1',
    onclick: toggle
}, mx.anIcon({ icon: 'close' }));   // anIcon: your own icon component, not part of mx

Boolean ARIA values

mx sets a boolean true to the string "true" - which is precisely what enumerated ARIA attributes require (aria-hidden="true", not aria-hidden=""). But a boolean false removes the attribute, and for tri-state ARIA that's usually wrong: aria-pressed="false" (a toggle that's off) is a different state from aria-pressed being absent (not a toggle at all):

boolean-aria.jsJS
// mx sets boolean true to the string "true" - exactly what
// enumerated ARIA attributes expect:
mx.div({ 'aria-hidden': true })       // aria-hidden="true"  ✓
mx.div({ role: 'switch', 'aria-checked': true })  // aria-checked="true"  ✓

// But boolean false REMOVES the attribute - which is wrong for
// tri-state ARIA, where "false" is a meaningful value:
mx.button({ 'aria-pressed': false })  // ✗ attribute removed, not "false"

// For ARIA states that need an explicit "false", coerce to a string -
// String(false) is "false", which SETS the attribute instead of removing it:
mx.button({ 'aria-pressed': String(pressed) })  // ✓  (pressed is a boolean)
Rule of thumb

For aria-hidden and other "present or gone" flags, a boolean is fine. For aria-pressed, aria-checked, aria-expanded, aria-selected - anything with a meaningful "false" - coerce to a string with String(value): String(false) is "false" (attribute kept), whereas a bare false removes it.

A copy-paste aria() helper

If you set ARIA state a lot, a tiny helper takes the String() decision off your hands. It is not part of mx - copy it if you like. It prefixes each key with aria-, stringifies the value (so a boolean false becomes the string "false" rather than a removed attribute), and drops null/undefined so you can omit conditionally:

aria-helper.jsJS
// Optional copy-paste helper - not part of mx. Prefixes each key with
// "aria-", stringifies the value (so a boolean false becomes "false"
// instead of a removed attribute), and drops null/undefined.
let aria = states => {
    let attrs = {};
    for (let key in states)
        if (states[key] != null) attrs['aria-' + key] = '' + states[key];
    return attrs;
};

aria({ checked: true, pressed: false })
// -> { 'aria-checked': 'true', 'aria-pressed': 'false' }
aria-helper-usage.jsJS
// Spread it into any element's attributes - no per-attribute String() calls:
mx.button({ ...aria({ pressed, expanded: open, controls: 'menu-1' }), onclick: toggle }, 'Menu')

// Numbers stringify, string enums pass through, and null/undefined drop out,
// so conditional ARIA stays clean:
aria({ valuenow: 40, current: onThisPage ? 'page' : null })
// -> { 'aria-valuenow': '40' }   (aria-current omitted when not the current page)
Why false and null behave differently

The two nullish values give you both behaviors: a boolean false becomes "false" (the attribute stays, marking an explicit off state), while null/undefined drops the key entirely (the attribute is absent). That's exactly the tri-state vs not-applicable distinction ARIA cares about - aria({ pressed: isToggle ? on : null }) sets "true"/"false" for a real toggle and nothing at all when it isn't one.

Use real elements first#

The single biggest accessibility win costs nothing: render the element that already means what you want. A <div onclick> is invisible to keyboards and screen readers, but a <button> is focusable, activates on Enter and Space, exposes a button role, and supports :disabled - for free.

A div is not a button

Clickable with a mouse, unreachable and unnamed for everyone else.
// ✗ A "button" with none of a button's behavior
mx.div({ class: 'btn', onclick: submit }, 'Save')
//   no keyboard activation, no focusability, no role, no :disabled
// ✓ A real button - focusable, Enter/Space activate it, role is implicit
mx.button({ class: 'btn', onclick: submit }, 'Save')

// ✓ Real link, real label/input pairing, real disabled state
mx.a({ href: '/settings' }, 'Settings')
mx.label({ for: 'email' }, 'Email')
mx.input({ id: 'email', type: 'email', disabled: !ready })

You only need ARIA when no native element fits (a custom listbox, a tab set, a tree). Everything a native element gives you, you'd otherwise have to re-implement with tabindex, key handlers, and role - and get exactly right. Don't, unless you must.

Accessible names#

Every interactive control needs an accessible name. Visible text is the name automatically. When there's no visible text - icon-only buttons - or when a field needs extra description, name or describe it explicitly. These five attributes cover almost everything:

AttributeWhat it does
aria-labelA name supplied directly as a string.
aria-labelledbyA name borrowed from another element's text, by id.
aria-describedbySupplementary description (hints, error text), by id.
aria-placeholderThe placeholder's semantic equivalent for custom inputs.
aria-errormessagePoints at the element holding a field's current error - only announced while aria-invalid is "true", "grammar" or "spelling".
accessible-names.jsJS
// Icon-only control: no visible text, so give it an accessible name
mx.button({ 'aria-label': 'Add to favorites', onclick: fav },
    mx.anIcon({ icon: 'star' })   // your own icon component
);

// Field described by helper text - point at the element holding it
mx.div(
    mx.label({ for: 'pw' }, 'Password'),
    mx.input({ id: 'pw', type: 'password', 'aria-describedby': 'pw-hint' }),
    mx.small({ id: 'pw-hint' }, 'At least 12 characters')
);

// Group labelled by its own heading
mx.section({ role: 'group', 'aria-labelledby': 'billing-h' },
    mx.h3({ id: 'billing-h' }, 'Billing'),
    /* fields... */
);
aria-errormessage needs aria-invalid

Per the ARIA spec, aria-errormessage is exposed to assistive tech only when the same element also has aria-invalid="true" (or "grammar"/"spelling"). With aria-invalid absent or "false", the error pointer is ignored. Always set them together, and clear both when the field becomes valid:

error-message.jsJS
mx.input({
    'aria-invalid': error ? 'true' : 'false',
    'aria-errormessage': error ? 'pw-err' : null
});
error && mx.small({ id: 'pw-err' }, error);
Prefer a real label

When the element can have a visible <label>, use one - it's a larger click target and survives translation. Reserve aria-label for text-free controls like icon buttons.

Focus management#

Two rules cover most of it: when an overlay opens, move focus into it and keep it there. When it closes, return focus to whatever opened it. The platform gives you a clean tool for the trapping part - the inert attribute, which makes a subtree unfocusable and invisible to assistive tech in one property.

  1. OpenRemember the focused element
  2. TrapInert the background, focus inside
  3. EscapeTop dialog only closes
  4. ReleaseRestore inert and focus
focus-trap.jsJS
// Modal ownership stack. Only the top panel may close or release focus.
// A native <dialog>.showModal() is another option for browser-owned modality.
let focusStack = [];
let FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), ' +
  'select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
function trapFocus(panel) {
  if (focusStack.some(entry => entry.panel === panel)) return false;
  let previousFocus = document.activeElement;
  let inerted = [];
  for (let node = panel; node && node !== document.body; node = node.parentElement) {
    node.parentElement?.childNodes.forEach(sibling => {
      if (sibling.nodeType === 1 && sibling !== node && !sibling.inert) {
        sibling.inert = true;
        inerted.push(sibling);
      }
    });
  }
  focusStack.push({ panel, previousFocus, inerted });
  (panel.querySelector(FOCUSABLE) || panel).focus();
  return true;
}
function releaseFocus(panel) {
  let top = focusStack[focusStack.length - 1];
  if (!top || top.panel !== panel) return false; // Reject repeated/out-of-order close.
  focusStack.pop();
  top.inerted.forEach(node => { node.inert = false; });
  if (top.previousFocus?.isConnected) top.previousFocus.focus();
  return true;
}

Open and close a dialog with it. Note the symmetry: it traps on open, releases on close, and Escape closes it, which is the keyboard behavior users expect from a modal:

open-dialog.jsJS
// Requires trapFocus/releaseFocus from the preceding example.
function openDialog(content, label = 'Dialog') {
  let dialog = dom.div({ role: 'dialog', 'aria-modal': 'true',
    'aria-label': label, tabindex: '-1', class: 'dialog' },
    content,
    mx.button({ 'aria-label': 'Close dialog', onclick: close }, '×')
  );
  function onKey(event) {
    if (event.key === 'Escape' && focusStack[focusStack.length - 1]?.panel === dialog) {
      event.preventDefault();
      event.stopImmediatePropagation();
      close();
    }
  }
  function close() {
    if (!releaseFocus(dialog)) return false;
    document.removeEventListener('keydown', onKey);
    dialog.remove();
    return true;
  }
  document.body.append(dialog);
  document.addEventListener('keydown', onKey);
  trapFocus(dialog);
  return { dialog, close };
}
// Owner closes dialogs from top to bottom before replacing their page.
// let first = openDialog('Settings', 'Settings'); first.close();
Why inert, not a focus-loop

The old approach was to intercept Tab and wrap focus manually. inert is better: it's declarative, it also hides the background from screen-reader virtual cursors (a focus-loop doesn't), and it's one line. The stack lets a dialog open a second dialog and unwind correctly.

Don't trap focus on non-modal surfaces

A trap belongs to modal dialogs and the like. A popover or dropdown that doesn't block the page should not trap focus - closing on Escape or outside-click and returning focus is enough. Trapping a non-modal surface strands keyboard users.

Keyboard navigation#

Custom widgets that group items - listboxes, menus, tab sets - can keep focus on the container using aria-activedescendant: the container is the single tab stop, and arrow keys move an "active" index inside it. mx makes the active index ordinary state, so the key handler is a few lines and the markup re-renders with the right aria-selected. Open the Result tab, then Tab into the list:

option-list.jsJSRunnablePlayground
define('option-list', {
  $({ options = [], onChoose, active = 0, label = 'Options' }) {
    // Per-instance IDs remain stable across updates and never collide.
    this._optionPrefix ||= 'option-' + crypto.randomUUID() + '-';
    active = options.length ? Math.max(0, Math.min(active, options.length - 1)) : -1;
    this.$attrs({ role: 'listbox', tabindex: '0', 'aria-label': label, style: 'display:block',
      'aria-activedescendant': active < 0 ? null : this._optionPrefix + active });
    this.onkeydown = event => {
      if (!options.length) return;
      let last = options.length - 1;
      if (event.key === 'ArrowDown') this.$({ active: active < last ? active + 1 : 0 });
      else if (event.key === 'ArrowUp') this.$({ active: active > 0 ? active - 1 : last });
      else if (event.key === 'Home') this.$({ active: 0 });
      else if (event.key === 'End') this.$({ active: last });
      else if (event.key === 'Enter' || event.key === ' ') onChoose?.(options[active]);
      else return;
      event.preventDefault();
    };
    return options.map((option, index) => mx.div({
      id: this._optionPrefix + index, role: 'option',
      'aria-selected': String(index === active),
      style: 'padding:8px;cursor:pointer;' + (index === active ? 'background:var(--a3, Highlight);color:var(--a1, HighlightText);' : ''),
      onclick: () => { this.$({ active: index }); this.focus(); onChoose?.(option); }
    }, option.label));
  }
});
// role="status" announces each choice without moving focus.
let status = dom.p({ role: 'status' }, 'Use arrows, Home/End, then Enter or Space.');
let list = dom('option-list', {
  label: 'Cities', options: [{ label: 'Berlin' }, { label: 'Cairo' }, { label: 'Lima' }],
  onChoose: option => { status.textContent = 'Chose: ' + option.label; }
});
document.body.render(list, status);
KeyEffect in the demo
TabMoves focus onto the list - one tab stop for the whole widget.
ArrowDown / ArrowUpNext / previous option, wrapping at the ends.
Home / EndFirst / last option.
Enter / SpaceChoose the active option, and the role="status" line announces it.

The keys to support depend on the pattern - the ARIA Authoring Practices enumerate them per widget. The mechanics in mx are always the same: this.onkeydown updates an index in $state, the render reflects it in aria-selected, and aria-activedescendant tells assistive tech which item is active without moving real DOM focus.

Roving tabindex vs aria-activedescendant

Shown above

aria-activedescendant

Keeps focus on the container and points at the active child by id. Simplest with mx, since the children re-render freely.

Alternative

Roving tabindex

Gives the active child tabindex="0" and the rest tabindex="-1", then calls .focus() on it. Use it when each item must be the real focus target, e.g. items contain their own controls.

Live regions#

When something changes away from the user's focus - a result count updates, a toast appears, a background save finishes - screen readers won't notice unless you tell them. A live region is a container whose text changes get announced automatically. Create one and write to it:

announce.jsJS
// A single polite live region, created once. Updating its text
// makes screen readers announce the new content without moving focus.
let announcer = dom.div({
    'aria-live': 'polite',
    'aria-atomic': 'true',
    class: 'visually-hidden'   // off-screen, not display:none (which AT ignores)
});
document.body.append(announcer);

function announce(message) {
    announcer.textContent = '';                       // reset so repeats re-announce
    requestAnimationFrame(() => announcer.textContent = message);
}

// Use it for things that happen away from the user's focus, one call
// per event (a second call in the same frame replaces the first):
announce('5 results found');   // when a search finishes
announce('Draft saved');       // when an autosave completes

// Urgent, interrupting messages: role="alert" already implies
// aria-live="assertive" + aria-atomic="true", so don't repeat them.
let errors = dom.div({ role: 'alert', class: 'visually-hidden' });
AttributeBehavior
aria-live="polite"Announce when the user is idle. Default for status, counts, confirmations.
aria-live="assertive"Interrupt immediately (role="alert" implies it). Reserve for errors and time-critical messages.
aria-atomic="true"Announce the whole region on change, not just the diff.

aria-busy for loading regions

While a region rebuilds, mark it aria-busy so assistive tech waits for a settled tree instead of announcing it mid-construction:

aria-busy.jsJSFragment
// While a region is loading, mark it busy so AT doesn't announce
// a half-built tree. Clear it when the content settles.
panel.$attrs({ 'aria-busy': loading ? 'true' : null });

return loading
    ? mx.div({ role: 'status' }, mx.aSpinner(), 'Loading...')   // aSpinner: your own component
    : mx.div(/* the loaded content */);
Off-screen, not display:none

A visually-hidden live region must stay in the accessibility tree - use the clip/off-screen technique (position:absolute;width:1px;height:1px;overflow:hidden), not display:none or visibility:hidden, which remove it from the tree and silence announcements.

Checklist#

NeedReach for
A clickable thingA real <button>/<a> - not <div onclick>
Name an icon-only controlaria-label
Describe a field / its erroraria-describedby / aria-errormessage
A toggle / disclosure statearia-pressed/aria-expanded via String(value), not a bare boolean
Trap focus in a modalinert + restore focus on close + Escape
Arrow-key a custom widgetActive index in $state + aria-activedescendant
Announce a background changearia-live region
In short

In mx, accessibility is something the platform already gives you rather than a feature you turn on. Semantic elements carry their own semantics through the reconciler untouched, aria-* is just attributes, and focus and keyboard are DOM APIs. All mx has to do is stay out of the way.

Related

FormsLabels, validation messaging.LifecycleCleaning up the keydown listeners these patterns add.Tag-level macrosEnforcing a11y defaults on every instance of a tag.