Radix Primitives
Knowledge base from the Radix Primitives (radix-ui.com/primitives) documentation — unstyled, accessible React component primitives. Use when building with Radix Primitives directly (not shadcn/ui), looking up a primitive's anatomy/props/data-attributes, choosing between similar primitives (Dialog vs AlertDialog vs Popover, DropdownMenu vs ContextMenu), or implementing composition/styling/animation patterns like asChild, data-state styling, or collision-aware positioning.
Radix Primitives
Package: radix-ui (+ per-primitive @radix-ui/react-*) | Components: 30 | Utilities: 5 | Guides: 4 | Generated: 2026-08-25
How to Use This Skill
- Without arguments — load Core Patterns below for the composition/styling conventions shared across every primitive
- With a component name — ask about
Dialog,Select,ScrollTrigger-style topics; I find and read the matching chapter - With a chapter — ask for
ch016; I load that specific chapter - Browse — ask "what chapters do you have?" to see the full index
When you ask about a topic not covered in Core Patterns below, I will read the relevant chapter file before answering.
Core Patterns & Conventions
Anatomy first. Every primitive is Root + named sub-parts (Trigger, Content, Item...) — always start from a primitive's Anatomy section (in its chapter) before reaching for individual props.
asChild is the universal escape hatch. Nearly every part accepts asChild to clone its child instead of rendering a default element. Use it to change the rendered tag or compose Radix behavior onto your own components — but the child must spread props and forward its ref, and you inherit responsibility for accessibility once you swap the element.
Style off data-state, never off tracked JS state. Stateful parts expose data-state (and sibling data-* attributes like data-disabled, data-orientation, data-side, data-align) — target these in CSS/CSS-in-JS directly instead of mirroring state into your own class toggling.
Unstyled by design. Nothing renders visually except structure and behavior — plan for both functional styles (positioning, sizing) and presentational styles from the start; there is no default CSS to fall back on.
Positioned overlays share one API. Popover, DropdownMenu, ContextMenu, Select (popper mode), HoverCard, Tooltip, and NavigationMenu all expose the same side/align/offset/collision-handling props and the same family of CSS variables (--radix-*-content-transform-origin, -available-width/height) — learn it once on any of them.
CSS animation needs no extra wiring; JS animation needs forceMount. CSS keyframes keyed off data-state work out of the box (Radix suspends unmount until the animation finishes). A JS animation library (react-spring, Motion, GSAP) needs forceMount on the relevant part so it — not Radix — controls mount/unmount timing.
Roving tabindex is built in. Menu items, radio items, tabs, and toolbar items share one Tab stop with internal arrow-key movement — don't hand-roll this; configure loop/orientation/dir instead.
Form-stateful primitives (Checkbox, RadioGroup, Switch, Slider) render a hidden native input automatically for plain <form> compatibility. Only reach for the unstable_* decoupled parts (Checkbox, Switch) if you need to relocate or exclude that input.
Accessibility is opinionated, not optional. WAI-ARIA roles, keyboard interaction, and focus management (e.g. AlertDialog auto-focusing Cancel) are handled internally — labelling (via Label, AccessibleIcon, or aria-label/aria-labelledby) is still your responsibility.
Chapter Index
Overview
| # | Title | Key Concepts |
|---|---|---|
| ch001 | Introduction | asChild, radix-ui package, philosophy |
| ch002 | Getting Started | Root/Trigger/Portal/Content anatomy |
| ch003 | Accessibility | WAI-ARIA, Label, focus management |
| ch004 | Releases & Versioning | per-primitive semver, radix-ui package |
Guides
| # | Title | Key Concepts |
|---|---|---|
| ch005 | Composition | asChild, prop spreading, ref forwarding |
| ch006 | Styling | className, data-state, extending a primitive |
| ch007 | Animation | CSS keyframes, forceMount, JS animation libs |
| ch008 | Server-Side Rendering | SSR, static rendering, id hydration |
Components
| # | Title | Key Concepts |
|---|---|---|
| ch009 | Accordion | type single/multiple, collapsible, content-size CSS vars |
| ch010 | Alert Dialog | Cancel/Action, focus trap, interrupt pattern |
| ch011 | Aspect Ratio | ratio prop |
| ch012 | Avatar | Image/Fallback, delayMs |
| ch013 | Checkbox | tri-state, indeterminate, unstable_ parts |
| ch014 | Collapsible | single-panel open/close |
| ch015 | Context Menu | right-click, submenus, roving tabindex |
| ch016 | Dialog | modal, Title/Description, custom API pattern |
| ch017 | Dropdown Menu | click-trigger menu, same anatomy as ContextMenu |
| ch018 | Form | Constraint Validation API, Message match, server-side validation |
| ch019 | Hover Card | sighted-only preview, openDelay/closeDelay |
| ch020 | Label | native label association |
| ch021 | Menubar | multi-menu bar, cross-menu arrow navigation |
| ch022 | Navigation Menu | Viewport, Sub, shared-panel animation |
| ch023 | One-Time Password Field | unstable, per-character inputs, autoSubmit |
| ch024 | Password Toggle Field | unstable, visibility toggle, focus behavior |
| ch025 | Popover | non-modal default, Anchor |
| ch026 | Progress | progressbar role, indeterminate value |
| ch027 | Radio Group | mutually exclusive, loop default true |
| ch028 | Scroll Area | native scroll, custom scrollbar overlay |
| ch029 | Select | item-aligned vs popper positioning, ScrollUp/DownButton |
| ch030 | Separator | decorative prop |
| ch031 | Slider | multi-thumb, onValueCommit, minStepsBetweenThumbs |
| ch032 | Switch | two-state, unstable_ parts |
| ch033 | Tabs | activationMode automatic/manual, forceMount |
| ch034 | Toast | auto-dismiss, swipe-to-dismiss, Provider/Viewport |
| ch035 | Toggle | single on/off button |
| ch036 | Toggle Group | single/multiple type, always-one-selected pattern |
| ch037 | Toolbar | mixed controls, shared roving tabindex |
| ch038 | Tooltip | keyboard-accessible hint, Provider delay |
Utilities
| # | Title | Key Concepts |
|---|---|---|
| ch039 | Portal | DOM-escape rendering, container prop |
| ch040 | Slot | asChild mechanism, Slottable |
| ch041 | Accessible Icon | label prop for icon-only controls |
| ch042 | Direction Provider | app-wide RTL/LTR |
| ch043 | Visually Hidden | hidden-but-announced content |
Topic Index
- Accessibility (general) → ch003, ch041, ch043
- Animation (CSS) → ch007, ch009, ch014
- Animation (JS libraries) → ch007
- asChild / composition → ch001, ch005, ch040
- Collision-aware positioning → ch015, ch017, ch019, ch025, ch029
- Constraint Validation API → ch018
- Data attributes / data-state styling → ch006
- Focus management → ch003, ch010, ch016
- Form-compatible controls → ch013, ch018, ch027, ch031, ch032
- Indeterminate state → ch013, ch026
- Menu family (items, checkbox items, radio items, submenus) → ch015, ch017, ch021
- Portal / DOM escape → ch039
- RTL / direction → ch003, ch042
- Roving tabindex → ch015, ch027, ch033, ch036, ch037
- Server-side rendering → ch008
- Unstable primitives → ch013, ch023, ch024, ch032
- Versioning / changelog → ch004
Supporting Files
- glossary.md — key terms with definitions
- patterns.md — composition/styling/animation techniques
- cheatsheet.md — decision tables and defaults
Scope & Limits
This skill covers the Radix Primitives documentation as of the fetch date in the source — the raw, unstyled primitives (behavior, accessibility, anatomy, props API) that ship in the radix-ui package.
This is not the shadcn/ui skill. This project also has a shadcn-ui-docs skill, which covers shadcn/ui — a separate, pre-styled component collection built on top of many of these same Radix primitives (Tailwind classes, copy-paste source, theming). Consult radix-primitives-docs for the underlying primitive's behavior/API contract (what props exist, what data attributes it exposes, how its accessibility works); consult shadcn-ui-docs for the styled, ready-to-use component layer. When working in a shadcn/ui codebase, both skills are often relevant together — shadcn's components pass most Radix props straight through.
The 45+ dated release entries in the source are not reproduced 1:1 — ch004 summarizes the versioning approach and cites only the notable milestones (Releases chapter explains why).