Skip to main content

Headless UI Components

What is headless UI​

Headless (or unstyled) components ship behavior, state, keyboard interaction, focus management, and ARIA accessibility — but no visual styling. You get the hard, easy-to-get-wrong interaction logic for widgets like dialogs, popovers, comboboxes, and menus, while keeping full control of the visual layer (Tailwind, CSS Modules, or plain CSS) and composing the UI from small, composable parts.

Two headless libraries are used as the unstyled foundation under shadcn/ui:

  • Radix UI — shadcn/ui's original primitive layer, now maintained by WorkOS
  • Base UI — the shadcn/ui default primitive layer as of July 2026, from the Radix/Floating UI/MUI teams
note

You often consume these libraries indirectly. shadcn/ui is built on a headless primitive layer — Base UI by default, Radix UI as an opt-in — so most teams get these primitives without installing them directly.

Why we recommend them​

  • Accessibility without the busywork — WAI-ARIA-compliant behavior, keyboard nav, and focus management handled for you.
  • Total styling freedom — no design language imposed; style with Tailwind, CSS Modules, or plain CSS.
  • Composable primitives — small parts you assemble, ideal for building an owned design system.
  • Foundation under shadcn/ui — adopting shadcn means you're already benefiting from these primitives.
  • Shared lineage — Base UI comes from the Radix/Floating UI/MUI teams, so patterns transfer.

When to use​

  • Building a custom or branded design system where you own the visual layer.
  • You need accessible complex widgets (dialog, combobox, menu, popover) without adopting a full styled library.
  • You're using shadcn/ui — you're already on a headless layer; these pages explain what's underneath and how to pick.
  • You want to choose primitives directly for a bespoke component library.

When NOT to use​

  • You need breadth and speed with ready-made styled components — use MUI instead.
  • You want copy-paste, pre-styled components rather than building the visual layer yourself — use shadcn/ui.
  • Small or simple projects where hand-building accessible components isn't worth it.
  • Teams without the capacity to design and maintain their own visual layer.

Radix UI or Base UI?​

  • New projects / following shadcn's default: Base UI. It's the shadcn default as of July 2026, and adoption is running ~2-to-1 over Radix in new shadcn create projects.
  • Existing Radix projects: stay on Radix — fully supported, not deprecated, and both receive new components. No migration required.
  • Opting into Radix under shadcn: pnpm dlx shadcn init -b radix (also the path for non-interactive CI).
  • Mechanical migration delta if teams move: asChild (Radix) → render (Base UI); shadcn provides an agent-driven migration skill.
tip

For the full story on shadcn/ui switching its default primitive layer to Base UI, see the blog post shadcn/ui Makes Base UI the Default.

Resources​

  • Radix UI — headless primitives from WorkOS
  • Base UI — headless primitives from the Radix/Floating UI/MUI teams
  • shadcn/ui — built on these primitives
  • MUI — styled alternative from the same team behind Base UI
  • Tailwind CSS — the styling layer to pair with headless primitives
  • React — the UI library these target