Radix Primitives

Radix Primitives

Unstyled, accessible React components for building high-quality design systems.

Overview

• Building custom styled components with full accessibility
• Understanding how shadcn/ui works under the hood
• Need polymorphic composition without wrapper divs
• Implementing complex UI patterns (modals, menus, tooltips)

Primitives Catalog

Overlay Components

Popover Components

Menu Components

Form Components

Disclosure Components

Core Pattern: asChild

The asChild prop enables polymorphic rendering without wrapper divs:

// Without asChild - creates nested elements
<Button>
  <Link href="/about">About</Link>
</Button>

// With asChild - merges into single element
<Button asChild>
  <Link href="/about">About</Link>
</Button>

How it works:

• Uses Radix's internal Slot component
• Merges props from parent to child
• Forwards refs correctly
• Combines event handlers (both fire)
• Merges classNames

Built-in Accessibility

Every primitive includes:

• Keyboard navigation: Arrow keys, Escape, Enter, Tab
• Focus management: Trap, return, visible focus rings
• ARIA attributes: Roles, states, properties
• Screen reader: Proper announcements

Styling with Data Attributes

Radix exposes state via data attributes:

/* Style based on state */
[data-state="open"] { /* open styles */ }
[data-state="closed"] { /* closed styles */ }
[data-disabled] { /* disabled styles */ }
[data-highlighted] { /* keyboard focus */ }

// Tailwind arbitrary variants
<Dialog.Content className="data-[state=open]:animate-in data-[state=closed]:animate-out">

Quick Reference

import { Dialog, DropdownMenu, Tooltip } from 'radix-ui'

// Basic Dialog
<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>Title</Dialog.Title>
      <Dialog.Description>Description</Dialog.Description>
      <Dialog.Close>Close</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

Key Decisions

Related Skills

• shadcn-patterns - Pre-styled Radix components
• focus-management - Accessibility patterns
• design-system-starter - Design system foundation

References

• asChild Composition - Polymorphic rendering
• Dialog Patterns - Dialog and AlertDialog
• Dropdown Patterns - Menus and Select
• Popover Patterns - Popover and Tooltip
• Focus Management - Keyboard and focus

Radix Accessibility Audit Checklist

Verify WCAG compliance for Radix-based components.

Keyboard Navigation

• [ ] All interactive elements reachable via Tab
• [ ] Tab order follows visual layout
• [ ] Focus visible on all interactive elements
• [ ] Escape closes overlays (dialogs, menus, popovers)
• [ ] Enter/Space activates buttons and triggers
• [ ] Arrow keys navigate menus, tabs, radio groups
• [ ] Home/End jump to first/last items in lists

Focus Management

• [ ] Focus trapped within dialogs when open
• [ ] Focus returns to trigger on close
• [ ] Initial focus on logical element (first input or primary action)
• [ ] No focus loss when elements are removed
• [ ] Focus visible indicator meets 3:1 contrast

ARIA Attributes (Auto-provided by Radix)

• [ ] role appropriate for component type
• [ ] aria-expanded on triggers for expandable content
• [ ] aria-controls links trigger to content
• [ ] aria-haspopup on menu triggers
• [ ] aria-selected on selected tabs/items
• [ ] aria-checked on checkboxes/radios
• [ ] aria-disabled on disabled elements

Screen Reader Announcements

• [ ] Dialog title announced on open
• [ ] Dialog description announced on open
• [ ] Menu items announced with role
• [ ] State changes announced (expanded/collapsed)
• [ ] Error messages associated with inputs

Dialogs (Dialog, AlertDialog)

• [ ] Has accessible name via Dialog.Title
• [ ] Has description via Dialog.Description
• [ ] AlertDialog requires explicit action (no click-outside close)
• [ ] Focus trapped within dialog
• [ ] Escape closes dialog (or prevented with reason)

Menus (DropdownMenu, ContextMenu)

• [ ] Trigger has aria-haspopup="menu"
• [ ] Items navigable via arrow keys
• [ ] Type-ahead focuses matching items
• [ ] Submenus accessible via arrow keys
• [ ] Disabled items skipped in navigation

Tooltips

• [ ] Wrapped in Tooltip.Provider for delay sharing
• [ ] Appears on hover AND focus
• [ ] Dismissible via Escape
• [ ] Does not block interaction with trigger
• [ ] Content is text-only (use Popover for interactive)

