The Accessibility Tree

At the top level, the first concept to understand is the platform Accessibility API, which is an integral part of each Operating System. On Windows, these interfaces include UI Automation (UIA), Microsoft Active Accessibility (MSAA), and IAccessible2. Linux desktop environments commonly use AT-SPI, while macOS and iOS use Apple's accessibility interfaces.

These platform APIs have a direct relationship with web development. They expose information about the controls that appear in an application or browser, including each control's Role, Name, Description, Value, State, and relationship to other controls.

For example, a native Checkbox is exposed as a control with a recognizable Role and a Checked State. A screen reader can use that information to announce the Checkbox's name and whether it is checked, without needing to guess from its appearance.

The Accessibility Tree is the browser's accessible representation of the page. It is built using the document structure, native HTML semantics, applicable ARIA attributes, content, CSS visibility, and changes caused by scripting. It is not an exact copy of the DOM; some nodes are omitted, combined, or represented differently by the browser.

Assistive Technologies interface with this representation through the appropriate operating-system API. Not every browser uses the same API mapping, so the available information and announcements can differ across browsers and devices.

To inspect these objects, begin with the Accessibility panel in the browser's Developer Tools. On Windows, Accessibility Insights and Microsoft's Inspect utility can help examine platform information. On Apple platforms, use Accessibility Inspector.

When testing, compare the computed Role, Name, Description, States, and keyboard focus with what the actual screen reader conveys. A correct-looking Accessibility Tree is important, but it cannot by itself establish whether the entire interface is usable.

To put things into perspective, it is helpful to understand the foundations of the Accessibility Tree and ARIA.

Originally, the Accessibility API on native platforms leveraged the window tree hierarchy. The reason being, that Windows applications needed to be able to propagate mouse and keyboard events upward from an object to its ancestors. This allowed desktop applications to have containers that managed their children, such as Listboxes with child Option objects. The Accessibility API used this hierarchy to determine context, such as the number of child objects matching a specific Role.

As desktop applications became more complex, they started to utilize object trees, instead of relying solely on window handles as they had previously. Thus allowing applications to manage child objects more effectively, in order to process mouse and keyboard events within the context of the same structure. This was when the Accessibility API was bound to the platform object tree, which first occurred when Microsoft implemented OLE Accessibility in 1995; later to be renamed MSAA (Microsoft Active Accessibility). This object structure is now what is referred to as the Accessibility Tree.

As browsers became capable of rendering increasingly complex document structures, semantic information from HTML and later ARIA made it possible to expose web content through platform accessibility APIs. The browser builds an Accessibility Tree from the DOM and other inputs, but the trees do not mirror one another exactly. The resulting objects and relationships are determined by browser accessibility mappings.

The history of access technology also includes screen-reading techniques that predate modern Accessibility APIs. Microsoft introduced OLE Accessibility in the 1990s; the technology became known as Microsoft Active Accessibility (MSAA). UI Automation later added a separate, richer Windows accessibility API. These technologies coexist in modern software rather than representing a single API that was simply renamed.

The first attempt at mapping base-line platform concepts from the DOM to the more traditional Windows platform, was made by Richard Schwerdtfeger and T.V Raman while brainstorming in 2002, in order to devise a way of determining the nature of a DHTML widget without first requiring the execution of JavaScript. This is when ARIA DOM attributes were conceived. Since the purpose of ARIA was designed as a detection and mapping mechanism for Roles and States, it set the course for what we know as ARIA today. This is why the use of ARIA does not currently include any scripting behaviors when attributes are applied to the DOM; requiring that developers be familiar with these concepts in advance.

(Historical account provided by Richard Schwerdtfeger and T.V Raman)

Going back to our Checkbox example, it is helpful to see how a standard Operating System control exposes its properties.

1. Open a native Windows application that contains a labeled Checkbox, such as an option in Windows Settings or a desktop program.
2. Move keyboard focus to the Checkbox and change its checked state by pressing Space.
3. Use Accessibility Insights for Windows or Inspect to examine the exposed control type, Name, keyboard focus, and checked state.

The important point is not the numeric Role and State values from a particular historical version of Windows. It is the relationship between the accessible Role, the Name that identifies the control, the State that changes with interaction, and the behavior that makes the control usable.

Now compare the Operating System Checkbox with a standard Checkbox in a web page. Paste the following markup into a file named test.html and open it in a current browser.

<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Checkbox test</title></head>
<body>
  <label><input type="checkbox" checked> Delete browsing history on exit</label>
</body>
</html>

Using the browser Accessibility panel, examine the Checkbox's computed Role, Name, and Checked State. Press Space to change the State, and verify that the browser updates its accessible representation.

A native HTML Checkbox already supplies keyboard focus, activation, and checked-state behavior. Its visible <label> provides an accessible name and a click target. You do not need to recreate these functions with ARIA.

For the host language requirements, see ARIA in HTML and the HTML Checkbox definition.

Here is where we can see how important ARIA is, and what its impact is on the Accessibility Tree.

ARIA stands for Accessible Rich Internet Applications. It lets developers communicate the Role, State, and relationships of custom web controls when native HTML alone does not describe the intended interaction.

