Headless components

Headless means the library owns behavior, you own the DOM. A styled component bundles three things: behavior (open/close, selection, keyboard), accessibility (roles, aria-*, focus), and presentation (markup + CSS). A headless component keeps the first two and hands you the third. It exposes its work as hooks, render props, or prop-getters — never as finished markup.

// A styled library: you get its <div>, its classes, its structure. You override.
<Combobox className="lib-combobox" /* now fight its internals */ />

// A headless library: it gives you behavior + a11y props; YOU write the elements.
const { getInputProps, getMenuProps, getItemProps, isOpen } = useCombobox({ items });
return (
  <div className="my-combobox">
    <input {...getInputProps()} className="my-input" />
    <ul {...getMenuProps()} className={isOpen ? "my-menu open" : "my-menu"}>
      {isOpen && items.map((item, i) => (
        <li key={item.id} {...getItemProps({ item, index: i })} className="my-row">
          {item.label}
        </li>
      ))}
    </ul>
  </div>
);

The library decides what the input and each row must announce and how arrow keys move selection; you decide what they look like and where they sit.

You inherit the accessibility and keyboard work that is genuinely hard to get right. This is the real payoff. A correct listbox needs role, aria-activedescendant, aria-expanded, aria-controls, roving focus, Home/End/PageUp/PageDown handling, type-ahead, and announcements — a multi-week project to do well, and a perennial source of bugs when hand-rolled. A headless primitive bakes this into its prop-getters, so spreading them onto your elements gives you a WAI-ARIA-compliant widget with your own skin.

// Radix is headless: unstyled, accessible primitives you compose and style yourself.
import * as Dialog from "@radix-ui/react-dialog";

export function ConfirmDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger className="btn">Delete</Dialog.Trigger>
      <Dialog.Portal>
        {/* focus trap, Esc-to-close, scroll lock, aria-modal, restore-focus: all free */}
        <Dialog.Overlay className="overlay" />
        <Dialog.Content className="card">
          <Dialog.Title className="title">Delete project?</Dialog.Title>
          <Dialog.Close className="btn-danger">Confirm</Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Every className is yours. Every focus trap, Esc handler, and aria-modal is the library’s. You did not write the part most teams get wrong.

Custom look has no cost, because there are no styles to override. With a styled kit, customization is subtraction — you remove and override what shipped. With headless, customization is the default state: nothing ships styled, so you never reverse-engineer a library’s CSS specificity or shadow-DOM. The same headless useReactTable powers a dense admin grid and an airy marketing table; the behavior is shared, the markup diverges completely.

import { useReactTable, getCoreRowModel, flexRender } from "@tanstack/react-table";

const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });

// TanStack Table is headless: it gives you the row model + state, no <table> at all.
return (
  <table className="my-grid">
    <tbody>
      {table.getRowModel().rows.map((row) => (
        <tr key={row.id} className="my-row">
          {row.getVisibleCells().map((cell) => (
            <td key={cell.id} className="my-cell">
              {flexRender(cell.column.columnDef.cell, cell.getContext())}
            </td>
          ))}
        </tr>
      ))}
    </tbody>
  </table>
);

Sorting, filtering, pagination, grouping — all behavior, zero markup. You render whatever the design demands.

Failure mode: a headless abstraction for one in-app widget with exactly one look is speculative generality. Headless earns its keep when behavior is shared but appearance varies — across an app, a design system, or a library’s many consumers. If you have a single dropdown used in one place with one design, building your own useDropdown headless layer (prop-getters, generic state, render props) buys you nothing: there is no second look to vary, no third consumer to serve. You’ve paid the abstraction’s full cost — indirection, a generic API, more files — for a flexibility you will never use.

// Over-engineering: a homegrown headless layer for ONE component with ONE look.
function useDropdown<T>() { /* prop-getters, generic state, a render-prop API… */ }
function AppMenu() {
  const { getToggleProps, getItemProps, isOpen } = useDropdown<MenuItem>();
  // …used in exactly one place, styled exactly one way, forever
}

// Senior choice: a plain component. Reach for headless only when variation is real.
function AppMenu() {
  const [open, setOpen] = useState(false);
  return /* the one markup this app needs */;
}

Consuming a published headless library (Radix, Headless UI) is cheap and almost always right — someone already paid the abstraction cost and the a11y is battle-tested. Authoring your own headless layer is only worth it once you genuinely have multiple looks over one behavior.