A few weeks ago I went through every "headless UI primitive" in @snatuva/primitives — our Angular signals-first, unstyled component library — and started asking an uncomfortable question for each one:
Is this directive replacing something the browser already does for free?
For the Dialog and Accordion primitives, the answer was yes, almost entirely. We were shipping our own focus trap, our own scroll lock, our own backdrop, our own open/close state machine, our own keyboard handling for a disclosure widget — all things <dialog> and <details>/<summary> have done natively for years.
So we ripped it out. Here's what changed, what we kept, and why "use the platform" isn't just a slogan — it's a real diff with negative lines.
The old way: a <div> pretending to be a dialog
Most headless dialog implementations (ours included) used to look roughly like this:
<div apDialog>
<button apDialogTrigger>Edit Profile</button>
<div apDialogOverlay class="overlay">
<div apDialogContent class="panel">
<h2 apDialogTitle>Edit Profile</h2>
<p apDialogDescription>Make changes to your profile here.</p>
<!-- form -->
<button apDialogClose>Save</button>
</div>
</div>
</div>
Looks reasonable. But behind that apDialogContent directive was a pile of code doing things the DOM is fully capable of doing itself:
- Focus trap — manually querying focusable elements, listening for Tab/Shift+Tab, redirecting focus at the boundaries
-
Focus restoration — remembering
document.activeElementbefore open, restoring it on close -
Scroll lock — toggling
overflow: hiddenon<body>, often fighting with scrollbar-width shifts -
Backdrop — a separate
apDialogOverlayelement, positioned and styled by hand -
Escape to close — a global
keydownlistener -
Inert background — manually setting
aria-hiddenorinerton everything else
That's a lot of edge-case-prone JavaScript for something that has existed as a single HTML element since 2022.
The new way: <dialog>
<dialog apDialogContent class="panel">
<h2 apDialogTitle>Edit Profile</h2>
<p apDialogDescription>Make changes to your profile here.</p>
<!-- form -->
<button apDialogClose>Save</button>
</dialog>
<button apDialogTrigger>Edit Profile</button>
The directive now does this:
@Directive({
selector: 'dialog[apDialogContent]',
standalone: true,
host: {
'(cancel)': 'onCancel($event)',
'(close)': 'onClose()',
},
})
export class DialogContentDirective {
private readonly dialog = inject(DialogDirective);
private readonly el = inject(ElementRef<HTMLDialogElement>);
constructor() {
effect(() => {
const open = this.dialog.open();
const native = this.el.nativeElement;
if (open && !native.open) {
this.dialog.modal() ? native.showModal() : native.show();
} else if (!open && native.open) {
native.close();
}
});
}
onCancel(event: Event): void {
if (!this.dialog.closeOnEscape()) event.preventDefault();
}
onClose(): void {
this.dialog.setOpen(false);
}
}
That's the entire implementation. showModal() gives us, for free:
- Focus trap — Tab/Shift+Tab can't escape the dialog
- Focus restoration — focus returns to the trigger on close
-
::backdrop— a real pseudo-element, styleable with CSS, no extra DOM node -
Escape to close — fires a cancelable
cancelevent -
Inert background — everything outside the dialog is automatically inert (not just
aria-hidden, actually un-interactable and unfocusable) -
role="dialog"/aria-modal— implicit ARIA semantics, baked in
Our directive's job shrank to: sync our open signal with showModal()/close(), and let the user opt out of Escape-to-close if they want a confirmation step instead. Everything else — the overlay directive, the focus-trap service, the scroll-lock service — deleted.
Same story for Accordion: <details> / <summary>
The accordion primitive had a near-identical story. The old version:
<div apAccordionItem itemId="item-1">
<button apAccordionTrigger>What are headless UI primitives?</button>
<div apAccordionContent>
Headless primitives provide behavior and accessibility without
imposing any visual styles.
</div>
</div>
...with a directive tracking expanded/collapsed state, toggling [hidden] on the content, managing aria-expanded/aria-hidden/aria-controls, and wiring up Enter/Space activation on the trigger button.
The new version:
<details apAccordionItem itemId="item-1" class="group">
<summary apAccordionTrigger class="list-none [&::-webkit-details-marker]:hidden">
What are headless UI primitives?
<svg class="transition-transform group-data-[state=open]:rotate-180" ...>
<!-- chevron -->
</svg>
</summary>
<div apAccordionContent>
Headless primitives provide behavior and accessibility without
imposing any visual styles.
</div>
</details>
<summary> is natively focusable, natively keyboard-activatable (Space and Enter both toggle the parent <details>), and <details> natively hides everything except the <summary> when closed — no [hidden] bindings, no aria-hidden juggling.
What's left for the directive to do?
@Directive({
selector: 'details[apAccordionItem]',
standalone: true,
host: {
'[attr.data-state]': 'dataState()',
'[attr.data-disabled]': 'isDisabled() || null',
'(toggle)': 'onToggle()',
},
})
export class AccordionItemDirective {
private readonly accordion = inject(AccordionDirective);
private readonly el = inject(ElementRef<HTMLDetailsElement>);
readonly id = input.required<string>({ alias: 'itemId' });
readonly isExpanded = computed(() => this.accordion.isExpanded(this.id()));
constructor() {
effect(() => {
const expanded = this.isExpanded();
if (this.el.nativeElement.open !== expanded) {
this.el.nativeElement.open = expanded;
}
});
}
onToggle(): void {
// Reconcile native <details> toggle with accordion state
// (e.g. enforce single-open / collapsible semantics)
if (this.el.nativeElement.open !== this.isExpanded()) {
this.accordion.toggle(this.id());
}
}
}
The directive's entire job is now: listen to the native toggle event and reconcile it with accordion-level rules (single vs. multiple expansion, collapsible, disabled). The browser does the toggling, hiding, focus, and keyboard handling. We just add the "accordion" semantics on top — single-open mode, ARIA role="region" on the panel, data-state for CSS transitions, and roving arrow-key navigation across triggers per the WAI-ARIA Accordion pattern.
Why this matters
-
Less code to ship. Every focus-trap loop, scroll-lock service, and
[hidden]binding we delete is bytes the browser doesn't need to send, parse, or run. - Fewer bugs. Focus trapping is notoriously easy to get wrong (iframes, shadow DOM, dynamically added content). The browser's implementation has been battle-tested across every site on the web.
-
Better baseline accessibility.
<dialog>and<details>/<summary>come with correct ARIA roles and keyboard behavior out of the box — your directive can't "forget" to addrole="dialog"if the element already implies it. - The directive's purpose becomes obvious. Once the platform handles "is it open, does it trap focus, can I tab into it," what's left in the directive is exactly the value your library adds — accordion grouping rules, animation hooks, Angular signal bindings. No more guessing what's "ours" vs. "boilerplate."
What didn't change
To be clear, this isn't "delete all your JavaScript." Things like a Switch, Checkbox with indeterminate, or a RadioGroup with a shared name still benefit from a thin directive layer — indeterminate is a DOM-only property Angular can't bind declaratively, and coordinating a [(value)] signal across a group of native radios is real, useful glue code. The native-element refactor isn't about doing nothing — it's about not reinventing what the platform already ships, so the directive's surface area maps exactly to the value it adds.
Try it
@snatuva/primitives is a free, open, signals-first, headless primitives library for Angular — Tabs, Accordion, Dialog, Tooltip, Select, Switch, Checkbox, and Radio Group, all unstyled and built on Angular Signals.
npm install @snatuva/primitives
If you're building a design system on Angular and tired of fighting NgModule-based component libraries for basic interaction patterns, give it a look — and if you spot a primitive that's still doing the browser's job for it, open an issue. That's exactly the kind of thing we're hunting for now.
Top comments (0)