Accessible Dialogs with ARIA

Technical Deep Dive & Specifications

Native Focus Trapping Mechanics

When a <dialog> is invoked via .showModal(), the browser engine executes an internal focus containment algorithm:

1. Focus Confinement: Pressing Tab on the last focusable element in the dialog automatically wraps focus to the first focusable element. Pressing Shift+Tab on the first element wraps to the last.
2. Background Inertness: The browser automatically marks all nodes outside the <dialog> as inert. Users cannot click, scroll, select text, or navigate into background elements via screen reader virtual cursors.
3. Automatic Focus Restoration: When the dialog is closed via .close(), the browser automatically restores keyboard focus back to the DOM element that originally triggered .showModal().

Initial Focus Placement Strategy & autofocus

When a dialog opens, where does keyboard focus land?

Browser Default Focus Order:

1. The first descendant element containing the autofocus attribute.
2. If no autofocus attribute is present, the first focusable descendant (button, input, link).
3. If no focusable descendants exist, focus lands on the <dialog> container itself.

<!-- Safe Initial Focus Placement for Destructive Actions -->
<dialog aria-labelledby="dialog-title">
  <h3 id="dialog-title">Delete Workspace?</h3>
  <p>This will delete all 45 projects.</p>
  
  <div class="actions">
    <!-- Place autofocus on the safe CANCEL button, NOT the delete button! -->
    <button type="button" id="btn-cancel" autofocus>Cancel</button>
    <button type="button" id="btn-delete" class="danger">Permanently Delete</button>
  </div>
</dialog>

[!WARNING] Never place autofocus on a destructive confirmation button. If a user rapidly presses Space or Enter on the webpage just as the modal pops up, an autofocus on the destructive button could instantly confirm data deletion. Always focus the safe "Cancel" action or an input field.

ARIA Labeling Matrix for <dialog>

<!-- Fully Accessible Dialog Structure -->
<dialog 
  id="export-dialog" 
  aria-labelledby="export-heading" 
  aria-describedby="export-description">
  
  <h2 id="export-heading">Export Database Snapshot</h2>
  <p id="export-description">
    Generating a full PostgreSQL dump may take up to 3 minutes.
  </p>

  <form method="dialog">
    <label for="snapshot-format">Format:</label>
    <select id="snapshot-format" autofocus>
      <option value="sql">Raw SQL Script</option>
      <option value="tar">Custom TAR Archive</option>
    </select>

    <div class="btn-group">
      <button value="cancel">Cancel</button>
      <button value="export" class="primary">Download Snapshot</button>
    </div>
  </form>
</dialog>

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Lines 57–60: Binds the accessible name and description of the dialog to its internal heading and description paragraph using aria-labelledby="modal-title" and aria-describedby="modal-desc".
• Line 68: Places autofocus on the safe "Cancel" button. When the modal appears, keyboard focus lands immediately on "Cancel" rather than the destructive "Revoke" button.
• Lines 28–31: Implements clear, high-contrast :focus-visible styles (outline: 3px solid #38bdf8), ensuring keyboard users can easily track focus.
• Lines 82–84: Triggers .showModal(), engaging the browser's built-in focus trap and making the rest of the page inert.

Expected Browser Render Output

1. Initial Viewport: Shows the account settings page.
2. Activating Modal: Clicking "Revoke All API Keys" opens the dark dialog with a blurred backdrop.
3. Keyboard Focus: Focus lands squarely on the "Cancel" button with a vivid cyan outline. Pressing Tab moves focus to "Revoke 8 Tokens". Pressing Tab again wraps focus directly back to "Cancel", completely ignoring the background page.