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.
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
Jul 7, 2026
Angular 21 Signal Forms: A Practical Guide for Reactive Forms Developers
A hands-on guide to Angular Signal Forms for reactive-forms developers: models, fields, validation, submission, cross-field rules, async work, and a measured migration path.
Jun 6, 2026
Vitest Is Angular’s Primary Test Runner: A Practical Karma Migration
Move an existing Angular unit-test suite from Karma and Jasmine to the Angular CLI’s Vitest runner without treating it as a blind search-and-replace.
May 12, 2026
Zoneless by Default: What Angular 21 Changes in Practice
Angular 21 makes zoneless change detection the default. Here is what changes, what to remove, and how to prepare an established app.