1# Base vs Radix
2 
3API differences between `base` and `radix`. Check the `base` field from `npx shadcn@latest info`.
4 
5## Contents
6 
7- Composition: asChild vs render
8- Button / trigger as non-button element
9- Select (items prop, placeholder, positioning, multiple, object values)
10- ToggleGroup (type vs multiple)
11- Slider (scalar vs array)
12- Accordion (type and defaultValue)
13 
14---
15 
16## Composition: asChild (radix) vs render (base)
17 
18Radix uses `asChild` to replace the default element. Base uses `render`. Don't wrap triggers in extra elements.
19 
20**Incorrect:**
21 
22```tsx
23<DialogTrigger>
24  <div>
25    <Button>Open</Button>
26  </div>
27</DialogTrigger>
28```
29 
30**Correct (radix):**
31 
32```tsx
33<DialogTrigger asChild>
34  <Button>Open</Button>
35</DialogTrigger>
36```
37 
38**Correct (base):**
39 
40```tsx
41<DialogTrigger render={<Button />}>Open</DialogTrigger>
42```
43 
44This applies to all trigger and close components: `DialogTrigger`, `SheetTrigger`, `AlertDialogTrigger`, `DropdownMenuTrigger`, `PopoverTrigger`, `TooltipTrigger`, `CollapsibleTrigger`, `DialogClose`, `SheetClose`, `NavigationMenuLink`, `BreadcrumbLink`, `SidebarMenuButton`, `Badge`, `Item`.
45 
46---
47 
48## Button / trigger as non-button element (base only)
49 
50When `render` changes an element to a non-button (`<a>`, `<span>`), add `nativeButton={false}`.
51 
52**Incorrect (base):** missing `nativeButton={false}`.
53 
54```tsx
55<Button render={<a href="/docs" />}>Read the docs</Button>
56```
57 
58**Correct (base):**
59 
60```tsx
61<Button render={<a href="/docs" />} nativeButton={false}>
62  Read the docs
63</Button>
64```
65 
66**Correct (radix):**
67 
68```tsx
69<Button asChild>
70  <a href="/docs">Read the docs</a>
71</Button>
72```
73 
74Same for triggers whose `render` is not a `Button`:
75 
76```tsx
77// base.
78<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
79  Pick date
80</PopoverTrigger>
81```
82 
83---
84 
85## Select
86 
87**items prop (base only).** Base requires an `items` prop on the root. Radix uses inline JSX only.
88 
89**Incorrect (base):**
90 
91```tsx
92<Select>
93  <SelectTrigger><SelectValue placeholder="Select a fruit" /></SelectTrigger>
94</Select>
95```
96 
97**Correct (base):**
98 
99```tsx
100const items = [
101  { label: "Select a fruit", value: null },
102  { label: "Apple", value: "apple" },
103  { label: "Banana", value: "banana" },
104]
105 
106<Select items={items}>
107  <SelectTrigger>
108    <SelectValue />
109  </SelectTrigger>
110  <SelectContent>
111    <SelectGroup>
112      {items.map((item) => (
113        <SelectItem key={item.value} value={item.value}>{item.label}</SelectItem>
114      ))}
115    </SelectGroup>
116  </SelectContent>
117</Select>
118```
119 
120**Correct (radix):**
121 
122```tsx
123<Select>
124  <SelectTrigger>
125    <SelectValue placeholder="Select a fruit" />
126  </SelectTrigger>
127  <SelectContent>
128    <SelectGroup>
129      <SelectItem value="apple">Apple</SelectItem>
130      <SelectItem value="banana">Banana</SelectItem>
131    </SelectGroup>
132  </SelectContent>
133</Select>
134```
135 
136**Placeholder.** Base uses a `{ value: null }` item in the items array. Radix uses `<SelectValue placeholder="...">`.
137 
138**Content positioning.** Base uses `alignItemWithTrigger`. Radix uses `position`.
139 
140```tsx
141// base.
142<SelectContent alignItemWithTrigger={false} side="bottom">
143 
144// radix.
145<SelectContent position="popper">
146```
147 
148---
149 
150## Select — multiple selection and object values (base only)
151 
152Base supports `multiple`, render-function children on `SelectValue`, and object values with `itemToStringValue`. Radix is single-select with string values only.
153 
154**Correct (base — multiple selection):**
155 
156```tsx
157<Select items={items} multiple defaultValue={[]}>
158  <SelectTrigger>
159    <SelectValue>
160      {(value: string[]) => value.length === 0 ? "Select fruits" : `${value.length} selected`}
161    </SelectValue>
162  </SelectTrigger>
163  ...
164</Select>
165```
166 
167**Correct (base — object values):**
168 
169```tsx
170<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
171  <SelectTrigger>
172    <SelectValue>{(value) => value.name}</SelectValue>
173  </SelectTrigger>
174  ...
175</Select>
176```
177 
178---
179 
180## ToggleGroup
181 
182Base uses a `multiple` boolean prop. Radix uses `type="single"` or `type="multiple"`.
183 
184**Incorrect (base):**
185 
186```tsx
187<ToggleGroup type="single" defaultValue="daily">
188  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
189</ToggleGroup>
190```
191 
192**Correct (base):**
193 
194```tsx
195// Single (no prop needed), defaultValue is always an array.
196<ToggleGroup defaultValue={["daily"]} spacing={2}>
197  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
198  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
199</ToggleGroup>
200 
201// Multi-selection.
202<ToggleGroup multiple>
203  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
204  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
205</ToggleGroup>
206```
207 
208**Correct (radix):**
209 
210```tsx
211// Single, defaultValue is a string.
212<ToggleGroup type="single" defaultValue="daily" spacing={2}>
213  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
214  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
215</ToggleGroup>
216 
217// Multi-selection.
218<ToggleGroup type="multiple">
219  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
220  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
221</ToggleGroup>
222```
223 
224**Controlled single value:**
225 
226```tsx
227// base — wrap/unwrap arrays.
228const [value, setValue] = React.useState("normal")
229<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>
230 
231// radix — plain string.
232const [value, setValue] = React.useState("normal")
233<ToggleGroup type="single" value={value} onValueChange={setValue}>
234```
235 
236---
237 
238## Slider
239 
240Base accepts a plain number for a single thumb. Radix always requires an array.
241 
242**Incorrect (base):**
243 
244```tsx
245<Slider defaultValue={[50]} max={100} step={1} />
246```
247 
248**Correct (base):**
249 
250```tsx
251<Slider defaultValue={50} max={100} step={1} />
252```
253 
254**Correct (radix):**
255 
256```tsx
257<Slider defaultValue={[50]} max={100} step={1} />
258```
259 
260Both use arrays for range sliders. Controlled `onValueChange` in base may need a cast:
261 
262```tsx
263// base.
264const [value, setValue] = React.useState([0.3, 0.7])
265<Slider value={value} onValueChange={(v) => setValue(v as number[])} />
266 
267// radix.
268const [value, setValue] = React.useState([0.3, 0.7])
269<Slider value={value} onValueChange={setValue} />
270```
271 
272---
273 
274## Accordion
275 
276Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. `defaultValue` is a string. Base uses no `type` prop, uses `multiple` boolean, and `defaultValue` is always an array.
277 
278**Incorrect (base):**
279 
280```tsx
281<Accordion type="single" collapsible defaultValue="item-1">
282  <AccordionItem value="item-1">...</AccordionItem>
283</Accordion>
284```
285 
286**Correct (base):**
287 
288```tsx
289<Accordion defaultValue={["item-1"]}>
290  <AccordionItem value="item-1">...</AccordionItem>
291</Accordion>
292 
293// Multi-select.
294<Accordion multiple defaultValue={["item-1", "item-2"]}>
295  <AccordionItem value="item-1">...</AccordionItem>
296  <AccordionItem value="item-2">...</AccordionItem>
297</Accordion>
298```
299 
300**Correct (radix):**
301 
302```tsx
303<Accordion type="single" collapsible defaultValue="item-1">
304  <AccordionItem value="item-1">...</AccordionItem>
305</Accordion>
306```
307