Forms (Select, Checkbox, RadioGroup, Switch)

• [ ] Associated with label
• [ ] Required state indicated
• [ ] Error messages programmatically associated
• [ ] Disabled state communicated
• [ ] Custom controls have appropriate ARIA roles

Testing Tools

# Install axe-core for automated testing
npm install -D @axe-core/react

# Or use browser extensions:
# - axe DevTools
# - WAVE
# - Accessibility Insights

Manual Testing

1. Keyboard-only: Unplug mouse, navigate entire flow 2. Screen reader: Test with VoiceOver (Mac), NVDA (Windows), or Orca (Linux) 3. Zoom: Test at 200% and 400% zoom levels 4. High contrast: Test with OS high contrast mode 5. Reduced motion: Test with prefers-reduced-motion: reduce

asChild Composition Pattern

Polymorphic rendering without wrapper divs.

What is asChild?

The asChild prop renders children as the component itself, merging props and refs. This avoids extra DOM elements while preserving functionality.

Basic Usage

import { Button } from '@/components/ui/button'
import Link from 'next/link'

// Without asChild - nested elements
<Button>
  <Link href="/about">About</Link>
</Button>
// Renders: <button><a href="/about">About</a></button>

// With asChild - single element
<Button asChild>
  <Link href="/about">About</Link>
</Button>
// Renders: <a href="/about" class="button-styles">About</a>

How It Works

Under the hood, asChild uses Radix's Slot component:

1. Props merging: Parent props spread to child 2. Ref forwarding: Refs correctly forwarded 3. Event combining: Both onClick handlers fire 4. Class merging: ClassNames combined

// Internal implementation concept
function Slot({ children, ...props }) {
  return React.cloneElement(children, {
    ...props,
    ...children.props,
    ref: mergeRefs(props.ref, children.ref),
    className: cn(props.className, children.props.className),
    onClick: chain(props.onClick, children.props.onClick),
  })
}

Nested Composition

Combine multiple Radix triggers:

import { Dialog, Tooltip } from 'radix-ui'

const MyButton = React.forwardRef((props, ref) => (
  <button {...props} ref={ref} />
))

export function DialogWithTooltip() {
  return (
    <Dialog.Root>
      <Tooltip.Root>
        <Tooltip.Trigger asChild>
          <Dialog.Trigger asChild>
            <MyButton>Open dialog</MyButton>
          </Dialog.Trigger>
        </Tooltip.Trigger>
        <Tooltip.Portal>
          <Tooltip.Content>Click to open dialog</Tooltip.Content>
        </Tooltip.Portal>
      </Tooltip.Root>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>Dialog content</Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

Common Patterns

Link as Button

<Button asChild variant="outline">
  <Link href="/settings">Settings</Link>
</Button>

Icon Button

<Button asChild size="icon">
  <a href="https://github.com" target="_blank">
    <GitHubIcon />
  </a>
</Button>

Menu Item as Link

<DropdownMenu.Item asChild>
  <Link href="/profile">Profile</Link>
</DropdownMenu.Item>

When to Use

Requirements for Child Components

The child component MUST:

1. Forward refs with React.forwardRef 2. Spread props to underlying element 3. Be a single element (not fragment)

// ✅ Correct - forwards ref and spreads props
const MyButton = React.forwardRef<HTMLButtonElement, Props>(
  (props, ref) => <button ref={ref} {...props} />
)

// ❌ Incorrect - no ref forwarding
const MyButton = (props) => <button {...props} />

Dialog and Modal Patterns

Accessible modal dialogs with Radix primitives.

Dialog vs AlertDialog

Basic Dialog

import { Dialog } from 'radix-ui'

export function BasicDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <Button>Edit Profile</Button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay className="fixed inset-0 bg-black/50" />
        <Dialog.Content className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 bg-white rounded-lg p-6">
          <Dialog.Title>Edit Profile</Dialog.Title>
          <Dialog.Description>
            Make changes to your profile here.
          </Dialog.Description>

          {/* Form content */}

          <Dialog.Close asChild>
            <Button>Save changes</Button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

Controlled Dialog

export function ControlledDialog() {
  const [open, setOpen] = useState(false)

  const handleSubmit = async () => {
    await saveData()
    setOpen(false) // Close after save
  }

  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger asChild>
        <Button>Open</Button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <form onSubmit={handleSubmit}>
            {/* Form fields */}
            <Button type="submit">Save</Button>
          </form>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  )
}

AlertDialog (Destructive Actions)

import { AlertDialog } from 'radix-ui'

export function DeleteConfirmation({ onDelete }) {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger asChild>
        <Button variant="destructive">Delete</Button>
      </AlertDialog.Trigger>
      <AlertDialog.Portal>
        <AlertDialog.Overlay className="fixed inset-0 bg-black/50" />
        <AlertDialog.Content className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 bg-white rounded-lg p-6">
          <AlertDialog.Title>Are you sure?</AlertDialog.Title>
          <AlertDialog.Description>
            This action cannot be undone. This will permanently delete your account.
          </AlertDialog.Description>
          <div className="flex gap-4 justify-end">
            <AlertDialog.Cancel asChild>
              <Button variant="outline">Cancel</Button>
            </AlertDialog.Cancel>
            <AlertDialog.Action asChild>
              <Button variant="destructive" onClick={onDelete}>
                Delete
              </Button>
            </AlertDialog.Action>
          </div>
        </AlertDialog.Content>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  )
}

