The Trade-Off: Bundle Size vs Custom HTML
What you'll learn: Why headless libraries add weight to your bundle and when that cost is justified over writing custom markup.
The Real Cost of Accessibility
Headless libraries like Radix UI, React Aria, and Headless UI aren't free—they add kilobytes to your JavaScript bundle. A simple dialog primitive might include:
- Focus trap logic
- Screen reader announcements
- Keyboard navigation
- ARIA attribute management
- Portal rendering
All this robust accessibility infrastructure comes with code weight. For example, Radix Dialog adds ~15-20kb, while a basic custom <div> dialog is essentially zero bytes.
The Alternative: Manual ARIA Implementation
You could build everything yourself with custom HTML and ARIA attributes:
// Custom approach: minimal bundle size
<div
role="dialog"
aria-modal="true"
aria-labelledby="title"
>
{/* Manual focus management */}
{/* Manual escape key handling */}
{/* Manual backdrop clicks */}
</div>
This is lighter, but you're now responsible for every edge case: focus trapping, screen reader quirks across browsers, keyboard interactions, and maintaining it all.
Making the Choice
Use headless libraries when:
- Building complex widgets (dialogs, comboboxes, date pickers)
- Accessibility is non-negotiable
- You lack deep ARIA expertise
- Maintenance burden matters
Build custom when:
- The component is simple (basic tooltips, badges)
- Bundle size is critical (mobile-first apps)
- You need extreme performance
- You have accessibility expertise in-house
Key Takeaway: Headless libraries trade bundle kilobytes for bulletproof accessibility and maintenance ease—evaluate whether robust, tested ARIA implementation is worth the weight for each component in your project.