Radix UI Primitives

Quick Guide: Radix ships unstyled primitives that carry the behaviour and accessibility of a component and none of its appearance. Every primitive is a compound component — Root, Trigger, Portal, Content — sharing context; asChild merges a primitive's behaviour onto your own element; data-state attributes drive CSS animation. Current major is v1.4.x: React 19 and RSC compatible, forwardRef no longer required, and radix-ui is the unified package that replaces the individual @radix-ui/react-* ones.

Detailed Resources:

examples/core.md — Dialog, asChild, Slot and Slottable
examples/overlays.md — AlertDialog, controlled Dialog with async work
examples/menus.md — DropdownMenu, submenus, checkable and radio items
examples/forms.md — Select, CSP nonce, indeterminate Progress
examples/navigation.md — Accordion and Tabs
examples/animation.md — data-state keyframes and height animation
examples/preview.md — unstable_ primitives: OTP field, password toggle, Form
reference.md — anti-patterns with code, checklists, CSS variable table, v1.4.x changes

Which path applies

A stable primitive — the eight-year-old API surface, semver-stable. Follow examples/core.md, then the file for the primitive family you need.
A preview primitive — unstable_OneTimePasswordField, unstable_PasswordToggleField, unstable_Form. The prefix is the API contract: these change between minors, so follow examples/preview.md and expect to revisit on upgrade.
Animating enter and exit — the approach forks on complexity. CSS @keyframes keyed to data-state covers fades, slides and height; orchestrated sequences need forceMount. Both are in examples/animation.md.

<critical_requirements>

Before writing Radix UI code

Install the unified radix-ui package rather than individual @radix-ui/react-* ones. One version of the shared internals means no duplicate context providers and no stacking-order conflicts between primitives.

Give overlays their full anatomy — Root, Trigger, Portal, Overlay, Content, Close. Each part registers itself with the Root's context; a missing part removes the behaviour it carried rather than just its markup.

Wrap overlay content in Portal. Content rendered in place inherits every ancestor's overflow: hidden and stacking context, so a dialog inside a scrolling panel is clipped by it.

Give every Dialog and AlertDialog a Title. It is what a screen reader announces on open, and Radix logs a console error when it is missing (a warning for a missing Description).

Forward the ref and spread every prop on a component used with asChild. The ref is how Radix positions floating content and returns focus on close; the spread is how the ARIA attributes and event handlers reach the DOM element. React 19 passes ref as an ordinary prop; below that it needs a forwardRef wrapper.

</critical_requirements>

Auto-detection: radix-ui, @radix-ui, Dialog.Root, AlertDialog, DropdownMenu, Popover, Tooltip, Accordion, Tabs, Select.Viewport, asChild, Slot, Slottable, ItemIndicator, data-state, forceMount, onOpenAutoFocus, onInteractOutside, --radix-accordion-content-height, unstable_OneTimePasswordField, unstable_PasswordToggleField, unstable_Form

Applies to:

Overlay behaviour — focus trapping, dismissal, collision-aware positioning, stacking order
Compound component APIs whose parts coordinate through shared context
Keyboard interaction and ARIA wiring for menus, selects, tabs and accordions
Polymorphism — rendering a primitive's behaviour on a different element via asChild
Building your own components with asChild support, using Slot

Handled elsewhere:

Visual design — primitives render unstyled and take a className; what produces that class is not this skill's concern
Form state, schema validation and submission — a Radix Select or Checkbox reports its value and nothing more
Icon artwork — the examples use Unicode glyphs marked aria-hidden; supplying real icons is a separate choice
Animation orchestration in JavaScript — Radix exposes forceMount and data-state as the hooks a presence-detecting animation runtime attaches to

Radix separates the two halves of a component that are usually welded together. It owns the half that is hard and invisible — ARIA roles, focus order, dismissal semantics, collision detection — and leaves the half that is your product's identity entirely alone.

That split has a consequence worth internalising: a primitive is a set of parts, not a component with props. Dialog is not a thing you configure; it is Root, Trigger, Portal, Overlay, Content, Title, Description and Close, communicating through context you never see. You compose the parts you need, in the arrangement your design calls for, and the coordination comes free. Reaching for a prop where a part exists is the usual sign of fighting the model.

</philosophy>

<decision_framework>

Choosing a primitive

Blocking the page?
├─ Destructive confirmation → AlertDialog (no click-outside dismiss, by design)
├─ Form or content         → Dialog
└─ Page-level, not blocking → Dialog with modal={false}, or Popover

Floating beside a trigger?
├─ Opened by click, holds interactive content → Popover
├─ Opened by hover or focus, text only        → Tooltip
└─ A list of actions                          → DropdownMenu

Choosing from options?
├─ One value, in a form   → Select
├─ Several values         → Popover containing Checkbox items
└─ An action, not a value → DropdownMenu

Showing and hiding regions?
├─ One at a time, in place → Accordion (type="single" collapsible)
├─ Several at once         → Accordion (type="multiple")
└─ One panel replacing another → Tabs

</decision_framework>

Core patterns

Pattern 1: Compound component anatomy