Abstracting Dialog Components

Create reusable wrappers:

// components/ui/dialog.tsx
import * as DialogPrimitive from '@radix-ui/react-dialog'
import { X } from 'lucide-react'

export const Dialog = DialogPrimitive.Root
export const DialogTrigger = DialogPrimitive.Trigger
export const DialogClose = DialogPrimitive.Close

export const DialogContent = React.forwardRef<
  React.ElementRef<typeof DialogPrimitive.Content>,
  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
>(({ children, className, ...props }, ref) => (
  <DialogPrimitive.Portal>
    <DialogPrimitive.Overlay
      className="fixed inset-0 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out"
    />
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
        'fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2',
        'bg-background rounded-lg shadow-lg p-6 w-full max-w-lg',
        'data-[state=open]:animate-in data-[state=closed]:animate-out',
        className
      )}
      {...props}
    >
      {children}
      <DialogPrimitive.Close className="absolute right-4 top-4">
        <X className="h-4 w-4" />
        <span className="sr-only">Close</span>
      </DialogPrimitive.Close>
    </DialogPrimitive.Content>
  </DialogPrimitive.Portal>
))

export const DialogHeader = ({ children }) => (
  <div className="space-y-1.5 mb-4">{children}</div>
)

export const DialogTitle = DialogPrimitive.Title
export const DialogDescription = DialogPrimitive.Description

Animation with data-state

/* Overlay animation */
[data-state="open"] .overlay {
  animation: fadeIn 150ms ease-out;
}
[data-state="closed"] .overlay {
  animation: fadeOut 150ms ease-in;
}

/* Content animation */
[data-state="open"] .content {
  animation: scaleIn 150ms ease-out;
}
[data-state="closed"] .content {
  animation: scaleOut 150ms ease-in;
}

@keyframes fadeIn { from { opacity: 0; } }
@keyframes fadeOut { to { opacity: 0; } }
@keyframes scaleIn { from { transform: scale(0.95); opacity: 0; } }
@keyframes scaleOut { to { transform: scale(0.95); opacity: 0; } }

Accessibility Built-in

• Focus trapped within dialog
• Focus returns to trigger on close
• Escape closes dialog
• Click outside closes (Dialog only)
• Proper ARIA attributes
• Screen reader announcements

Dropdown Menu Patterns

Accessible dropdown menus with Radix primitives.

Basic Dropdown Menu

import { DropdownMenu } from 'radix-ui'
import { ChevronDown } from 'lucide-react'

export function UserMenu() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <Button variant="outline">
          Options <ChevronDown className="ml-2 h-4 w-4" />
        </Button>
      </DropdownMenu.Trigger>

      <DropdownMenu.Portal>
        <DropdownMenu.Content
          className="min-w-[200px] bg-white rounded-md shadow-lg p-1"
          sideOffset={5}
        >
          <DropdownMenu.Item className="px-2 py-1.5 rounded hover:bg-gray-100 cursor-pointer">
            Profile
          </DropdownMenu.Item>
          <DropdownMenu.Item className="px-2 py-1.5 rounded hover:bg-gray-100 cursor-pointer">
            Settings
          </DropdownMenu.Item>
          <DropdownMenu.Separator className="h-px bg-gray-200 my-1" />
          <DropdownMenu.Item className="px-2 py-1.5 rounded hover:bg-red-100 text-red-600 cursor-pointer">
            Sign out
          </DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  )
}