Consider a SPAN made focusable with tabindex="0". A browser does not interpret this SPAN as a Checkbox merely because it looks like one. By adding role="checkbox" and aria-checked, the element can expose Checkbox semantics to Assistive Technologies.

<span role="checkbox" tabindex="0" aria-checked="true" aria-label="Delete browsing history on exit"></span>

Inspect the element's Role, Name, and Checked State in the browser Accessibility panel. It should be exposed as a Checkbox. Yet the code above is only a demonstration of ARIA semantics: pressing Space will not change its checked state unless you add scripting to update aria-checked and the visible presentation.

This is the critical distinction: ARIA communicates meaning; it does not create keyboard interaction, focus movement, or the control's underlying behavior. A custom Checkbox needs a clear name, a synchronized Checked State, keyboard activation, visible focus, and a clickable target. For the simple case shown here, the native <input type="checkbox"> remains the better option.

See the WAI-ARIA Checkbox Role, ARIA in HTML, and Checkbox design pattern for additional examples. The APG example demonstrates one implementation approach; its particular markup is not the only valid approach.

When ARIA is implemented correctly, it can make a custom control recognizable to Assistive Technologies by supplying accurate Roles, States, and relationships. When used incorrectly, it can also conflict with native semantics or expose information that does not match the actual interaction.

As a result, care must always be taken when implementing interactive ARIA Widgets. There are several specifications to consult, and each answers a different question:

1. WAI-ARIA 1.2 defines ARIA Roles, States, Properties, and requirements for authors.
2. ARIA in HTML identifies which Roles and attributes may be used on individual HTML elements.
3. Core Accessibility API Mappings and HTML Accessibility API Mappings explain how browsers expose semantics through platform accessibility APIs.

The ARIA Authoring Practices Guide also provides useful keyboard interaction patterns and working examples. Its examples are informative rather than additional conformance rules, and more than one accessible design may be appropriate.

Browsers are responsible for translating web semantics into the accessible objects exposed through the Operating System. The historical User Agent Implementation Guide introduced this process; its modern successors are the Core Accessibility API Mappings and HTML Accessibility API Mappings.

For ARIA to work reliably, browsers must expose meaningful Roles, States, and events, and Assistive Technologies must interpret those objects appropriately. What is exposed by the browser and what is announced by a screen reader are related, but not identical questions.

An ARIA Menu is a useful example. The menu and menubar Roles describe application-style command menus. Their use depends on how the control works, not merely on whether the layout appears vertical or horizontal. An ordinary website navigation list should generally be marked up as navigation links, rather than being given application-menu semantics.

When an application-style Menu is appropriate, keep the following requirements in mind:

1. Use the applicable Menu container Role and include supported command children such as menuitem, menuitemcheckbox, or menuitemradio, allowing for the grouping structures defined by the specification.
2. Make each command operable from the keyboard and manage focus through the Menu's documented interaction model. Arrow navigation and Escape are familiar conventions, but assigning a Role never creates these behaviors.
3. When an item opens a submenu, expose its popup type and expanded or collapsed state where applicable. Keep aria-expanded synchronized with the actual submenu.
4. Give every active item a meaningful accessible name. Avoid placing unrelated forms or nested interactive controls inside elements that are supposed to behave as Menu commands.
5. Use either valid DOM focus movement or a supported aria-activedescendant relationship. Do not assume that setting aria-selected moves focus.

You can explore these concepts in the WhatSock Vertical Menu and WhatSock Horizontal Menu.

Actual conformance depends on the Role definitions and the chosen HTML elements. Use the WAI-ARIA 1.2 Menu, Menu Item, and Active Descendant sections together with ARIA in HTML. Platform API mapping details are primarily for browser and Assistive Technology implementers; they do not replace authoring requirements.

The ARIA Roles Model describes what each Role means, how the Roles relate to one another, and which States and Properties may or must be supplied. The current Recommendation is WAI-ARIA 1.2, Roles.

For example, a listbox is an interactive choice control, whereas a list represents document structure. A grid has an interactive focus and navigation model, whereas a table can simply present tabular information. These distinctions affect how Assistive Technologies interpret and operate the content.

Before choosing a Role, check the following:

1. Does a native HTML control already supply the required semantics and keyboard behavior?
2. Does the Role match the action or information the user encounters?
3. What accessible Name, required parent or owned Roles, States, and Properties does the Role require?
4. Does the chosen HTML element permit the Role under ARIA in HTML?
5. Have focus management, keyboard commands, pointer interaction, and live updates been implemented and tested?

A Role does not add event handlers, change where DOM focus goes, or repair an interaction that cannot be operated from the keyboard. The Roles Model must therefore be read alongside the control's implemented behavior.

The ARIA States and Properties identify information that a browser can expose for specific controls. Some attributes are required for a particular Role; others apply only when a feature is present.

For instance, aria-pressed expresses the pressed state of a toggle button. It should be used only when the control actually acts as a toggle, and it must change when the user changes that state.

Live demo: WhatSock ARIA Toggle Buttons.

Another useful example is the combobox. Under WAI-ARIA 1.2, the element with role="combobox" must include aria-controls to identify its popup and aria-expanded to indicate whether that popup is visible. An editable combobox that performs autocomplete must also describe the autocomplete behavior with aria-autocomplete. Do not use aria-owns on the combobox to reference its controlled listbox or popup; use aria-controls.

