A11Y HTML

A collection of accessible markup for common UI components.

Dialog

A dialog is an interactive overlay component, such as a dismissible alert or confirmation window, that separates content from the rest of the page.

role

This attribute role="dialog" tells the browser and assistive technology that this element is a dialog, and its content should be separated from the page's content.

aria-modal

Indicates whether this dialog is modal or not.

Setting aria-modal="true" tells assistive technology that nagivation is limited to the dialog, and everything else is hidden.

Note: This attribute does not provide the required focus and keyboard behavior to the dialog.

aria-labelledby

The attribute aria-labelledby provides contextual information for the controls inside the dialog.

All dialogs must be properly labelled.

aria-describedby

The attribute aria-describedby provides additional context if available.

<button type="button">Open dialog</button>
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-label"
  aria-describedby="dialog-desc"
>
  <h2 id="dialog-label">Dialog Title</h2>
  <p id="dialog-desc">Dialog Description</p>
</div>

A menu is an interactive component that groups together a list of actions or choices that a user can invoke.

The attribute role="menu" tells assistive technology that this element is a menu.

The attribute role="menuitem" tells assistive technology that this element is an option in a set of actions contained by a menu.

The attribute aria-labelledby refers to the element that contains the accessible name for the menu.

The attribute aria-haspopup indicates the menu button triggers an interactive popup element.

Setting the attribute, aria-expanded, to "true" informs assistive technology that the element the menu button controls is visible.

Note: aria-controls is required to inform assistive technology which element or elements are visible.

The attribute aria-controls identifies the element that is controlled or made visible by the menu button, through a reference to the element's id.

tabindex informs browsers on how to handle keyboard focus. The menuitems in the menu should be keyboard navigable with arrow keys, but not tab.

<button 
  id="menu-trigger"
  aria-haspopup="true"
  aria-expanded="true"
  aria-controls="menu-container"
>
  Menu Button
</button>
<div
  role="menu"
  aria-labelledby="menu-trigger"
  id="menu-container"
>
  <button role="menuitem" tabindex="-1">
    Action
  </button>
  <button role="menuitem" tabindex="-1">
    Action
  </button>
</div>

Popover

A popover is an non-modal overlay element that displays additional content.

aria-expanded

Setting the attribute, aria-expanded, to "true" informs assistive technology that the element the button controls is visible.

Note: aria-controls is required to inform assistive technology which element or elements are visible.

aria-controls

The attribute aria-controls identifies the element that is controlled or made visible by the button, through a reference to the element's id.

aria-hidden

To prevent keyboard interaction with the popover when it is closed, either use aria-hidden set to "true", or do not render the popover.

Focusable

The popover must have a focusable element, and focus should be moved to the either first focusable element within the popover or the container when it is opened.

<button
  type="button"
  aria-expanded="true"
  aria-controls="popover-container"
>
  Trigger
</button>
<div
  id="popover-container"
  aria-hidden="false"
>
  <p>Popover content</p>
  <button type="button">Close</button>
</div>

Switch (Toggle)

A type of checkbox that represents on and off values, as opposed to checked and unchecked values. Functionally similar to a checkbox, but only supports an on and off state.

role

The attribute role="switch" tells assistive technology that this element is a switch.

aria-checked

The aria attribute aria-checked is required for any elements with a switch role. Values must be either "true" or "false".

<button
  type="button"
  role="switch"
  aria-checked="true"
>
  Toggle
</button>

Tabs

Tabs are used to show and hide content within a page, organized by clickable elements describing each section. Once focused, the user can change between the tabs using the left and right arrow keys.

role='tablist'

role="tablist" describes a list of elements withrole"tab". These tab elements must be immediate children.

role='tab'

role="tab" describes a clickable element as a tab, indicating it controls the visibility of an associated element with role"tabpanel".

aria-selected

Used to indicate which tab is currently active, and as a result, which associated role"tabpanel" is visible.

aria-controls

Used to explicitly describe the relationship between an element with role="tab" and role"tabpanel" via a unique id.

tabindex

The tabindex must be set to 0 for the currently selected tab, and set to -1 otherwise. This allows focus to be controlled programmatically when the user uses the left and right arrow key rather than via the regular tab order of the document.

role='tabpanel'

role="tabpanel" is used to describe regions of content that show and hide according to the selected tab. The aria-controls attribute of the corresponding tab must have the same value as the uniqueid of this element.

aria-labelledby

Each element with role="tabpanel" is labelled by the content of the corresponding element with role="tab" via its unique id.

<div>
  <div role="tablist">
    <button
      type="button"
      role="tab"
      aria-selected="true"
      aria-controls="tabpanel-1"
      id="tab-1"
    >
      Tab 1
    </button>

    <button
      type="button"
      role="tab"
      aria-selected="false"
      aria-controls="tabpanel-2"
      id="tab-2"
      tabindex="-1"
    >
      Tab 2
    </button>

    <button
      type="button"
      role="tab"
      aria-selected="false"
      aria-controls="tabpanel-3"
      id="tab-3"
      tabindex="-1"
    >
      Tab 3
    </button>
  </div>

  <div>
    <div
      role="tabpanel"
      aria-labelledby="tab-1"
      id="tabpanel-1"
    >
      Tab panel 1
    </div>

    <div
      role="tabpanel"
      aria-labelledby="tab-2"
      id="tabpanel-2"
    >
      Tab panel 2
    </div>

    <div
      role="tabpanel"
      aria-labelledby="tab-3"
      id="tabpanel-3"
    >
      Tab panel 3
    </div>
  </div>
</div>

Toggle Button

A toggle button that represents on or off values. Functionally similar to switch, but supports mixed values and should be used when the element visually looks like a button.

aria-pressed

Indicates the current "pressed" state of a button. Can be either "true", "false", "mixed" or undefined.

<button
  type="button"
  aria-pressed="true"
>
  Toggle
</button>

Tooltip

A tooltip is a small overlay element that provides auxiliary content for another focusable or interactive element, such as a field, link or button. Tooltips are triggerd by both focus and hover events.

role

The attribute role="tooltip" tells assistive technology that this element is a tooltip.

aria-describedby

The attribute aria-describedby on the triggering element ties the element to the tooltip.

aria-hidden

To prevent interaction with tooltip content when it is closed, either use aria-hidden set to "true", or do not render the tooltip.

<a aria-describedby="tooltip">
  Link
</a>
<span
  role="tooltip"
  id="tooltip"
  aria-hidden="true"
>
  Tooltip Content
</span>