With Checkbox Items

export function ViewOptionsMenu() {
  const [showGrid, setShowGrid] = useState(true)
  const [showDetails, setShowDetails] = useState(false)

  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <Button>View</Button>
      </DropdownMenu.Trigger>

      <DropdownMenu.Portal>
        <DropdownMenu.Content>
          <DropdownMenu.CheckboxItem
            checked={showGrid}
            onCheckedChange={setShowGrid}
          >
            <DropdownMenu.ItemIndicator>
              <Check className="h-4 w-4" />
            </DropdownMenu.ItemIndicator>
            Show Grid
          </DropdownMenu.CheckboxItem>

          <DropdownMenu.CheckboxItem
            checked={showDetails}
            onCheckedChange={setShowDetails}
          >
            <DropdownMenu.ItemIndicator>
              <Check className="h-4 w-4" />
            </DropdownMenu.ItemIndicator>
            Show Details
          </DropdownMenu.CheckboxItem>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  )
}

With Radio Group

export function SortMenu() {
  const [sort, setSort] = useState('date')

  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <Button>Sort by</Button>
      </DropdownMenu.Trigger>

      <DropdownMenu.Portal>
        <DropdownMenu.Content>
          <DropdownMenu.RadioGroup value={sort} onValueChange={setSort}>
            <DropdownMenu.RadioItem value="date">
              <DropdownMenu.ItemIndicator>
                <Circle className="h-2 w-2 fill-current" />
              </DropdownMenu.ItemIndicator>
              Date
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem value="name">
              <DropdownMenu.ItemIndicator>
                <Circle className="h-2 w-2 fill-current" />
              </DropdownMenu.ItemIndicator>
              Name
            </DropdownMenu.RadioItem>
            <DropdownMenu.RadioItem value="size">
              <DropdownMenu.ItemIndicator>
                <Circle className="h-2 w-2 fill-current" />
              </DropdownMenu.ItemIndicator>
              Size
            </DropdownMenu.RadioItem>
          </DropdownMenu.RadioGroup>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  )
}

With Submenus

export function FileMenu() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger asChild>
        <Button>File</Button>
      </DropdownMenu.Trigger>

      <DropdownMenu.Portal>
        <DropdownMenu.Content>
          <DropdownMenu.Item>New File</DropdownMenu.Item>
          <DropdownMenu.Item>Open</DropdownMenu.Item>

          <DropdownMenu.Sub>
            <DropdownMenu.SubTrigger>
              Export
              <ChevronRight className="ml-auto h-4 w-4" />
            </DropdownMenu.SubTrigger>
            <DropdownMenu.Portal>
              <DropdownMenu.SubContent>
                <DropdownMenu.Item>PDF</DropdownMenu.Item>
                <DropdownMenu.Item>PNG</DropdownMenu.Item>
                <DropdownMenu.Item>SVG</DropdownMenu.Item>
              </DropdownMenu.SubContent>
            </DropdownMenu.Portal>
          </DropdownMenu.Sub>

          <DropdownMenu.Separator />
          <DropdownMenu.Item>Quit</DropdownMenu.Item>
        </DropdownMenu.Content>
      </DropdownMenu.Portal>
    </DropdownMenu.Root>
  )
}

Custom Abstraction

// components/ui/dropdown-menu.tsx
export const DropdownMenu = DropdownMenuPrimitive.Root
export const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger

export const DropdownMenuContent = React.forwardRef(
  ({ className, sideOffset = 4, ...props }, ref) => (
    <DropdownMenuPrimitive.Portal>
      <DropdownMenuPrimitive.Content
        ref={ref}
        sideOffset={sideOffset}
        className={cn(
          'z-50 min-w-[8rem] rounded-md border bg-popover p-1 shadow-md',
          'data-[state=open]:animate-in data-[state=closed]:animate-out',
          className
        )}
        {...props}
      />
    </DropdownMenuPrimitive.Portal>
  )
)

