# The Accessibility Tree and WAI-ARIA Semantics vs Custom Elements Lifecycle and Upgrade Reactions

- **Canonical URL:** https://frontend.rocks/vs/accessibility-tree-aria-vs-custom-elements-lifecycle/
- **Relation:** Contrasts With
- **Last Verified:** 2026-11-15
- **Verdict:** Native elements expose built-in ARIA semantics, whereas autonomous custom elements require ElementInternals to wire roles.

## Comparison Matrix

| Dimension | The Accessibility Tree and WAI-ARIA Semantics | Custom Elements Lifecycle and Upgrade Reactions |
| :--- | :--- | :--- |
| **Maturity** | Baseline · Widely | Baseline · Widely |
| **Domain** | Security & Accessibility | DOM & Events |
| **Mental Model** | Parallel OS-exposed tree derived from the DOM and CSSOM that computes each element's Role, Accessible Name, States, and Properties for assistive technologies. | Build framework-agnostic UI primitives without hydration races—customElements.define() upgrades existing DOM nodes via deterministic lifecycle reaction queues. |
| **Prerequisites** | Browser Rendering Pipeline (Critical Rendering Path) (CSS visibility (display: none, visibility: hidden) prunes nodes from the Accessibility Tree.) | Shadow DOM Encapsulation and Event Retargeting (Custom elements typically attach a ShadowRoot in constructor() and hydrate slots in connectedCallback().); Prototype Chain Lookup and Delegation (Element upgrades swizzle the DOM node's [[Prototype]] to the registered HTMLElement subclass.) |
| **When Not to Use** | When not to use ARIA: Whenever a native HTML element (<button>, <a href>, <input>, <dialog>) already carries the required role and keyboard behavior, omit redundant role attributes; for Custom Elements, expose roles via ElementInternals instead of mutating host aria-* attributes. | When not to use Custom Elements: Avoid wrapping every leaf UI primitive in a custom element if your app already compiles single-framework SSR templates, use them for cross-framework widgets or design-system leaves. |

## The Accessibility Tree and WAI-ARIA Semantics — Under the Hood
If the [Browser Rendering Pipeline](/concepts/browser-rendering-pipeline) paints pixels for eyes, the Accessibility Tree serializes a structured wireframe for OS assistive APIs (`UIA` on Windows, `NSAccessibility` on macOS, `ATK` on Linux).

1. **CSS Pruning**: `display: none`, `visibility: hidden`, and `aria-hidden="true"` remove nodes from the Accessibility Tree, whereas `opacity: 0` leaves them exposed.
2. **AccName Computation**: Engines resolve an element's Accessible Name in strict precedence: `aria-labelledby` > `aria-label` > native `<label>`/`alt` > text content.
3. **Metadata Only**: Setting `role="button"` changes the tree node's role string, but does not wire `Tab` focus or `Enter`/`Space` key activation, unlike `<button>` or [Native Dialog](/concepts/native-dialog-element).

```html
<!-- Bad: role="presentation" or aria-hidden="true" on a focusable control -->
<button aria-hidden="true">Broken</button>

<!-- Good: native semantics + dynamic ARIA state + live region -->
<button type="button" aria-expanded="false" aria-controls="menu-list">
  Options
</button>
<div role="status" aria-live="polite">Saved 3 items.</div>
```

## Custom Elements Lifecycle and Upgrade Reactions — Under the Hood
The HTML parser instantiates unregistered hyphenated tags as `HTMLUnknownElement` nodes until `customElements.define()` runs an upgrade pass, swizzling each node's prototype and queuing its reactions. Only when the element is inserted into a connected document does `connectedCallback()` fire to wire listeners and external state.

1. **Pre-Upgrade State**: Unregistered `<my-el>` tags render as `HTMLUnknownElement` until `define()` runs and swizzles their prototype.
2. **Restricted `constructor()`**: The spec forbids reading or mutating attributes or light-DOM children inside `constructor()`; attach `ShadowRoot` there and defer DOM setup to `connectedCallback()`.
3. **Move Re-Fires**: Moving an element via `append()` fires `disconnectedCallback()` then `connectedCallback()` (unless `moveBefore()` is used).

```js
class ToastBanner extends HTMLElement {
  static observedAttributes = ['open'];
  #ctrl;
  connectedCallback() {
    this.#ctrl = new AbortController();
    window.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') this.removeAttribute('open');
    }, { signal: this.#ctrl.signal });
  }
  disconnectedCallback() { this.#ctrl?.abort(); }
}
customElements.define('toast-banner', ToastBanner);
```

## Interactive Labs & Dissections
- [The Accessibility Tree and WAI-ARIA Semantics Lab](https://frontend.rocks/concepts/accessibility-tree-aria/#lab) ([Markdown](https://frontend.rocks/concepts/accessibility-tree-aria.md))
- [Custom Elements Lifecycle and Upgrade Reactions Lab](https://frontend.rocks/concepts/custom-elements-lifecycle/#lab) ([Markdown](https://frontend.rocks/concepts/custom-elements-lifecycle.md))

## Primary Sources
- https://developer.mozilla.org/en-US/docs/Glossary/Accessibility_tree
- https://w3c.github.io/aria/
- https://html.spec.whatwg.org/multipage/custom-elements.html#custom-element-reactions
- https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
