base-vs-radix — Claude Code rule: shadcn component APIs
base-vs-radix — an IDE rule that clarifies API differences between shadcn's base components and their Radix counterparts. Covers composition, Select options, value types, and prop naming across multiple components.
LicenseRef-Proprietary ★ 7,523 updated 2026-10-29
.claude/rules/base-vs-radix.mdWhat base-vs-radix does
When working with shadcn across different component implementations, base and Radix versions use different APIs. This rule documents the gaps: Radix uses asChild where base uses render; Select in base requires an items array and supports multiple values and objects, while Radix is single-select with strings only; ToggleGroup and Accordion treat defaultValue as an array in base but a string in Radix; Slider accepts a plain number in base but always an array in Radix.
When a trigger's render prop points to a non-button element, base requires nativeButton={false}. Select in base uses alignItemWithTrigger instead of position for layout. Understanding these patterns prevents runtime errors and keeps code coherent across mixed component usage.
What it helps with
- choose asChild or render based on component implementation
- configure Select items, placeholder, and positioning correctly in base
- manage ToggleGroup value as array or string depending on version
- pass Slider defaultValue as number or array without type errors
- add nativeButton={false} when rendering trigger or button as link or custom element
Example prompts for the agent
- Should I use asChild or render to wrap a Button inside DialogTrigger?
- Does Select in base need an items array, or can I use inline SelectItem children?
- Why does defaultValue in ToggleGroup work differently between base and Radix?
How to install base-vs-radix
Manually: put the files in place
.claude/rules/base-vs-radix.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/base-vs-radix.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/base-vs-radix.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/base-vs-radix.mdManually: put the files in place
.clinerules/base-vs-radix.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about base-vs-radix
How do I install base-vs-radix in Claude Code?
Place the file at .claude/rules/base-vs-radix.md in your project root. Claude Code loads rules from this directory automatically.
What does the base-vs-radix rule explain?
It documents all major API differences between shadcn's base components and Radix versions: composition syntax (asChild vs render), Select behavior (items prop, multiple values, object values), value shape in ToggleGroup and Accordion, nativeButton requirement, and positioning attributes.
What are the main differences between base and Radix components?
Base uses render instead of asChild, requires an items array in Select, supports multiple selection and object values, always uses arrays for defaultValue. Radix is simpler but limited to strings and single-select in Select.