Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

base-ui-react

MUI Base UI unstyled React components with Floating UI. Use for accessible components, Radix UI migration, render props API, or encountering positioning, popup, v1.0 rc / pre-GA issues.

secondsky · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add secondsky/claude-skills --skill base-ui-react

About this skill


name: base-ui-react description: "MUI Base UI unstyled React components with Floating UI. Use for accessible components, Radix UI migration, render props API, or encountering positioning, popup, v1.0 rc / pre-GA issues." license: MIT metadata: version: "2.0.0" last_verified: "2026-08-03" production_tested: true token_savings: "~62%" errors_prevented: 10 templates_included: 7 references_included: 3 keywords: - base-ui - "@base-ui-components/react" - mui base ui - unstyled components - accessible components - render props - radix alternative - radix migration - floating-ui - positioner pattern - headless ui - accessible dialog - accessible select - accessible popover - accessible tooltip - accessible accordion - number field - cloudflare workers ui - beta components

Base UI React

Status: Release Candidate (v1.0.0-rc.0) ⚠️ | Last Verified: 2026-08-03


What Is Base UI?

MUI's unstyled, accessible React component library:

  • 27+ accessible components
  • Render props pattern
  • Full styling control
  • Floating UI integration
  • Alternative to Radix UI

Release Candidate status: v1.0.0-rc.0 (stable v1.0 GA expected soon — still pre-GA, API may change)


Quick Start

Install

bun add @base-ui-components/react

Basic Dialog

import * as Dialog from '@base-ui-components/react/dialog';

export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>Title</Dialog.Title>
          <Dialog.Description>Content</Dialog.Description>
          <Dialog.Close>Close</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Basic Select

import * as Select from '@base-ui-components/react/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder="Select" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Option value="1">Option 1</Select.Option>
        <Select.Option value="2">Option 2</Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Load references/setup-guide.md for complete examples.


Core Components

Available (27+):

  • Dialog
  • Select
  • Popover
  • Tooltip
  • Accordion
  • NumberField
  • Checkbox
  • Switch
  • Tabs
  • Slider
  • And more...

Critical Rules

Always Do ✅

  1. Use Portal for popups (Dialog, Select, Popover)
  2. Use Positioner for floating elements
  3. Add Backdrop for modal dialogs
  4. Style with Tailwind (or any CSS)
  5. Use render props (not asChild like Radix)
  6. Test accessibility (ARIA built-in)
  7. Handle Portal edge cases (SSR, hydration)
  8. Check beta docs for breaking changes
  9. Use TypeScript for better DX
  10. Test on target browsers

Never Do ❌

  1. Never use asChild (use render function instead)
  2. Never skip Portal for popups (positioning breaks)
  3. Never skip Positioner (Floating UI won't work)
  4. Never assume API stability (beta software)
  5. Never skip accessibility testing
  6. Never use with React <19 (requires React 19+)
  7. Never skip Backdrop for modals
  8. Never hardcode z-index (use Portal)
  9. Never skip SSR testing (hydration issues)
  10. Never assume Radix compatibility (different API)

With Tailwind

<Dialog.Popup className="rounded-lg bg-white p-6 shadow-xl dark:bg-gray-800">
  <Dialog.Title className="text-xl font-bold text-gray-900 dark:text-white">
    Dialog Title
  </Dialog.Title>
  <Dialog.Description className="mt-2 text-gray-600 dark:text-gray-300">
    Dialog content here
  </Dialog.Description>
  <Dialog.Close className="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
    Close
  </Dialog.Close>
</Dialog.Popup>

Common Use Cases

Use Case 1: Modal Dialog

<Dialog.Root>
  <Dialog.Trigger className="btn">Open Modal</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop className="fixed inset-0 bg-black/50" />
    <Dialog.Popup className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

Use Case 2: Dropdown Select

<Select.Root>
  <Select.Trigger className="flex items-center gap-2 rounded border px-4 py-2">
    <Select.Value placeholder="Select option" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner className="z-50">
      <Select.Popup className="rounded border bg-white shadow-lg">
        <Select.Option value="1" className="px-4 py-2 hover:bg-gray-100">
          Option 1
        </Select.Option>
        <Select.Option value="2" className="px-4 py-2 hover:bg-gray-100">
          Option 2
        </Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Use Case 3: Tooltip

import * as Tooltip from '@base-ui-components/react/tooltip';

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup className="rounded bg-gray-900 px-2 py-1 text-sm text-white">
        Tooltip text
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>

Beta Considerations

Stable for production:

  • Dialog
  • Popover
  • Tooltip
  • Select
  • Accordion

Use with caution:

  • NumberField (API may change)
  • Complex form components

Migration path:

  • v1.0 stable GA expected soon (currently v1.0.0-rc.0)
  • Breaking changes will be documented
  • Codemods likely provided

vs Radix UI

| Feature | Base UI | Radix UI | |-

Read the complete source ↗