Every overlay is the same six parts. Root holds the state, Portal escapes the layout, Title and Description carry the accessible name.

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className={overlayClass} />
    <Dialog.Content className={contentClass}>
      <Dialog.Title>Account settings</Dialog.Title>
      <Dialog.Description>Manage preferences and security.</Dialog.Description>
      <Dialog.Close aria-label="Close">×</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

Full code: examples/core.md

Pattern 2: Controlled and uncontrolled state

defaultOpen lets Radix own the state. open with onOpenChange takes it back — needed to close after an async save, to open from somewhere other than the trigger, or to mirror the URL. onOpenChange is the only channel for user intent, so a controlled primitive that omits it can never be dismissed.

const [open, setOpen] = useState(false);

<Dialog.Root open={open} onOpenChange={setOpen}>
  {/* … */}
</Dialog.Root>;

Full code: examples/overlays.md

Pattern 3: `asChild` for polymorphism

asChild tells a part to render its child instead of its own element, merging props and behaviour onto it. This is how a Tooltip.Trigger becomes an anchor, or a Dialog.Trigger becomes your own button, without a wrapper element.

<Tooltip.Trigger asChild>
  <a href="/docs">Documentation</a>
</Tooltip.Trigger>

A custom component in that position takes ref and spreads the rest, or the merge silently drops the handlers and ARIA attributes Radix passed down.

Full code: examples/core.md

Pattern 4: Building your own `asChild` components with `Slot`

Slot is the merging machinery asChild uses, exposed for your own components. Swap the rendered element for Slot when asChild is set. Slottable marks where the child's content belongs when the component also renders fixed decoration around it.

function Button({ asChild = false, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : "button";
  return <Comp {...props} />;
}

Full code: examples/core.md

Pattern 5: Portal and its container

Portal moves content to document.body, out of every ancestor's clipping and stacking context. Pass container to send it somewhere else — a shadow root, an iframe body, or a micro-frontend's own mount point.

<Popover.Portal container={containerRef.current}>
  <Popover.Content>
    <Popover.Arrow />
  </Popover.Content>
</Popover.Portal>

Full code: examples/core.md

Pattern 6: Animation through `data-state`

Radix sets data-state="open" and "closed" on the animatable parts and suspends unmount until the exit animation reports it has finished. It listens for animationend, so @keyframes delays the unmount and transition does not.

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

For sequences a JavaScript runtime drives, forceMount on Portal, Overlay and Content hands unmounting back to you.

Full code: examples/animation.md

Pattern 7: Focus management

Modal content traps focus and returns it to the trigger on close, with no configuration. Override where the initial focus lands with onOpenAutoFocus — a destructive confirmation should open on Cancel rather than on Delete.

<AlertDialog.Content
  onOpenAutoFocus={(event) => {
    event.preventDefault();
    cancelRef.current?.focus();
  }}
>

Full code: examples/overlays.md

Pattern 8: Accessible names for overlays

Title is the accessible name and is required. Where the design has no visible heading, keep the element and hide it visually — removing it removes the announcement, not just the text.

<VisuallyHidden asChild>
  <Dialog.Title>Filter results</Dialog.Title>
</VisuallyHidden>

Set aria-describedby={undefined} on Content when there is deliberately no Description, which silences the warning without inventing text.

Full code: examples/core.md

</patterns>

<red_flags>

Red flags

Breaks at runtime:

A custom asChild child that does not take a ref — Radix cannot measure or focus it, so floating content mispositions and focus never returns; take ref as a prop (React 19) or wrap in forwardRef
A custom asChild child that does not spread its remaining props — the merged event handlers and ARIA attributes are dropped, leaving a trigger that looks right and does nothing
Overlay content outside Portal — clipped by any ancestor with overflow: hidden, and layered against the wrong stacking context
A Dialog without Title — no accessible name, and a console error on every open
transition used for an exit animation — unmount is not delayed, so the element disappears before anything animates; use @keyframes
Mounting content with a JavaScript animation runtime but no forceMount — Radix unmounts it the moment state flips, cutting the exit animation off at frame one

Surprising behaviour:

data-state flips to "closed" before the exit animation starts, not after it ends
--radix-accordion-content-height and its siblings are set only while an animation is running, and read as empty outside one
AlertDialog has no click-outside or Escape dismissal — Cancel or Action is the only way out, which is the point of choosing it
Slot merges handlers rather than replacing them, and the child's own handler runs first
Setting an explicit z-index on portalled content fights the ordering Radix maintains between layered primitives; isolate the container instead
A Progress with value={undefined} is indeterminate rather than zero
Select and ScrollArea take a nonce prop, needed wherever a Content Security Policy blocks unnonced inline styles

</red_flags>

web-ui-radix-ui

Radix UI Primitives

Which path applies

Before writing Radix UI code

Choosing a primitive

Core patterns

Pattern 1: Compound component anatomy

Pattern 2: Controlled and uncontrolled state

Pattern 3: asChild for polymorphism

Pattern 4: Building your own asChild components with Slot

Pattern 5: Portal and its container

Pattern 6: Animation through data-state

Pattern 7: Focus management

Pattern 8: Accessible names for overlays

Red flags

Pattern 3: `asChild` for polymorphism

Pattern 4: Building your own `asChild` components with `Slot`

Pattern 6: Animation through `data-state`