---

name: radix-ui description: | Radix UI unstyled accessible React components. Headless primitives.

USE WHEN: user mentions "Radix", "Radix UI", "headless components", "unstyled primitives", asks about "accessible components", "Radix primitives"

DO NOT USE FOR: shadcn/ui (use shadcn-ui skill), styled component libraries (Material-UI, Chakra), Vue/Svelte (use Headless UI) allowed-tools: Read, Grep, Glob, Write, Edit

Radix UI - Quick Reference

When to Use This Skill

• Accessible Dialog/Modal components
• Dropdown menu, Select, Popover
• Headless components to style with Tailwind

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: radix-ui for comprehensive documentation.

When NOT to Use This Skill

• shadcn/ui project - Use shadcn-ui skill for pre-styled components
• Need styled components - Use Material-UI, Chakra UI, Ant Design
• Vue/Svelte projects - Use Headless UI or framework-specific libraries
• Simple use cases - Native HTML elements might suffice

Essential Patterns

Dialog (Modal)

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

<Dialog.Root>
  <Dialog.Trigger asChild>
    <button>Open</button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="fixed inset-0 bg-black/50" />
    <Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6 rounded">
      <Dialog.Title>Title</Dialog.Title>
      <Dialog.Description>Description</Dialog.Description>
      <Dialog.Close asChild>
        <button>Close</button>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

Dropdown Menu

import * as DropdownMenu from '@radix-ui/react-dropdown-menu';

<DropdownMenu.Root>
  <DropdownMenu.Trigger asChild>
    <button>Menu</button>
  </DropdownMenu.Trigger>
  <DropdownMenu.Portal>
    <DropdownMenu.Content className="bg-white shadow-lg rounded p-2">
      <DropdownMenu.Item onSelect={() => handleEdit()}>
        Edit
      </DropdownMenu.Item>
      <DropdownMenu.Item onSelect={() => handleDelete()}>
        Delete
      </DropdownMenu.Item>
    </DropdownMenu.Content>
  </DropdownMenu.Portal>
</DropdownMenu.Root>

Select

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

<Select.Root value={value} onValueChange={setValue}>
  <Select.Trigger className="select-trigger">
    <Select.Value placeholder="Select..." />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content>
      <Select.Viewport>
        <Select.Item value="admin">
          <Select.ItemText>Admin</Select.ItemText>
        </Select.Item>
      </Select.Viewport>
    </Select.Content>
  </Select.Portal>
</Select.Root>

Controlled State

const [open, setOpen] = useState(false);
<Dialog.Root open={open} onOpenChange={setOpen}>

Common Props

Prop	Usage
asChild	Merge props to child
open/onOpenChange	Controlled state
side/align	Positioning
sideOffset	Distance offset

Anti-Patterns to Avoid

• Do not forget Portal for z-index
• Do not forget asChild to avoid wrapper divs
• Do not neglect accessibility (ARIA labels)

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
No Portal for overlays	Z-index issues	Always use Portal for dialogs/dropdowns
Missing asChild	Extra wrapper divs	Use asChild to merge props
No controlled state	Can't track open/close	Use open/onOpenChange
Missing aria labels	Not accessible	Add proper labels to all interactive elements
Inline styles only	Hard to maintain	Use Tailwind classes or CSS modules
Not handling keyboard nav	Poor UX	Radix handles it, don't override

Quick Troubleshooting

Issue	Cause	Solution
Overlay behind other elements	No Portal	Wrap in Portal component
Extra div wrapper	Not using asChild	Add asChild prop to Trigger/Content
Component not opening	No state management	Add open/onOpenChange props
Styling not applying	Wrong element	Check Radix docs for data-attributes
Keyboard nav broken	Preventing default	Don't preventDefault on Radix events
Type errors	Wrong component import	Check @radix-ui/react-[component] package

Further Reading

For complete API reference: Radix UI Docs