/shadcn

Component Composition

Contents

• Items always inside their Group component
• Callouts use Alert
• Empty states use Empty component
• Toast notifications follow the project base
• Choosing between overlay components
• Dialog, Sheet, and Drawer always need a Title
• Card structure
• Button has no isPending or isLoading prop
• TabsTrigger must be inside TabsList
• Avatar always needs AvatarFallback
• Use Separator instead of raw hr or border divs
• Use Skeleton for loading placeholders
• Use Badge instead of custom styled spans

Items always inside their Group component

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:

Chat components nest in a fixed order (MessageScrollerProvider → MessageScroller → MessageScrollerViewport → MessageScrollerContent → MessageScrollerItem). See chat.md.

Callouts use Alert

<Alert>
  <AlertTitle>Warning</AlertTitle>
  <AlertDescription>Something needs attention.</AlertDescription>
</Alert>

Empty states use Empty component

<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>

Toast notifications follow the project base

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() },
})

Choosing between overlay components

Dialog, Sheet, and Drawer always need a Title

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>

Card structure

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>

Button has no isPending or isLoading prop

Compose with Spinner + data-icon + disabled:

<Button disabled>
  <Spinner data-icon="inline-start" />
  Saving...
</Button>

TabsTrigger must be inside TabsList

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>

Avatar always needs AvatarFallback

Always include AvatarFallback for when the image fails to load:

<Avatar>
  <AvatarImage src="/avatar.png" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

Use existing components instead of custom markup