Radix Primitives vs Base UI: Evaluating Next-Gen Headless Component Architectures

Headless component libraries have moved from novelty to core infrastructure. Radix Primitives and Base UI both promise accessible, unstyled React primitives, but they encode different bets about composition, state, and customization. The choice affects your design system API, your accessibility review process, and how much glue code your team maintains.

The Headless Contract: Behavior Without Opinion

Headless UI is not merely CSS-free markup. A production headless primitive owns the hard parts: ARIA roles and relationships, focus trapping and restoration, escape and outside-click dismissal, collision-aware positioning, scroll locking, RTL direction, and controlled/uncontrolled state. Radix Primitives and Base UI both implement patterns from the WAI-ARIA Authoring Practices, but neither certifies WCAG compliance. You still own content, labels, contrast, motion preferences, and test coverage.

Both libraries expose compound components. You compose Root, Trigger, Portal, and content parts, then style them with data attributes and CSS variables. The architectural difference is how they let you replace the underlying element.

Radix Primitives: Slot-Based Composition and Data-State Styling

Radix Primitives, maintained by WorkOS, uses a Slot-based composition model. The asChild prop merges the primitive's behavior and event handlers into your child element. Internally, Radix relies on layers such as DismissableLayer, FocusScope, Portal, and Presence, and it exposes state through data-state, data-side, and CSS custom properties for positioning.

import * as Dialog from '@radix-ui/react-dialog';
import { useState, type ReactElement } from 'react';

type ConfirmDialogProps = {
  trigger: ReactElement;
  title: string;
  description: string;
  onConfirm: () => Promise<void>;
};

