Course contentsShow
← React
Lesson 1194 of 2,39630. Composition: Inversion of ControlFree lesson

The Trade-Off: Bundle Size vs Custom HTML

Headless libraries add kilobytes for robust accessibility; decide if the cost is worth avoiding manual ARIA implementation for complex widgets.

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.