A slider requires aria-valuenow, but aria-valuemin and aria-valuemax have default values of 0 and 100 when omitted. A spinbutton should report its numeric value when one is available, although aria-valuenow is not listed as an unconditional required state for that Role. An indeterminate progressbar should not invent a numeric value.

For checked controls, checkbox accepts true, false, and mixed states; switch accepts true or false, not mixed. A tooltip can be referenced from the element it describes using aria-describedby; that attribute belongs on the element being described, not on the tooltip itself.

There are also requirements that cannot be reduced to a short attribute list. Some Roles require an accessible Name or particular parent and child relationships, and some prohibit author-supplied labels. Check both WAI-ARIA 1.2 and the ARIA in HTML allowed-role table for the actual markup.

CSS is often used to make controls look alike across browsers, even when the underlying HTML has a different meaning. This can cause a disparity between what a sighted user sees and what an Assistive Technology user encounters.

CSS does not assign an accessible Role or implement a control's keyboard behavior. It can, however, affect the Accessibility Tree: for example, content hidden using display:none is ordinarily excluded from accessibility navigation. CSS visibility and ARIA semantics therefore have different, sometimes overlapping effects.

An especially useful technique is to style controls using their ARIA States. When the same State is updated by the interaction script, the visual presentation changes automatically without needing to maintain a separate CSS class.

<button type="button" aria-pressed="false" id="spellcheck">Spell Check</button>