export function ConfirmDialog({ trigger, title, description, onConfirm }: ConfirmDialogProps) {
  const [open, setOpen] = useState(false);
  const [pending, setPending] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function handleConfirm() {
    setPending(true);
    setError(null);
    try {
      await onConfirm();
      setOpen(false);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Something went wrong');
    } finally {
      setPending(false);
    }
  }

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger asChild>{trigger}</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className='dialog-overlay' />
        <Dialog.Content className='dialog-content' aria-describedby='confirm-description'>
          <Dialog.Title>{title}</Dialog.Title>
          <Dialog.Description id='confirm-description'>{description}</Dialog.Description>
          {error ? <p role='alert'>{error}</p> : null}
          <div className='dialog-actions'>
            <Dialog.Close asChild>
              <button type='button' disabled={pending}>Cancel</button>
            </Dialog.Close>
            <button type='button' onClick={handleConfirm} disabled={pending}>
              {pending ? 'Working...' : 'Confirm'}
            </button>
          </div>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

The snippet shows the production contract: controlled open state, async confirmation with error handling, and asChild on both trigger and close button. Radix's strength is ecosystem maturity: broad component coverage, extensive examples, and optional Radix Themes. The trade-off is that asChild can hide DOM structure. If your child does not forward refs or compose event handlers correctly, focus and dismissal can break.

Base UI: Render Props, Hooks, and MUI Lineage

Base UI comes from the MUI team and is the successor to MUI Base. It uses an explicit render prop and a useRender hook instead of asChild. Components are still compound: Dialog.Root, Dialog.Trigger, Dialog.Portal, Dialog.Backdrop, Dialog.Popup, Dialog.Title, Dialog.Description, and Dialog.Close. The render prop accepts a React element or a function that receives props, which makes the element replacement contract visible at the call site.

import { Dialog } from '@base-ui-components/react/Dialog';
import { useState, type ReactElement } from 'react';

type ConfirmDialogProps = {
  trigger: ReactElement;
  title: string;
  description: string;
  onConfirm: () => Promise<void>;
};

export function ConfirmDialog({ trigger, title, description, onConfirm }: ConfirmDialogProps) {
  const [open, setOpen] = useState(false);
  const [pending, setPending] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function handleConfirm() {
    setPending(true);
    setError(null);
    try {
      await onConfirm();
      setOpen(false);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Something went wrong');
    } finally {
      setPending(false);
    }
  }

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger render={trigger} />
      <Dialog.Portal>
        <Dialog.Backdrop className='dialog-overlay' />
        <Dialog.Popup className='dialog-content'>
          <Dialog.Title>{title}</Dialog.Title>
          <Dialog.Description>{description}</Dialog.Description>
          {error ? <p role='alert'>{error}</p> : null}
          <div className='dialog-actions'>
            <Dialog.Close render={<button type='button' disabled={pending} />}>
              Cancel
            </Dialog.Close>
            <button type='button' onClick={handleConfirm} disabled={pending}>
              {pending ? 'Working...' : 'Confirm'}
            </button>
          </div>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Base UI's model is more verbose but often easier to audit: you can see exactly which element receives the primitive props. It also ships newer primitives such as Combobox, NumberField, Field, and Meter, which matter for form-heavy applications. The trade-off is a younger ecosystem and fewer third-party examples than Radix. The MUI lineage is useful if your organization already standardizes on MUI conventions.

API Trade-Offs: asChild vs render

Both libraries require ref forwarding and event merging when you customize triggers. A custom trigger that swallows onClick or onKeyDown will break keyboard behavior even if the primitive is correct.

Accessibility Compliance: What the Library Guarantees and What You Still Own

Both libraries handle keyboard navigation, focus management, and ARIA relationships for their patterns. That is not the same as accessibility compliance. A dialog can be modal and focus-trapped and still fail because the title is missing, the description is not announced, the close button has no accessible name, or the contrast ratio is 3.2:1.

Use this production checklist:

• Every trigger has an accessible name.
• Every dialog has a title; a description is recommended.
• Async errors use role='alert' or a polite live region.
• Focus-visible styles meet WCAG 2.2 focus appearance.
• Motion respects prefers-reduced-motion.
• Touch targets meet the 24x24 CSS px minimum.
• Test with keyboard only, screen readers, and axe-core in CI.

Use Playwright or Cypress to assert focus return and escape behavior, not just visual snapshots. Run axe-core against open states, because many violations only appear after portal content mounts.

SSR, Portals, and Animation: Production Architecture Notes

Portals are where headless libraries meet application architecture. A dialog rendered into document.body leaves your React context unless you explicitly bridge theme and i18n providers. Both libraries let you supply a portal container; use it to keep design tokens, direction, and test selectors consistent.

Animation exit is another common failure. If you conditionally unmount content immediately on close, exit animations never run. Use the library's presence or keep-mounted mechanism and drive CSS from state attributes. For Radix, Presence and data-state are the usual tools. For Base UI, use the documented transition data attributes and keep-mounted behavior for your version.

Watch for nested dialogs and scroll lock conflicts. A second modal must not release the first modal's scroll lock. Test stacked layers, focus return to the correct trigger, and escape ordering. On mobile, virtual keyboards can resize the viewport and break popover positioning; verify with real devices. RTL support is not automatic just because positioning is. Set dir on the portal container and test collision handling, arrow keys, and slide animations in both directions.

Decision Matrix and Migration Checklist

Before migrating, inventory every primitive in use, including undocumented internal imports. Verify custom triggers forward refs and merge handlers. Audit portal containers, z-index layers, and animation unmount behavior. Run accessibility tests against open, loading, error, and RTL states. Measure bundle size after tree-shaking, not from package size alone.

Both libraries are credible foundations. Radix is the safer default for teams that want maximum ecosystem coverage and a concise composition API. Base UI is compelling for teams that prefer explicit render contracts, need newer form and combobox primitives, or are already aligned with MUI. The wrong choice is treating either as a compliance certificate rather than a behavior layer.

Sources & Technical References

• Radix Primitives introduction: https://www.radix-ui.com/primitives/docs/overview/introduction
• Radix Primitives accessibility: https://www.radix-ui.com/primitives/docs/overview/accessibility
• Radix Primitives composition guide: https://www.radix-ui.com/primitives/docs/guides/composition
• Radix Primitives styling guide: https://www.radix-ui.com/primitives/docs/guides/styling
• Base UI quick start: https://base-ui.com/react/overview/quick-start
• Base UI accessibility: https://base-ui.com/react/overview/accessibility
• Base UI composition: https://base-ui.com/react/overview/composition
• Base UI styling: https://base-ui.com/react/overview/styling
• WAI-ARIA Authoring Practices Guide: https://www.w3.org/WAI/ARIA/apg/
• WAI-ARIA 1.2 specification: https://www.w3.org/TR/wai-aria-1.2/
• WCAG 2.2: https://www.w3.org/TR/WCAG22/
• MDN ARIA documentation: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA
• Floating UI React documentation: https://floating-ui.com/docs/react
• Radix Primitives GitHub: https://github.com/radix-ui/primitives
• Base UI GitHub: https://github.com/mui/base-ui