export const DropdownMenuItem = React.forwardRef(
  ({ className, ...props }, ref) => (
    <DropdownMenuPrimitive.Item
      ref={ref}
      className={cn(
        'relative flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none',
        'focus:bg-accent focus:text-accent-foreground',
        'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
        className
      )}
      {...props}
    />
  )
)

Keyboard Navigation

Built-in keyboard support:

• Arrow keys: Navigate items
• Enter/Space: Select item
• Escape: Close menu
• Right arrow: Open submenu
• Left arrow: Close submenu
• Type ahead: Focus matching item

Focus Management

Keyboard navigation and focus handling with Radix.

Built-in Focus Features

All Radix primitives include:

Dialog Focus Trap

Focus is automatically trapped within dialogs:

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Content>
      {/* Focus trapped here */}
      <input autoFocus />  {/* Receives initial focus */}
      <button>Action 1</button>
      <button>Action 2</button>
      <Dialog.Close>Close</Dialog.Close>
      {/* Tab cycles through these elements */}
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

Custom Initial Focus

<Dialog.Content
  onOpenAutoFocus={(event) => {
    event.preventDefault()
    // Focus specific element
    document.getElementById('email-input')?.focus()
  }}
>
  <input id="name-input" />
  <input id="email-input" />  {/* Gets focus */}
</Dialog.Content>

Preventing Focus Return

<Dialog.Content
  onCloseAutoFocus={(event) => {
    event.preventDefault()
    // Focus something else instead of trigger
    document.getElementById('other-element')?.focus()
  }}
>
  {/* Content */}
</Dialog.Content>

Roving Tabindex (Menu Navigation)

Arrow keys navigate within menus:

<DropdownMenu.Content>
  {/* Tab: exits menu */}
  {/* Arrow Up/Down: navigates items */}
  <DropdownMenu.Item>Profile</DropdownMenu.Item>
  <DropdownMenu.Item>Settings</DropdownMenu.Item>
  <DropdownMenu.Item>Sign out</DropdownMenu.Item>
</DropdownMenu.Content>

RadioGroup Focus

<RadioGroup.Root>
  {/* Tab: enters group at selected item */}
  {/* Arrow keys: move between items */}
  <RadioGroup.Item value="a">Option A</RadioGroup.Item>
  <RadioGroup.Item value="b">Option B</RadioGroup.Item>
  <RadioGroup.Item value="c">Option C</RadioGroup.Item>
</RadioGroup.Root>

Tabs Focus

<Tabs.Root>
  <Tabs.List>
    {/* Arrow keys navigate tabs */}
    <Tabs.Trigger value="account">Account</Tabs.Trigger>
    <Tabs.Trigger value="password">Password</Tabs.Trigger>
  </Tabs.List>
  {/* Tab moves to content */}
  <Tabs.Content value="account">...</Tabs.Content>
  <Tabs.Content value="password">...</Tabs.Content>
</Tabs.Root>

Focus Visible Styling

Style focus indicators for keyboard users:

/* Only show focus ring for keyboard navigation */
[data-focus-visible] {
  outline: 2px solid var(--ring);
  outline-offset: 2px;
}

/* Hide for mouse users */
:focus:not([data-focus-visible]) {
  outline: none;
}

// Tailwind
<Button className="focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2">

Escape Key Handling

All overlays close on Escape:

<Dialog.Content
  onEscapeKeyDown={(event) => {
    // Prevent close if form has changes
    if (hasUnsavedChanges) {
      event.preventDefault()
      showConfirmDialog()
    }
  }}
>

Keyboard Shortcuts Reference

Focus Scope (Advanced)

For custom focus trapping:

import { FocusScope } from '@radix-ui/react-focus-scope'

<FocusScope
  trapped={true}
  onMountAutoFocus={(event) => {
    event.preventDefault()
    firstInput.current?.focus()
  }}
  onUnmountAutoFocus={(event) => {
    event.preventDefault()
    triggerRef.current?.focus()
  }}
>
  {/* Focusable content */}
</FocusScope>

Popover and Tooltip Patterns

Floating content with Radix primitives.

Tooltip vs Popover vs HoverCard

Basic Tooltip

import { Tooltip } from 'radix-ui'