<style>
  button[aria-pressed="true"] { background: #183f48; color: white; }
  button[aria-pressed="false"] { background: #f4f4f4; color: #151515; }
</style>
<script>
  const button = document.getElementById('spellcheck');
  button.addEventListener('click', () => {
    const pressed = button.getAttribute('aria-pressed') === 'true';
    button.setAttribute('aria-pressed', String(!pressed));
  });
</script>

The <button> element already supports focus and Enter/Space activation. The script changes aria-pressed; the CSS follows the State without a second update. For actual spell-check functionality, the script would also need to enable or disable spell checking.

Adding role="button" and tabindex="0" to a SPAN does not give it the same behavior. In that case, Enter and Space activation must be implemented separately. Use native HTML controls where possible, and confirm that visual changes remain perceivable without relying on color alone.

One of the most challenging interactive patterns to implement is drag and drop. Making an item visually draggable is only one part of the problem. The user also needs to discover what can be moved, understand the available destinations, perform the operation without a mouse drag, and receive confirmation that the move succeeded.

Older ARIA examples used the attributes aria-grabbed and aria-dropeffect. Both were deprecated in ARIA 1.1. They should not be used as the foundation for a new drag-and-drop implementation, and they never supplied the drag behavior by themselves.

Instead, expose real actions using accessible Buttons, Menus, and meaningful status messages. For operations controlled by pointer dragging, provide a single-pointer alternative that does not require dragging unless the movement is essential, as described in WCAG 2.2, 2.5.7 Dragging Movements. Keyboard access and logical focus movement remain essential as well.

There are several common forms of drag and drop, described here as Unassociated, Associated, and Internal. The categories are useful for choosing a keyboard interaction design; they are not separate ARIA Roles.

1. Unassociated: Moving an item without a specific drop zone, such as repositioning a panel.
2. Associated: Moving an item into one of a limited number of destinations.
3. Internal: Reordering items within a larger control, such as the Options of a Listbox.

Unassociated movement is commonly seen on pages where panels or other components can be repositioned. When an item has a move handle, it is usually easiest to make that handle a genuine Button and keep the remaining content of the panel independently operable.

The Button should tell the user what can be moved, how movement is performed, and how to finish or cancel the operation. It should have a visible focus indicator and support pointer as well as keyboard input. The instructions can be associated with the Button through aria-describedby.

<section aria-labelledby="panel-title">
  <h2 id="panel-title">Weather panel</h2>
  <button type="button" aria-describedby="move-help">
    Move weather panel
  </button>
  <p id="move-help">Use the arrow keys after activating Move. Press Enter to finish or Escape to cancel.</p>
  <p>Panel content...</p>
</section>

The markup above demonstrates the accessible Name and Description; scripting must implement the movement, position tracking, cancellation, and final placement. If the panel includes other Buttons or Links, do not put role="button" on the entire panel, since nested interactive controls would create conflicting behavior.

A movement command does not need to simulate a conventional drag gesture. Buttons such as “Move left” and “Move right,” or a position selector, can offer the same result. These can also be activated by touch, switch controls, and speech input.

When an item moves, keep focus at a predictable location and provide useful feedback such as “Weather panel moved left.” Do not rely solely on color changes, coordinate announcements, or deprecated aria-grabbed States to convey the result.

Associated drag and drop requires that an item be moved to a particular destination, such as a Trash area, a collection, or another panel. It can be difficult for both screen reader and keyboard-only users to locate and target a visual drop zone precisely.

For this reason, a direct action often provides a more reliable alternative. When there is only one destination, use a Button with a name such as “Move report to Trash.” The name identifies the action, the item, and the destination without requiring the user to discover the drop zone visually.

<button type="button" aria-describedby="move-result">
  Move report to Trash
</button>
<div id="move-result" role="status"></div>

After activation, the script performs the same underlying operation as the pointer interface and updates the Status message to confirm the result. A confirmation step may also be appropriate when the action is destructive.

When several destinations are available, the user can first activate a “Move report” Button and then choose a destination from an accessible list of actions or a Menu that is fully implemented for keyboard and pointer use. The choice of a Menu is an interaction decision, not a requirement merely because there is more than one destination.

An example of the direct-action approach can be seen in the WhatSock Drag and Drop demonstration. The interaction illustrates why a single activation can be more useful than requiring a precise mouse movement.

Hidden controls should not appear unexpectedly in the Tab order. If an additional Move Button is shown only when focused, make sure it has an understandable visible focus treatment and can also be discovered by sighted keyboard users.

Internal movement occurs when items are rearranged inside a larger control. For example, this may be used to reorder Tabs in a Tablist, Rows in a Grid, or Options in a Listbox.

The keyboard mechanism depends on the control. One interface may provide “Move up” and “Move down” Buttons, while another may let the user select an item, enter a Move mode, choose a destination, and then confirm. Either approach can work when the behavior is predictable, documented, and compatible with the rest of the widget.

For a sortable Listbox, a useful interaction sequence might be:

1. Navigate to the Option to be moved.
2. Activate a Move command or press a documented shortcut.
3. Choose a new location using available commands.
4. Confirm the operation, or press Escape to cancel.
5. Announce the completed result, such as “Item moved to position 2 of 5.”

See the WhatSock Sortable Listbox demonstration for an example of selecting and moving Options within a composite widget.

The original movement concept remains useful even though the historical aria-grabbed and aria-dropeffect attributes are deprecated. Do not rely on those attributes to tell Assistive Technologies what is happening. Use properly named actions, valid selection and focus semantics, instructions, and a clear completion message instead.

When a Listbox is used, retain its required Option ownership and an accurate selection model. Keyboard navigation, selection, and physical reordering are separate operations and must be handled separately in the script.

Typically, ARIA Role usage fits into one of several broad categories: Landmarks and Regions, Interactive Widgets, Compound Components, Corner Cases, or Live Regions. These categories provide a useful way to think about a design before choosing a Role.

The categories are teaching aids rather than an alternative to the formal ARIA Role hierarchy. The exact requirements for a Role must still be checked in the WAI-ARIA Roles Model and, for HTML pages, in ARIA in HTML.

Landmarks and Regions are amongst the easiest Roles to implement because they identify meaningful areas of a page and help Assistive Technology users move between them.

Common Landmark Roles include banner, navigation, main, complementary, contentinfo, search, form, and region. The corresponding HTML elements, such as <nav>, <main>, and <aside>, should be preferred where they supply the intended semantics.

Landmark context matters. A <header> inside an Article does not automatically become the page Banner. A form or region Landmark generally needs an accessible Name. Multiple Navigation Landmarks should be named so that a user can distinguish them.

Landmarks do not automatically provide keyboard commands, and a page with too many repetitive Regions can become more difficult to navigate. Use them to represent meaningful organization rather than placing a Landmark on every container.

Reference: WAI-ARIA Landmark Roles.

There are important details to be aware of regarding role="application".

The term does not simply mean that a page is dynamic or resembles a desktop application. Its purpose is to identify an area whose interactive keyboard behavior may require Assistive Technologies to use a different navigation mode.

For example, JAWS and NVDA often allow users to read a normal page using navigation commands such as the arrow keys or single-letter heading navigation. A specialized interactive area may need those keys for its own commands. In some configurations, the Application Role helps the screen reader pass the necessary keystrokes to the page.

The WhatSock ARIA Date Picker demonstrates an interactive calendar that has its own arrow-key commands. The framework's design should be evaluated by its documented semantics, keyboard behavior, and actual screen-reader operation, not by assuming it must match a particular APG example.

Use role="application" sparingly. Applying it to an entire page or ordinary Form may interfere with a screen reader's reading commands and content discovery. Most native controls and many well-designed custom widgets do not require an Application container at all.

The document Role can identify readable document content inside an Application area. This is useful when users need to switch back to ordinary document navigation within a custom interaction, but it does not remove the need for meaningful headings, Labels, and focus management.

Actual screen-reader modes and commands differ across products and versions. Always confirm that the content remains readable, that keyboard commands can be discovered, and that the user can leave the specialized interaction.

The Region Role is useful for identifying a named section of content that deserves Landmark navigation.

A Region should have a meaningful accessible Name, supplied through aria-labelledby when a visible heading is available or through aria-label otherwise.

<section aria-labelledby="latest-heading">
  <h2 id="latest-heading">Latest updates</h2>
  <p>Content...</p>
</section>

When an HTML <section> has a suitable accessible Name, it can supply the Region semantics without needing an explicit role="region". A generic container can also be given role="region" and a Name when appropriate.

For example, the WhatSock Accordion demonstration uses named Regions to identify associated content panels.

Use Regions for meaningful boundaries rather than every small section. When several Regions appear on the page, their Names should clearly distinguish their purpose.

Scrollable containers are often used to display variable amounts of content without expanding the whole page. A container with CSS such as overflow:auto may scroll when it has focus, although the precise behavior depends on the browser, layout, and input method.

When a scrollable area is not otherwise keyboard reachable, tabindex="0" can make it focusable. Give the container a useful accessible Name, and use Region semantics only if it represents a meaningful section rather than an incidental wrapper.

<section class="scrollable" tabindex="0" aria-labelledby="messages-title">
  <h2 id="messages-title">Message history</h2>
  <p>Earlier messages...</p>
</section>
<style>
  .scrollable { max-height: 16rem; overflow: auto; }
  .scrollable:focus-visible { outline: 3px solid #194b57; }
</style>

Do not assume that tabindex="0" makes scrolling fully accessible in every browser or Assistive Technology. Check that the user can reach the area, scroll through all content, recognize where focus is, and move on without getting trapped.

Interactive Widget Roles represent controls that people can operate, including Buttons, Checkboxes, Comboboxes, Listboxes, Menus, Radios, Sliders, Textboxes, Trees, and Grids. Each Role has its own semantics and, sometimes, required States or relationships.

A few common requirements are worth keeping in mind:

• A custom checkbox and switch require aria-checked. A Switch must not use the mixed state.
• Under WAI-ARIA 1.2 a combobox needs aria-controls and aria-expanded. It may control a listbox, tree, grid, or dialog popup. Do not use aria-owns to reference that popup.
• A slider requires aria-valuenow, and a custom scrollbar requires both aria-controls and aria-valuenow.
• A listbox must own suitable option elements, and composite controls such as Grids, Trees, and Tab Lists have required structural relationships.
• A grid is an interactive table-like widget. Static tabular data is usually better represented with a native HTML Table.

Focus management is a separate part of building these controls. One common approach is to move actual DOM focus between active items. Another is to keep DOM focus on a supported container or input while aria-activedescendant identifies the currently active item. That reference is valid only when the ownership or controlled-popup relationship meets WAI-ARIA requirements.

Neither approach automatically implements arrow-key behavior. Nor does changing aria-selected move keyboard focus. The interaction script must coordinate the user's commands with visual focus, selection, active items, and accessible States.

Consult the individual Role definitions and ARIA in HTML restrictions before implementing a particular control. The APG patterns are useful examples of familiar interactions, not the only available implementations.

Compound components occur when an interactive control contains more than one kind of widget behavior. A Data Grid is a common example: arrow keys may move between Cells, while Enter or another command may allow the user to edit a Cell using a Textbox or a Slider.

These components can be challenging because the user must understand when navigation is taking place and when an embedded control is accepting input. The following principles are especially useful:

1. Make every intended action reachable and operable from the keyboard.
2. Use valid Roles that match the function of each control, rather than assigning an interactive Role merely because the element receives focus.
3. Provide meaningful Names for controls; visible Labels are preferable when possible.
4. Define how focus enters, moves within, and leaves the compound widget.
5. Explain any keyboard commands that are not apparent from the interface.
6. Keep selection, expanded or collapsed State, current values, and editing mode synchronized with the behavior users experience.

Inspect the browser's computed accessibility objects and relationships while moving through the component. Then test in the intended browser and Assistive Technology combinations to confirm that each action can actually be completed.

If an accessibility object is missing information even though the markup is correct, investigate a possible browser mapping issue. If the tree is correct but the screen reader does not convey it or operate it properly, investigate the Assistive Technology interaction. Record the actual browser, OS, version, steps, and observed result before attributing a problem to either component.

Corner cases occur when a complex interaction does not map neatly to a single native HTML control or ARIA Widget Role. A Date Picker, for example, may contain a calendar with disabled dates, navigation commands, and an input field, but ARIA does not supply a single Role that makes the entire calendar work automatically.

One example is the WhatSock Date Picker with Disabled Date Ranges. It combines several interactions and uses its own documented keyboard model. Its controls must be evaluated according to the actual Roles exposed, the focus behavior, and the results experienced by keyboard and Assistive Technology users.

Another example is the WhatSock Dynamic Data Grid. Some Cells represent values while others can perform actions. When an interactive control is embedded in a Cell, the implementation must make it possible to discover and operate that control without losing the Grid's navigation model.

It is sometimes useful to add text that describes a Cell's action or State. That information should supplement accurate semantics, not pretend that a Gridcell itself has become a Button. If a control is actually a Button, the implementation should provide a valid Button interaction and a coherent way of reaching it.

There is no single solution for every corner case. First identify what the user is trying to accomplish, then select the appropriate semantics and focus model. A design that differs from an informative Authoring Practices example is not automatically incorrect; it still needs to satisfy normative requirements and work in practice.

Live Regions are parts of a page that can announce updates without forcing keyboard focus to move. They are especially useful for status messages, chat activity, changing results, and other information that may need to be conveyed while the user continues working elsewhere.

ARIA provides aria-live, aria-atomic, aria-relevant, and aria-busy, as well as Roles such as status, alert, and log. Each changes how updates are exposed for possible announcement.

Live Region markup does not guarantee that every Assistive Technology will speak exactly the same words at exactly the same time. Browsers and screen readers can combine, delay, or omit announcements. The content should remain accessible by ordinary navigation even when a live announcement is missed.

The aria-live Property accepts the values off, polite, and assertive.

• off: the content is not automatically announced merely because it changes, although it remains available through ordinary navigation.
• polite: changes may be announced when the user is not being interrupted.
• assertive: changes are presented with greater urgency and may interrupt current announcements. It should be used sparingly.

For example, a Region that contains a nonurgent update can use:

<div id="availability" aria-live="polite"></div>

The container normally should exist before its text is changed. When a script updates the Region, Assistive Technologies may announce the new content without changing keyboard focus.

The aria-atomic Property helps determine whether an update is treated as a whole Region or as changed parts. With aria-atomic="true", the whole relevant Region is considered. With false, the changed node or nodes are considered. This does not override a screen reader's announcement policy.

The aria-relevant Property can identify which types of additions, removals, and text changes matter. Support for announcing removals varies; never make an important deletion notice available only through that mechanism.

Try the polite update demonstration, atomic update demonstration, and removal demonstration. Each allows the change to be triggered manually so its behavior can be examined without continuous interruptions.

Online example: Aria-live Property demonstration on WhatSock

Online example: Aria-live Property demonstration on WhatSock

Online example: Aria-live Property demonstration on WhatSock

The Alert Role is meant for important, time-sensitive information. It has implicit aria-live="assertive" and aria-atomic="true" behavior.

An Alert can be suitable for an urgent error or condition that requires immediate attention. It is not appropriate for every routine success message, changing counter, or automatically rotating slide.

<div id="urgent-error" role="alert"></div>

When an urgent error occurs, a script can place the message in the Alert. The browser then exposes it as an important live update. Whether an actual interruption occurs, and when, depends on the browser and Assistive Technology combination. It should not be described as a guarantee of an Operating System-wide interruption.

Try the Alert demonstration and compare it with the assertive live-region demonstration. Use the controls deliberately, since urgent announcements can interrupt the task at hand.

Online example: Alert Role demonstration on WhatSock

The Log Role identifies a sequence of messages that grows over time, such as a chat history. It has implicit aria-live="polite" and aria-atomic="false" behavior. New entries can be announced while earlier entries remain available for reading.

The Status Role conveys a nonurgent result, such as “Your changes were saved.” It has implicit aria-live="polite" and aria-atomic="true" behavior.

These Roles therefore do not have identical atomic behavior. Choose the Role that matches the meaning of the content rather than adding aria-live indiscriminately to every changing element.

<div role="status" id="save-result"></div>

<div role="log" aria-label="Conversation messages" id="chat-messages"></div>

Compare the Log demonstration and Status demonstration. A browser Accessibility panel can confirm their semantics, but actual announcements still need to be checked using the intended screen reader.

Online example: Log and Status Roles demonstration on WhatSock

Online example: Log and Status Roles demonstration on WhatSock

Besides choosing the appropriate Role or aria-live value, there are several details to keep in mind when building Live Regions.

1. Avoid excessive announcements. Automatically changing carousels, fast counters, or stock tickers can produce more speech than a person can use. Allow users to pause, stop, or request updates when appropriate.
2. Keep announcements short and meaningful. A message such as “Item moved to position 2 of 5” is more useful than repeatedly announcing the entire container.
3. Do not move focus merely to announce a result. Use a Status message for an ordinary success and reserve Alert for genuinely urgent information.
4. Use aria-busy where appropriate. If a Region is being updated in several steps, the Busy State can help indicate that the update is not yet complete.
5. Do not assume every DOM mutation is spoken. Browsers and screen readers process changes differently. Screen reader punctuation settings, voice configuration, and verbosity can also change what the user hears.
6. Make important information readable on demand. A live announcement is supplemental; users should still be able to find the resulting content by ordinary navigation.

For a direct comparison of different live-region settings, see the polite update and non-atomic update demonstrations.

The goal is to inform the user, not to force the screen reader to talk. Confirm the experience in more than one supported browser and screen reader when the announcement is important to completing the task.

Online example: Live Region Caveats demonstration on WhatSock

It's very important to understand that the Accessibility Tree and the Document Object Model (DOM) are not the same thing.

The DOM is the browser's structured representation of the document. JavaScript can read and change its nodes, attributes, content, and focus, and those changes may cause the page to be rendered differently. The DOM Standard describes the underlying model.

The browser uses the DOM together with native HTML semantics, ARIA, CSS visibility, labeling rules, and platform accessibility mappings to build the Accessibility Tree. The browser may omit presentational wrappers, combine objects, or expose computed information that is not represented by a single DOM attribute.

For example, a control's accessible Name can come from a visible <label>, a reference through aria-labelledby, or its own text. Its Description may come from aria-describedby. The order of precedence is defined by the Accessible Name and Description Computation specification, not by the order in which the attributes happen to appear in the HTML.

CSS visibility affects this mapping. Elements hidden with display:none or hidden are usually excluded from normal accessibility navigation, subject to naming and description computation exceptions. aria-hidden="true" hides an element from the Accessibility Tree but does not prevent the element or its children from receiving keyboard focus. Do not use it on an active control or a container of focusable controls.

Similarly, role="presentation" and role="none" may suppress an element's native structural Role, but they do not hide its readable text. The role may be ignored when the element is focusable or has conflicting global ARIA properties.

Relationships are not the same as DOM placement. aria-controls identifies an element controlled by another element. aria-labelledby provides a naming relationship. aria-owns affects accessibility ownership in specific circumstances, and should not be used to move a Combobox popup into the accessibility subtree in place of aria-controls.

It is also important to distinguish DOM focus from the reading position of a screen reader's virtual cursor. Reading a Heading or an Option is not proof that the browser has moved actual keyboard focus to that node.

The WhatSock ARIA Tree demonstration provides a useful example of a hierarchy whose expanded, selected, and focused States change as the user interacts. Earlier tests of this demonstration found differences among Internet Explorer, Firefox, and Chrome on Windows 7 in 2014. Those results illustrate how browser mappings once differed; they are not evidence that the same bugs remain in current browsers.

To investigate a current issue, inspect the DOM and the browser Accessibility panel, then operate the widget with the keyboard and an actual screen reader. Record whether the problem occurs in the authored markup, the computed accessibility representation, or the way an Assistive Technology interprets it. Do not assume that a single static tree inspection proves an interface is fully accessible.

Since Assistive Technology behaviors and support levels differ, it's important to consider the people who will use the interface, the input methods they rely on, and the browsers and devices they may choose.

This is especially true for progressive enhancement, where the same controls may be used through a keyboard, mouse, touch screen, speech input, switch device, or screen reader.

Start with native HTML semantics and a complete keyboard interaction. Then verify focus, Names, Roles, States, and actual behavior through representative combinations of browsers and Assistive Technologies. The WebAIM Screen Reader User Survey provides useful reported usage data, but no one survey determines which combinations every website must support.

The following sections explain the interaction models and testing considerations for JAWS, NVDA, VoiceOver, speech input, and screen magnification.

The first thing that must always be covered is keyboard accessibility. Every intended action should be reachable and operable without depending on a mouse. ARIA alone does not provide this behavior.

Native controls, including Buttons, Links with href, Checkboxes, Textboxes, and Selects, generally supply appropriate keyboard interaction. A simulated control made from a DIV or SPAN does not. It needs focus management, a correct Role, an accessible Name, and the necessary keyboard event handling.

For a simulated Button, Enter and Space should activate the control. A native <button> already handles this, which is a strong reason to use it whenever possible. A control that merely has tabindex="0" may receive focus but still do nothing when activated.

Composite widgets often use Tab to enter or leave the component and Arrow keys to navigate inside it. Common focus approaches include moving DOM focus between items through a roving tabindex, or keeping DOM focus on a supported container while aria-activedescendant identifies the active item. The latter does not itself move focus, change selection, or scroll the active item into view.

The WhatSock Dynamic Data Grid and the following WhatSock examples demonstrate ways of navigating composite controls:

• ARIA Tabs
• ARIA Multiselect Listbox
• ARIA Menu
• ARIA Radio Buttons
• ARIA Tree

Familiar keyboard conventions can be found in the ARIA Authoring Practices keyboard guidance. These are useful examples and conventions, but any design still needs independent evaluation against applicable normative requirements and actual user behavior.

The Simulated Buttons exercise illustrates why a control's appearance, focusability, keyboard operation, and accessible Role are four different questions. In the exercise, the deliberately incomplete Buttons are labeled so their failures can be compared with a functional version.

Keyboard testing should also cover Tab and Shift+Tab order, Escape where appropriate, visible focus, focus restoration after closing a popup, zoom, and the ability to leave a component without becoming trapped.

Online example: Keyboard Accessibility demonstration on WhatSock

JAWS is a screen reader for Windows. It supports reading and navigating web content through a Virtual Cursor, and it has modes that allow keyboard commands to be sent to interactive controls.

During ordinary document reading, the Virtual Cursor may move among Headings, Links, and other content without changing the browser's DOM focus. When the user enters an interactive control, JAWS may change the way it handles the keyboard. The exact transition depends on the control, JAWS settings, browser, and version.

For this reason, never rely on a screen reader to manufacture a click event for an element that is missing native keyboard behavior. Use native Buttons and Links, or implement correct keyboard activation on custom controls.

When testing with JAWS, check the following:

1. Can a user identify the control's Name, Role, current State, and available action?
2. Can the user reach it by normal keyboard navigation and operate it using its documented commands?
3. Does the control remain usable when JAWS changes between reading and interaction modes?
4. Does actual browser focus move where expected, and is focus restored after dismissing a popup?
5. Are important changes announced without overwhelming unrelated speech?

Test the intended browsers rather than relying on compatibility claims made for Internet Explorer 11 or JAWS 15. Browser and screen-reader support has changed considerably since those versions were current.

For current documentation, see Freedom Scientific Support. A browser Accessibility panel can help identify computed semantics, but a JAWS interaction test is still necessary to confirm the user experience.

NVDA is an open-source screen reader for Windows. It includes a Browse Mode for reading content and a Focus Mode for operating many interactive controls. Like JAWS, NVDA can move a virtual reading position without necessarily moving DOM keyboard focus.

This distinction matters when scripting custom Widgets. For example, code that performs an action merely because an element receives focus may behave unexpectedly during assistive-technology navigation. Focus and selection are not always the same thing; the component needs to define when selection should change.

The Focus demonstration allows you to compare virtual reading with intentional DOM focus changes. The Radio Buttons demonstration provides examples of native and custom Radio interaction.

When testing with NVDA, confirm that the user can identify the available controls, navigate the page in Browse Mode, enter and leave Focus Mode when necessary, and use the control's keyboard interaction without missing content.

Do not assume that a specific browser is always best for NVDA or that the behavior of a historical version remains unchanged. For installation and current documentation, use the official NV Access website.

Online example: NonVisual Desktop Access demonstration on WhatSock

Online example: NonVisual Desktop Access demonstration on WhatSock

VoiceOver is the built-in screen reader on iPhone, iPad, and other Apple devices. On a touch screen, VoiceOver uses gestures and an accessibility navigation focus that can differ from the browser's ordinary DOM keyboard focus.

Content can be exposed to VoiceOver even when it is visually positioned outside the viewport for sighted users, depending on how it has been hidden or positioned. It is not accurate to assume that VoiceOver can access only content whose pixels are currently visible.

For this reason, visually hidden instructions and status messages must be designed carefully. A focusable control should not be moved far outside the viewport merely to hide it. Content that should not be operable must not remain unexpectedly in the accessibility navigation order.

A commonly used visually hidden text pattern is:

.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

This technique can be useful for explanatory text that should remain available to screen readers. It does not make an element inert or remove it from keyboard navigation. Do not apply it indiscriminately to interactive elements.

For an example of dynamic announcements, see the WhatSock Web Chat demonstration. Test actual live-region messages with current VoiceOver and browser versions; no particular announcement sequence is guaranteed by the markup alone.

Also test the interface with touch exploration, swipe navigation, double-tap activation, an external keyboard if supported, device rotation, and available text-sizing options. Navigation through the accessibility representation is different from ordinary touch events received by page scripts.

Speech input is important for users who cannot comfortably operate a mouse or keyboard. Products such as Dragon and the voice-control features built into operating systems can issue commands, activate controls by their names, and sometimes send keyboard shortcuts.

For speech users, a visible Label that agrees with the control's accessible Name is especially useful. If a Button says “Save Changes” visually, a person should be able to identify and activate that action through a matching spoken command when the speech tool supports it.

Keyboard access remains useful because many speech tools can issue equivalent keyboard commands. However, keyboard support alone does not ensure that an unlabeled simulated control can be discovered or activated by voice.

A complex example is the WhatSock Date Picker. Its documented keyboard commands include Arrow keys for moving among dates, Page Up and Page Down for moving between months, and Enter for selection. A speech-input user may be able to invoke those commands through the speech tool.

The available vocabulary and commands differ by application, operating system, and version. Test by speaking visible control labels, by issuing documented keyboard commands, and by completing a realistic task from beginning to end.

Also consult WCAG 2.2, Label in Name for the relationship between visible labels and the accessible Names of controls.

Screen magnification software, including ZoomText and built-in operating-system magnifiers, helps people enlarge content and follow the current area of interaction.

ARIA can provide useful semantics to accessibility software, but it does not substitute for a visible Label, readable text, clear focus indication, or a layout that remains usable when enlarged.

When reviewing a page with magnification, make sure that:

1. Interactive controls remain recognizable when part of the page is outside the visible viewport.
2. The current keyboard focus is clearly visible and is not hidden behind fixed or sticky content.
3. Text can be enlarged and reflowed without losing controls or instructions.
4. Meaning is not expressed through color alone, and the contrast remains adequate.
5. Labels remain visually associated with the controls they describe.

For standard HTML form controls, a visible <label> associated through its for and id attributes provides an accessible Name and allows the Label to be clicked to activate or focus the control.

{codeblock('First name ')}

Using aria-labelledby can provide an accessible Name as well, but it does not by itself reproduce the native Label's click-to-focus behavior. An aria-label may provide a Name without displaying that text visually, which can make a control harder for some users to identify.

For this reason, visible Labels and native HTML associations remain valuable even when ARIA labeling is available. The Accessible Name and Description Computation specification explains how the browser computes these Names; its output should be checked along with the rendered Label.

10/15/2026

Updated the accessibility API, ARIA Roles and States, drag-and-drop, live-region, browser inspection, keyboard, and Assistive Technology guidance. Updated the supporting demonstrations and reference links for contemporary browsers and specifications.

07/22/2014

Initial Release.

07/24/2014

Within section ARIA Categories > Landmarks and Regions > Region Role: Added Scrollable Divs subsection.
Within section Keyboard, Touch, and ATs > Dragon NaturallySpeaking: Updated ARIA support section to reflect recent press release.

08/01/2014

Within section ARIA, Important Details: Added ARIA Drag and Drop subsection.

08/15/2014

Within section Accessibility API > Simulated Web Controls using ARIA: Added Microsoft ARIA to UIA Role and Property mapping references.

08/18/2014

Within section Accessibility API > User Agent Implementation Guide: Fixed UAIG Introduction url to point to the correct page. (Reported by: Mark Sadecki)

08/25/2014

Within section ARIA Categories: Added Live Regions subsection.

09/02/2014

Within section Keyboard, Touch, and ATs > Keyboard Accessibility: Added direct design pattern demos.

12/07/2017

Within section Keyboard, Touch, and ATs > Keyboard Accessibility > JAWS For Windows: Updated the Applications Mode article link to reflect the most recent address.