Documentation navigation

On this page

Authoring Practices

A widget is a contract#

WAI-ARIA Authoring Practices Guide is guidance for implementing that contract. A role attribute alone is not a widget.

Every custom widget needs

  1. Correct role and accessible name
  2. Keyboard interaction model
  3. Focus management
  4. Accurate state updates

Focus pattern: dialog#

Interactive demo

Dialog focus movement

Dialog focus

Open the dialog with the button. Escape closes it. Focus should move in on open and return to the trigger on close.

Closed. Focus is on the page (trigger when last used). (closed)

Confirm action

This uses the native HTML dialog with showModal().

Instructions
Open, Tab inside, Close or Escape, confirm focus returns.

Pattern checklist#

Use this when building tabs, accordions, menus, or comboboxes.

Test

Widget acceptance

ActionExpect
Role/nameMatch the widget type and purpose
KeyboardMatches APG for that pattern
FocusMoves and restores correctly
Stateexpanded/selected/checked stay in sync