1# Component Composition
2 
3## Contents
4 
5- Items always inside their Group component
6- Callouts use Alert
7- Empty states use Empty component
8- Toast notifications use sonner
9- Choosing between overlay components
10- Dialog, Sheet, and Drawer always need a Title
11- Card structure
12- Button has no isPending or isLoading prop
13- TabsTrigger must be inside TabsList
14- Avatar always needs AvatarFallback
15- Use Separator instead of raw hr or border divs
16- Use Skeleton for loading placeholders
17- Use Badge instead of custom styled spans
18 
19---
20 
21## Items always inside their Group component
22 
23Never render items directly inside the content container.
24 
25**Incorrect:**
26 
27```tsx
28<SelectContent>
29  <SelectItem value="apple">Apple</SelectItem>
30  <SelectItem value="banana">Banana</SelectItem>
31</SelectContent>
32```
33 
34**Correct:**
35 
36```tsx
37<SelectContent>
38  <SelectGroup>
39    <SelectItem value="apple">Apple</SelectItem>
40    <SelectItem value="banana">Banana</SelectItem>
41  </SelectGroup>
42</SelectContent>
43```
44 
45This applies to all group-based components:
46 
47| Item | Group |
48|------|-------|
49| `SelectItem`, `SelectLabel` | `SelectGroup` |
50| `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` | `DropdownMenuGroup` |
51| `MenubarItem` | `MenubarGroup` |
52| `ContextMenuItem` | `ContextMenuGroup` |
53| `CommandItem` | `CommandGroup` |
54 
55---
56 
57## Callouts use Alert
58 
59```tsx
60<Alert>
61  <AlertTitle>Warning</AlertTitle>
62  <AlertDescription>Something needs attention.</AlertDescription>
63</Alert>
64```
65 
66---
67 
68## Empty states use Empty component
69 
70```tsx
71<Empty>
72  <EmptyHeader>
73    <EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>
74    <EmptyTitle>No projects yet</EmptyTitle>
75    <EmptyDescription>Get started by creating a new project.</EmptyDescription>
76  </EmptyHeader>
77  <EmptyContent>
78    <Button>Create Project</Button>
79  </EmptyContent>
80</Empty>
81```
82 
83---
84 
85## Toast notifications use sonner
86 
87```tsx
88import { toast } from "sonner"
89 
90toast.success("Changes saved.")
91toast.error("Something went wrong.")
92toast("File deleted.", {
93  action: { label: "Undo", onClick: () => undoDelete() },
94})
95```
96 
97---
98 
99## Choosing between overlay components
100 
101| Use case | Component |
102|----------|-----------|
103| Focused task that requires input | `Dialog` |
104| Destructive action confirmation | `AlertDialog` |
105| Side panel with details or filters | `Sheet` |
106| Mobile-first bottom panel | `Drawer` |
107| Quick info on hover | `HoverCard` |
108| Small contextual content on click | `Popover` |
109 
110---
111 
112## Dialog, Sheet, and Drawer always need a Title
113 
114`DialogTitle`, `SheetTitle`, `DrawerTitle` are required for accessibility. Use `className="sr-only"` if visually hidden.
115 
116```tsx
117<DialogContent>
118  <DialogHeader>
119    <DialogTitle>Edit Profile</DialogTitle>
120    <DialogDescription>Update your profile.</DialogDescription>
121  </DialogHeader>
122  ...
123</DialogContent>
124```
125 
126---
127 
128## Card structure
129 
130Use full composition — don't dump everything into `CardContent`:
131 
132```tsx
133<Card>
134  <CardHeader>
135    <CardTitle>Team Members</CardTitle>
136    <CardDescription>Manage your team.</CardDescription>
137  </CardHeader>
138  <CardContent>...</CardContent>
139  <CardFooter>
140    <Button>Invite</Button>
141  </CardFooter>
142</Card>
143```
144 
145---
146 
147## Button has no isPending or isLoading prop
148 
149Compose with `Spinner` + `data-icon` + `disabled`:
150 
151```tsx
152<Button disabled>
153  <Spinner data-icon="inline-start" />
154  Saving...
155</Button>
156```
157 
158---
159 
160## TabsTrigger must be inside TabsList
161 
162Never render `TabsTrigger` directly inside `Tabs` — always wrap in `TabsList`:
163 
164```tsx
165<Tabs defaultValue="account">
166  <TabsList>
167    <TabsTrigger value="account">Account</TabsTrigger>
168    <TabsTrigger value="password">Password</TabsTrigger>
169  </TabsList>
170  <TabsContent value="account">...</TabsContent>
171</Tabs>
172```
173 
174---
175 
176## Avatar always needs AvatarFallback
177 
178Always include `AvatarFallback` for when the image fails to load:
179 
180```tsx
181<Avatar>
182  <AvatarImage src="/avatar.png" alt="User" />
183  <AvatarFallback>JD</AvatarFallback>
184</Avatar>
185```
186 
187---
188 
189## Use existing components instead of custom markup
190 
191| Instead of | Use |
192|---|---|
193| `<hr>` or `<div className="border-t">` | `<Separator />` |
194| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |
195| `<span className="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` |
196