Headless UI - Components That Don't Look Like Ass

You know that dropdown you've been tweaking for 3 hours, trying to get the focus management right? The one where pressing Escape sometimes works and sometimes doesn't? Headless UI's Menu component handles all that keyboard navigation bullshit for you. You just worry about making it look good.

The Problem It Solves

Ever tried overriding Material-UI's button styles to match your design system? Spent 2 days fighting with Bootstrap's modal z-index? This is exactly why Headless UI exists.

Traditional libraries like Material-UI, Ant Design, and Chakra UI give you pretty components that look exactly like everyone else's app. Headless UI gives you the behavior without the baggage. No more CSS specificity wars. No more !important everywhere. No more explaining to your PM why the "simple" dropdown took 3 days when Material-UI's z-index system conflicts with your layout.

What You Get (Besides a Headache)

Every Headless UI component handles the shit that you'd probably mess up:

• Keyboard navigation that actually works - Tab, Enter, Escape do what users expect. I've tested this shit with screen readers, it's solid.
• Focus trapping in modals - No more users tabbing into the background while your modal is open. This alone saves hours of debugging.
• Screen reader support - ARIA labels, roles, and states that actually make sense to assistive technology
• Mobile touch handling - Touch events that don't break your keyboard navigation
• State management - Open/closed, selected, disabled states managed properly

React gets all the new stuff first. Vue support is stuck on v1.x because Tailwind Labs clearly doesn't give a shit about Vue users - you get updates whenever they feel like porting them over. The form components that shipped in React v2.0 took forever to reach Vue, and some features are still missing.

React 17.x breaks the Transition component with Concurrent Mode. You'll get "Cannot read properties of null" or "ReferenceError: process is not defined" errors. Upgrade to React 18+ or disable Concurrent Mode. Learned that after debugging for 3 hours wondering why transitions randomly stopped working.

The Bundle Size Reality Check

Headless UI React is like 50KB. Material-UI? Christ, it's over 300KB. Ant Design is even worse. But here's the catch everyone forgets to mention: you're trading bundle size for development time.

Yes, your JavaScript bundle is smaller. But you're about to write a ton of CSS. Pick your poison:

• Big bundle, components work out of the box
• Small bundle, plan on 2-3x longer styling time

Accessibility: The Good and the Bad

The accessibility stuff is genuinely excellent. Focus management, keyboard navigation, screen reader support - it's all there and it actually works. I've tested it with NVDA, JAWS, and VoiceOver.

But accessibility isn't just JavaScript. You can still fuck it up with bad CSS. Hide something with display: none that should be visibility: hidden? Congratulations, you just broke screen reader navigation. Read WebAIM's guide to CSS and accessibility and MDN's accessibility best practices. The components give you the foundation; don't screw up the styling layer with CSS that breaks accessibility.

So you've decided Headless UI beats the alternatives for your project. Good choice. Now here's what you actually get - 15 components that handle the interaction patterns most developers completely screw up. These aren't just random UI elements; they're the specific components where accessibility and keyboard handling matter most.

The Complex Stuff That Breaks in Production

Interactive Components (The Hard Ones)

These are the components where you'd spend weeks getting the behavior right:

• Menu - Dropdown menus that don't break when you hit Escape or click outside
• Dialog - Modals with focus trapping that actually works (no more tabbing into the background)
• Popover - Floating panels that position correctly and close when they should
• Disclosure - Collapsible sections that screen readers understand
• Tabs - Tab navigation with arrow key support and proper ARIA relationships
• Transition - Enter/leave animations that don't fuck with accessibility

Form Components (v2.0+ Actually Handles Forms)

The newer versions include solid form components that handle validation properly:

• Button - Buttons with loading states and proper disabled handling
• Input - Text inputs that work with form libraries and show validation states
• Textarea - Auto-resizing textareas that don't break your layout
• Select - Custom selects that look consistent across browsers
• Checkbox - Checkboxes with indeterminate state support
• Switch - Toggle switches that actually feel responsive
• Radio Group - Radio groups with keyboard navigation between options
• Listbox - Multi-select components that don't suck
• Combobox - Autocomplete/search inputs with proper keyboard handling

Form Structure (The Boring But Important Stuff)

Form wrapper components that handle the ARIA relationships:

• Fieldset - Groups related form controls (actually useful for complex forms)
• Field - Individual form field containers with error state support
• Label - Labels that properly associate with form controls
• Description - Help text that screen readers announce
• Legend - Fieldset labels that accessibility tools understand

Implementation Reality

Basic Usage (It's Pretty Straightforward)

Most components follow the same pattern - controlled state with onChange handlers:

import { useState } from 'react'
import { Switch } from '@headlessui/react'

function MyToggle() {
  const [enabled, setEnabled] = useState(false)

  return (
    <Switch
      checked={enabled}
      onChange={setEnabled}
      // This className gets messy fast with responsive design
      className="relative inline-flex h-6 w-11 items-center rounded-full bg-gray-200"
    >
      {/* Don't use display:none on this span - breaks screen readers */}
      <span className={`inline-block h-4 w-4 transform rounded-full bg-white transition ${
        enabled ? 'translate-x-6' : 'translate-x-1'
      }`} />
    </Switch>
  )
}

CSS Integration (Choose Your Hell)

This CSS integration stuff is where you'll spend most of your time cursing. Headless UI works with whatever CSS solution you're using:

• Tailwind CSS - Obviously the intended pairing, works great with Tailwind UI components
• CSS Modules - Regular CSS with scoped classes, totally fine
• Styled Components - CSS-in-JS, some extra work for dynamic classes
• Emotion - Similar to styled-components, manageable
• Regular CSS - Just add class names, nothing fancy needed

Framework Support Reality Check

React:

• Full TypeScript support that actually works
• Supports modern React versions, works fine with Next.js, Vite, etc.
• SSR works, but test your transitions for hydration issues

Vue (always behind React):

• Vue 3 only, Composition API
• TypeScript support exists but not as comprehensive
• Works with Nuxt but some features missing
• Vue version always gets updates months later

Our Vue team wasted half a day on a Dialog SSR bug in Nuxt. Dialog components wouldn't render server-side, throwing "ReferenceError: document is not defined" errors. Already fixed in React but nobody bothered porting to Vue. Ended up with a hacky process.client workaround that still makes me cringe.

Spent 4 hours debugging why focus trapping broke in production. CSS minifier was removing focus-visible styles. Production was broken for keyboard users for a week because QA doesn't test accessibility. The Menu component breaks if you nest it inside a form with onSubmit - learned that the hard way too.

Who Actually Uses This

Look, here's when this shit makes sense vs when it'll make you want to quit coding:

• Your design team is picky - They want pixel-perfect implementations following design systems, not "close enough"
• Performance matters - Mobile users, slow connections, or strict Core Web Vitals budgets
• Accessibility is mandatory - WCAG 2.1 AA compliance, legal requirements, government contracts, or just giving a shit
• You're already using Tailwind - The integration works great and the workflow makes sense
• You have strong CSS skills - Junior devs will struggle without good styling knowledge

It's not great for:

• Rapid prototyping - Material-UI or Ant Design will be faster for MVPs
• Small internal tools - The styling effort isn't worth it, use Mantine or similar instead
• Teams with weak CSS skills - You'll spend more time on styling than features, consider CSS learning resources
• Tight deadlines - Pre-styled components like React Bootstrap are faster for generic designs