Setting the file. One moment.
Subchapter 2.9
rules/composition.mdMarkdown5 KBView on GitHub
Never render items directly inside the content container.
Incorrect:
<SelectContent>
<SelectItem value="apple">Apple</SelectItem>
<SelectItem value="banana">Banana</SelectItem>
</SelectContent>Correct:
<SelectContent>
<SelectGroup>
<SelectItem value="apple">Apple</SelectItem>
<SelectItem value="banana">Banana</SelectItem>
</SelectGroup>
</SelectContent>This applies to all group-based components:
| Item | Group |
|---|---|
SelectItem, SelectLabel | SelectGroup |
DropdownMenuItem, DropdownMenuLabel, DropdownMenuSub | DropdownMenuGroup |
MenubarItem | MenubarGroup |
ContextMenuItem | ContextMenuGroup |
CommandItem | CommandGroup |
MessageScrollerItem | MessageScrollerContent |
Message (consecutive, same sender) | MessageGroup |
Bubble (stacked) | BubbleGroup |
Attachment (in a row) | AttachmentGroup |
Chat components nest in a fixed order (MessageScrollerProvider → MessageScroller → MessageScrollerViewport → MessageScrollerContent → MessageScrollerItem). See chat.md.
<Alert>
<AlertTitle>Warning</AlertTitle>
<AlertDescription>Something needs attention.</AlertDescription>
</Alert><Empty>
<EmptyHeader>
<EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>
<EmptyTitle>No projects yet</EmptyTitle>
<EmptyDescription>Get started by creating a new project.</EmptyDescription>
</EmptyHeader>
<EmptyContent>
<Button>Create Project</Button>
</EmptyContent>
</Empty>For Base UI projects, use the toast component:
import { toast } from "@/components/ui/toast"
toast.add({
title: "Changes saved.",
})For Radix and React Aria projects, use Sonner:
import { toast } from "sonner"
toast.success("Changes saved.")
toast.error("Something went wrong.")
toast("File deleted.", {
action: { label: "Undo", onClick: () => undoDelete() },
})| Use case | Component |
|---|---|
| Focused task that requires input | Dialog |
| Destructive action confirmation | AlertDialog |
| Side panel with details or filters | Sheet |
| Mobile-first bottom panel | Drawer |
| Quick info on hover | HoverCard |
| Small contextual content on click | Popover |
DialogTitle, SheetTitle, DrawerTitle are required for accessibility. Use className="sr-only" if visually hidden.
<DialogContent>
<DialogHeader>
<DialogTitle>Edit Profile</DialogTitle>
<DialogDescription>Update your profile.</DialogDescription>
</DialogHeader>
...
</DialogContent>Use full composition — don’t dump everything into CardContent:
<Card>
<CardHeader>
<CardTitle>Team Members</CardTitle>
<CardDescription>Manage your team.</CardDescription>
</CardHeader>
<CardContent>...</CardContent>
<CardFooter>
<Button>Invite</Button>
</CardFooter>
</Card>Compose with Spinner + data-icon + disabled:
<Button disabled>
<Spinner data-icon="inline-start" />
Saving...
</Button>Never render TabsTrigger directly inside Tabs — always wrap in TabsList:
<Tabs defaultValue="account">
<TabsList>
<TabsTrigger value="account">Account</TabsTrigger>
<TabsTrigger value="password">Password</TabsTrigger>
</TabsList>
<TabsContent value="account">...</TabsContent>
</Tabs>Always include AvatarFallback for when the image fails to load:
<Avatar>
<AvatarImage src="/avatar.png" alt="User" />
<AvatarFallback>JD</AvatarFallback>
</Avatar>| Instead of | Use |
|---|---|
<hr> or <div className="border-t"> | <Separator /> |
<div className="animate-pulse"> with styled divs | <Skeleton className="h-4 w-3/4" /> |
<span className="rounded-full bg-green-100 ..."> | <Badge variant="secondary"> |