export function IconWithTooltip() {
  return (
    <Tooltip.Provider delayDuration={300}>
      <Tooltip.Root>
        <Tooltip.Trigger asChild>
          <Button size="icon" variant="ghost">
            <Settings className="h-4 w-4" />
          </Button>
        </Tooltip.Trigger>
        <Tooltip.Portal>
          <Tooltip.Content
            className="bg-gray-900 text-white px-3 py-1.5 rounded text-sm"
            sideOffset={5}
          >
            Settings
            <Tooltip.Arrow className="fill-gray-900" />
          </Tooltip.Content>
        </Tooltip.Portal>
      </Tooltip.Root>
    </Tooltip.Provider>
  )
}

Tooltip Provider

Wrap your app for shared configuration:

// app/layout.tsx
import { Tooltip } from 'radix-ui'

export default function RootLayout({ children }) {
  return (
    <Tooltip.Provider
      delayDuration={400}      // Delay before showing
      skipDelayDuration={300}  // Skip delay when moving between tooltips
    >
      {children}
    </Tooltip.Provider>
  )
}

Basic Popover

import { Popover } from 'radix-ui'

export function FilterPopover() {
  return (
    <Popover.Root>
      <Popover.Trigger asChild>
        <Button variant="outline">
          <Filter className="mr-2 h-4 w-4" />
          Filters
        </Button>
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content
          className="w-80 bg-white rounded-lg shadow-lg p-4"
          sideOffset={5}
        >
          <div className="space-y-4">
            <h4 className="font-medium">Filter options</h4>

            <div className="space-y-2">
              <Label>Status</Label>
              <Select>
                <option>All</option>
                <option>Active</option>
                <option>Archived</option>
              </Select>
            </div>

            <div className="space-y-2">
              <Label>Date range</Label>
              <Input type="date" />
            </div>

            <Button className="w-full">Apply filters</Button>
          </div>

          <Popover.Arrow className="fill-white" />
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  )
}

Controlled Popover

export function ControlledPopover() {
  const [open, setOpen] = useState(false)

  const handleSubmit = () => {
    // Process form
    setOpen(false) // Close after submit
  }

  return (
    <Popover.Root open={open} onOpenChange={setOpen}>
      <Popover.Trigger asChild>
        <Button>Add item</Button>
      </Popover.Trigger>
      <Popover.Portal>
        <Popover.Content>
          <form onSubmit={handleSubmit}>
            <Input placeholder="Item name" />
            <Button type="submit">Add</Button>
          </form>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  )
}

HoverCard (Rich Previews)

import { HoverCard } from 'radix-ui'

export function UserHoverCard({ username }) {
  return (
    <HoverCard.Root>
      <HoverCard.Trigger asChild>
        <a href={`/user/${username}`} className="text-blue-500 hover:underline">
          @{username}
        </a>
      </HoverCard.Trigger>

      <HoverCard.Portal>
        <HoverCard.Content
          className="w-64 bg-white rounded-lg shadow-lg p-4"
          sideOffset={5}
        >
          <div className="flex gap-4">
            <Avatar src={`/avatars/${username}.jpg`} />
            <div>
              <h4 className="font-medium">{username}</h4>
              <p className="text-sm text-gray-500">Software Engineer</p>
              <p className="text-sm mt-2">Building cool things with React.</p>
            </div>
          </div>
          <HoverCard.Arrow className="fill-white" />
        </HoverCard.Content>
      </HoverCard.Portal>
    </HoverCard.Root>
  )
}

Positioning

Common positioning props:

<Content
  side="top"           // top | right | bottom | left
  sideOffset={5}       // Distance from trigger
  align="center"       // start | center | end
  alignOffset={0}      // Offset from alignment
  avoidCollisions={true}  // Flip if clipped
  collisionPadding={8}    // Viewport padding
/>

Styling States

/* Animation on open/close */
[data-state="open"] { animation: fadeIn 200ms ease-out; }
[data-state="closed"] { animation: fadeOut 150ms ease-in; }

/* Side-aware animations */
[data-side="top"] { animation-name: slideFromBottom; }
[data-side="bottom"] { animation-name: slideFromTop; }
[data-side="left"] { animation-name: slideFromRight; }
[data-side="right"] { animation-name: slideFromLeft; }