---
title: Accessibility
description: Accessibility principles, keyboard interaction models, and ARIA
  contracts in Moraine.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# Accessibility

> Accessibility principles, keyboard interaction models, and ARIA contracts in Moraine.

Moraine implements keyboard navigation, focus management, and ARIA relationships based on the [W3C WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/). Applications still need accessible names, readable color contrast, and appropriate semantics for custom renderers and polymorphic elements.

## Keyboard Interaction Models

Moraine components follow established UI patterns for keyboard interaction:

### Collection Navigation

`Tabs` uses roving tabindex: the highlighted tab has `tabindex="0"`, and other tab triggers have `tabindex="-1"`. Select-family controls keep DOM focus on their trigger or input and identify the highlighted option through `aria-activedescendant`. Menus move focus between their items. These models support arrow navigation without adding every option to the page's tab order:

| Key                                 | Action                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------- |
| <kbd>↓</kbd> / <kbd>→</kbd>         | Moves to the next item along the component's navigation axis.                   |
| <kbd>↑</kbd> / <kbd>←</kbd>         | Moves focus to the previous item.                                               |
| <kbd>Home</kbd>                     | Moves focus directly to the first enabled item.                                 |
| <kbd>End</kbd>                      | Moves focus directly to the last enabled item.                                  |
| <kbd>Enter</kbd> / <kbd>Space</kbd> | Activates or selects where supported; editable inputs retain normal text entry. |

Looping and activation depend on the component and its options. See each component's keyboard documentation for orientation, disabled items, typeahead, and selection.

### Overlay Dismissal

Dismissible overlays (such as `Dialog`, `Sheet`, `Drawer`, `Popover`, `Tooltip`, `HoverCard`, `DropdownMenu`, `ContextMenu`, and select popups) close on <kbd>Escape</kbd>. Only the topmost active overlay handles the key, so closing a nested overlay leaves its parent open. Escape is ignored during IME composition. Set `closeOnEscape` to `false` to keep an overlay open; `onClosePrevented` reports the blocked attempt.

## Focus Management

### Focus Trapping in Modals

Modal surfaces such as `Dialog`, `Sheet`, `Drawer`, and `BaseDialog` keep keyboard focus inside their content while open. Tabbing past the last focusable element returns focus to the first. While open, they also hide outside content from assistive technology and lock page scroll. `Popover` is non-modal by default; `modal` applies the same behavior only when the content includes `Popover.Close`. With `modal={false}` on a modal surface, focus is not trapped, moved on open, or restored on close.

### Focus Restoration

Modal overlays restore focus to their trigger after closing, or to the element that was focused when they opened. Set `finalFocus` to choose another element. Non-modal floating overlays restore focus after keyboard dismissal but let an outside press move focus to its target. Tooltips never move focus from their trigger. Check each component's focus options before customizing this behavior.

### Initial Auto-Focus

Modal surfaces focus an `[autofocus]` or `[data-autofocus]` descendant when opened, otherwise the first focusable child, otherwise the content container. When opened by touch, they focus the content container. Set `initialFocus` to choose the element, or `false` to skip the move. Menus and select-family controls use their own highlighted-item behavior. Tooltips do not move focus into their content.

## ARIA Attribute Contracts

Moraine sets and updates these ARIA attributes from component state:

- **State indication**: Components maintain `aria-expanded="true|false"` on triggers, `aria-selected="true|false"` on selection items, and `aria-checked="true|false|mixed"` on checkboxes.
- **Relationship wiring**: Triggers and contents are linked through `aria-controls` with deterministic element IDs generated by `createId`.
- **Overlay names**: `Dialog.Content` and `Sheet.Content` use `title` as `aria-labelledby` (unless `aria-label` is set) and `description` as `aria-describedby`. `BaseDialog.Content` renders `role="dialog"` and needs an `aria-label` or `aria-labelledby`.
- **Form association**: `Field` binds its `label` to the registered control through `aria-labelledby`, and its `hint`, `description`, `error`, and `help` text through `aria-describedby`. `hiddenLabel` supplies a visually hidden label when `label` is empty.
- **Validation**: When a field has an error, Moraine sets `aria-invalid="true"` on the control and adds the visible error message to `aria-describedby`.

```tsx
import { Field, Input } from 'moraine'

export function AccountField() {
  return (
    <Field label="Email Address" description="We will never share your email.">
      {/* Automatically wires id, aria-labelledby, and aria-describedby */}
      <Input type="email" placeholder="name@example.com" />
    </Field>
  )
}
```

## Screen Reader Considerations

- **Semantic HTML**: Moraine uses native controls such as `<button>` and `<input>` alongside ARIA roles for custom widgets and overlay surfaces. When you use the `as` prop, the rendered element must provide the same semantics.
- **Icon-only buttons**: Provide an accessible name with `aria-label`:

  ```tsx
  import { Button } from 'moraine'

  export function CloseSettingsButton() {
    return (
      <Button aria-label="Close settings" variant="ghost" size="icon-md" leading="icon-close" />
    )
  }
  ```

- **Built-in labels**: Accessible names that Moraine supplies, such as the `Dialog` close button, come from locale messages. Override them with a component's `translations` prop or `MoraineProvider` `messages`; see the [Localization guide](https://moraine.subf.dev/docs/localization.md).

