1# Forms & Inputs
2 
3## Contents
4 
5- Forms use FieldGroup + Field
6- InputGroup requires InputGroupInput/InputGroupTextarea
7- Buttons inside inputs use InputGroup + InputGroupAddon
8- Option sets (2–7 choices) use ToggleGroup
9- FieldSet + FieldLegend for grouping related fields
10- Field validation and disabled states
11 
12---
13 
14## Forms use FieldGroup + Field
15 
16Always use `FieldGroup` + `Field` — never raw `div` with `space-y-*`:
17 
18```tsx
19<FieldGroup>
20  <Field>
21    <FieldLabel htmlFor="email">Email</FieldLabel>
22    <Input id="email" type="email" />
23  </Field>
24  <Field>
25    <FieldLabel htmlFor="password">Password</FieldLabel>
26    <Input id="password" type="password" />
27  </Field>
28</FieldGroup>
29```
30 
31Use `Field orientation="horizontal"` for settings pages. Use `FieldLabel className="sr-only"` for visually hidden labels.
32 
33**Choosing form controls:**
34 
35- Simple text input → `Input`
36- Dropdown with predefined options → `Select`
37- Searchable dropdown → `Combobox`
38- Native HTML select (no JS) → `native-select`
39- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)
40- Single choice from few options → `RadioGroup`
41- Toggle between 2–5 options → `ToggleGroup` + `ToggleGroupItem`
42- OTP/verification code → `InputOTP`
43- Multi-line text → `Textarea`
44 
45---
46 
47## InputGroup requires InputGroupInput/InputGroupTextarea
48 
49Never use raw `Input` or `Textarea` inside an `InputGroup`.
50 
51**Incorrect:**
52 
53```tsx
54<InputGroup>
55  <Input placeholder="Search..." />
56</InputGroup>
57```
58 
59**Correct:**
60 
61```tsx
62import { InputGroup, InputGroupInput } from "@/components/ui/input-group"
63 
64<InputGroup>
65  <InputGroupInput placeholder="Search..." />
66</InputGroup>
67```
68 
69---
70 
71## Buttons inside inputs use InputGroup + InputGroupAddon
72 
73Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.
74 
75**Incorrect:**
76 
77```tsx
78<div className="relative">
79  <Input placeholder="Search..." className="pr-10" />
80  <Button className="absolute right-0 top-0" size="icon">
81    <SearchIcon />
82  </Button>
83</div>
84```
85 
86**Correct:**
87 
88```tsx
89import { InputGroup, InputGroupInput, InputGroupAddon } from "@/components/ui/input-group"
90 
91<InputGroup>
92  <InputGroupInput placeholder="Search..." />
93  <InputGroupAddon>
94    <Button size="icon">
95      <SearchIcon data-icon="inline-start" />
96    </Button>
97  </InputGroupAddon>
98</InputGroup>
99```
100 
101---
102 
103## Option sets (2–7 choices) use ToggleGroup
104 
105Don't manually loop `Button` components with active state.
106 
107**Incorrect:**
108 
109```tsx
110const [selected, setSelected] = useState("daily")
111 
112<div className="flex gap-2">
113  {["daily", "weekly", "monthly"].map((option) => (
114    <Button
115      key={option}
116      variant={selected === option ? "default" : "outline"}
117      onClick={() => setSelected(option)}
118    >
119      {option}
120    </Button>
121  ))}
122</div>
123```
124 
125**Correct:**
126 
127```tsx
128import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
129 
130<ToggleGroup spacing={2}>
131  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
132  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
133  <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
134</ToggleGroup>
135```
136 
137Combine with `Field` for labelled toggle groups:
138 
139```tsx
140<Field orientation="horizontal">
141  <FieldTitle id="theme-label">Theme</FieldTitle>
142  <ToggleGroup aria-labelledby="theme-label" spacing={2}>
143    <ToggleGroupItem value="light">Light</ToggleGroupItem>
144    <ToggleGroupItem value="dark">Dark</ToggleGroupItem>
145    <ToggleGroupItem value="system">System</ToggleGroupItem>
146  </ToggleGroup>
147</Field>
148```
149 
150> **Note:** `defaultValue` and `type`/`multiple` props differ between base and radix. See [base-vs-radix.md](./base-vs-radix.md#togglegroup).
151 
152---
153 
154## FieldSet + FieldLegend for grouping related fields
155 
156Use `FieldSet` + `FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:
157 
158```tsx
159<FieldSet>
160  <FieldLegend variant="label">Preferences</FieldLegend>
161  <FieldDescription>Select all that apply.</FieldDescription>
162  <FieldGroup className="gap-3">
163    <Field orientation="horizontal">
164      <Checkbox id="dark" />
165      <FieldLabel htmlFor="dark" className="font-normal">Dark mode</FieldLabel>
166    </Field>
167  </FieldGroup>
168</FieldSet>
169```
170 
171---
172 
173## Field validation and disabled states
174 
175Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control.
176 
177```tsx
178// Invalid.
179<Field data-invalid>
180  <FieldLabel htmlFor="email">Email</FieldLabel>
181  <Input id="email" aria-invalid />
182  <FieldDescription>Invalid email address.</FieldDescription>
183</Field>
184 
185// Disabled.
186<Field data-disabled>
187  <FieldLabel htmlFor="email">Email</FieldLabel>
188  <Input id="email" disabled />
189</Field>
190```
191 
192Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`, `NativeSelect`, `InputOTP`.
193