Article Angular

Article

Angular Aria: Headless Accessible UI Primitives in Angular 21

Angular Aria brings keyboard behavior, focus management, and ARIA semantics to custom UI without prescribing a visual design.

2 min read Angular

Custom UI is where accessibility gets expensive. A branded tab set or toolbar can look finished long before it supports the keyboard model, focus movement, state attributes, and screen-reader announcements that make it genuinely usable.

Angular 21 introduced Angular Aria: a set of headless directives for common WAI-ARIA patterns. It supplies the interaction and semantics; the application supplies the markup, styling, and product behavior. That division is the interesting bit. It lets a design system own its visual language without re-implementing accessibility mechanics for every component.

Angular Aria is a developer preview in Angular 21. It is usable today, but treat it with the usual upgrade care until the API is stable.

Install the package separately:

npm install @angular/aria

Headless means behavior, not a theme

Angular Aria is not a replacement skin for Angular Material. It is a lower-level tool for teams that need a custom design system. The package covers patterns such as accordions, tabs, menus, listboxes, trees, grids, comboboxes, and toolbars.

For a toolbar, the component imports the directives it needs:

import {Component} from '@angular/core';
import {Toolbar, ToolbarWidget, ToolbarWidgetGroup} from '@angular/aria/toolbar';

@Component({
  selector: 'app-editor-toolbar',
  imports: [Toolbar, ToolbarWidget, ToolbarWidgetGroup],
  templateUrl: './editor-toolbar.html',
})
export class EditorToolbar {}

Then the template expresses the structure. The directives take responsibility for the keyboard behavior and the selection model; the buttons remain ordinary, stylable buttons.

<div ngToolbar aria-label="Text formatting">
  <div class="group">
    <button
      ngToolbarWidget
      #bold="ngToolbarWidget"
      value="bold"
      type="button"
      aria-label="Bold"
      [aria-pressed]="bold.selected()"
    >
      B
    </button>
    <button
      ngToolbarWidget
      #italic="ngToolbarWidget"
      value="italic"
      type="button"
      aria-label="Italic"
      [aria-pressed]="italic.selected()"
    >
      I
    </button>
  </div>

  <div ngToolbarWidgetGroup role="radiogroup" class="group" aria-label="Text alignment">
    <button
      ngToolbarWidget
      #alignLeft="ngToolbarWidget"
      role="radio"
      value="align-left"
      type="button"
      aria-label="Align left"
      [aria-checked]="alignLeft.selected()"
    >
      Left
    </button>
    <button
      ngToolbarWidget
      #alignCenter="ngToolbarWidget"
      role="radio"
      value="align-center"
      type="button"
      aria-label="Align center"
      [aria-checked]="alignCenter.selected()"
    >
      Center
    </button>
  </div>
</div>

Two responsibilities are worth separating here. Angular Aria owns roving focus, arrow-key traversal, and which widget is selected; the template declares the roles and binds the state each widget exposes through selected(). Independent toggles are ordinary buttons with aria-pressed. ngToolbarWidgetGroup is what makes a set mutually exclusive—a radiogroup whose children report aria-checked—and its multi input relaxes that to allow several selections at once.

The product still decides what “bold” does. Angular Aria makes the interaction predictable for people who navigate with a keyboard or assistive technology.

CSS is part of the contract

Headless does not mean unstyled by accident. It means state is exposed for CSS to consume. A tab implementation, for example, can use aria-selected as its styling hook:

.tab[aria-selected='true'] {
  border-bottom: 2px solid var(--brand);
  color: var(--brand);
}

.tab:focus-visible {
  outline: 3px solid var(--focus-ring);
  outline-offset: 3px;
}

That approach is preferable to maintaining a second “selected” class that can drift from the accessible state. The ARIA state is both semantic and visual truth.

Where it fits—and where it does not

Angular Aria is a strong fit for a shared component library, an enterprise product with strict brand requirements, or any custom interaction that would otherwise need bespoke focus and keyboard code. It is not a reason to turn every native control into a custom widget. Use native buttons, inputs, radios, and selects for straightforward cases; they already provide excellent semantics.

Likewise, choose Angular Material when a pre-styled component is the desired outcome. The point of Angular Aria is control, and control carries a styling and testing responsibility.

The practical takeaway: start with one difficult pattern—tabs, a menu, or a toolbar—not a wholesale design-system rewrite. Keep semantic HTML, style the states Angular Aria exposes, and test with keyboard navigation as a product feature. Angular’s Angular Aria overview is the best starting point and includes working examples for each supported pattern.

Related articles

Keep reading

Search

Search the publication

Search articles and topic pages without leaving the page.