shadcn/ui Components Documentation

This document lists all shadcn/ui components available in the CROP project. All components are located in components/ui/ and follow the Moby Design System patterns.

📦 Installation Status

Total Components Installed: 45

All components are fully integrated with:

• ✅ Tailwind CSS v4
• ✅ Moby Design System (data-surface theming)
• ✅ TypeScript strict mode
• ✅ Accessibility (ARIA, keyboard navigation)
• ✅ Dark mode support

📚 Complete Component List

Layout & Structure

Accordion

File: components/ui/accordion.tsx Description: Vertically stacked set of interactive headings that reveal content. Use cases: FAQs, product details, collapsible sections Example:

import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@/components/ui";

<Accordion type="single" collapsible>
  <AccordionItem value="item-1">
    <AccordionTrigger>Is it accessible?</AccordionTrigger>
    <AccordionContent>Yes. It adheres to WAI-ARIA design patterns.</AccordionContent>
  </AccordionItem>
</Accordion>

Aspect Ratio

File: components/ui/aspect-ratio.tsx Description: Maintains consistent aspect ratios for images/videos. Use cases: Responsive media, product images, thumbnails Example:

import { AspectRatio } from "@/components/ui/aspect-ratio";

<AspectRatio ratio={16 / 9}>
  <img src="photo.jpg" alt="Product" />
</AspectRatio>

Card

File: components/ui/card.tsx Description: Container for content with header, footer, and elevated styling. Use cases: Product cards, info panels, dashboards Components: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter Example:

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui";

<Card variant="elevated">
  <CardHeader>
    <CardTitle>Product Name</CardTitle>
  </CardHeader>
  <CardContent>Product details here...</CardContent>
</Card>

Collapsible

File: components/ui/collapsible.tsx Description: Interactive component to show/hide content. Use cases: Expandable sections, show more/less functionality Example:

import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@/components/ui/collapsible";

<Collapsible>
  <CollapsibleTrigger>Show details</CollapsibleTrigger>
  <CollapsibleContent>Hidden content here...</CollapsibleContent>
</Collapsible>

Resizable

File: components/ui/resizable.tsx Description: Resizable panel layouts with drag handles. Use cases: Split panes, adjustable sidebars, multi-panel layouts

Scroll Area

File: components/ui/scroll-area.tsx Description: Custom styled scrollable container. Use cases: Long lists, content overflow, custom scrollbars

Separator

File: components/ui/separator.tsx Description: Visual divider between content sections. Use cases: Section dividers, visual hierarchy Example:

import { Separator } from "@/components/ui";

<div>
  <p>Section 1</p>
  <Separator className="my-4" />
  <p>Section 2</p>
</div>

Sidebar

File: components/ui/sidebar.tsx Description: Responsive sidebar navigation component. Use cases: App navigation, drawer menus, side panels Components: Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarMenu

Tabs

File: components/ui/tabs.tsx Description: Tabbed interface for switching between views. Use cases: Product details, settings panels, content organization Components: Tabs, TabsList, TabsTrigger, TabsContent, ScrollableTabs Example:

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui";

<Tabs defaultValue="specs">
  <TabsList>
    <TabsTrigger value="specs">Specifications</TabsTrigger>
    <TabsTrigger value="docs">Documents</TabsTrigger>
  </TabsList>
  <TabsContent value="specs">Spec content...</TabsContent>
  <TabsContent value="docs">Docs content...</TabsContent>
</Tabs>

Navigation

Breadcrumb

File: components/ui/breadcrumb.tsx Description: Navigation trail showing current page location. Use cases: Page hierarchy, navigation history Components: Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator Example:

import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList } from "@/components/ui";

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbItem>
      <BreadcrumbLink href="/parts">Parts</BreadcrumbLink>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

Command

File: components/ui/command.tsx Description: Command palette with search and keyboard navigation. Use cases: Quick actions, search menus, keyboard shortcuts Components: Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem

Context Menu

File: components/ui/context-menu.tsx Description: Right-click context menu. Use cases: Action menus, contextual options

Dropdown Menu

File: components/ui/dropdown-menu.tsx Description: Menu triggered by a button click. Use cases: User menus, action lists, settings Components: DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup

Menubar

File: components/ui/menubar.tsx Description: Horizontal menu bar (like desktop apps). Use cases: Application menus, toolbar actions

Navigation Menu

File: components/ui/navigation-menu.tsx Description: Main site navigation with dropdowns. Use cases: Header navigation, mega menus

Pagination

File: components/ui/pagination.tsx Directory: components/ui/pagination/ Description: Page navigation controls. Use cases: Search results, product listings, tables Components: PaginationBar (custom implementation)

Overlays & Modals

Alert Dialog

File: components/ui/alert-dialog.tsx Description: Modal dialog for important confirmations. Use cases: Delete confirmations, warnings, critical actions Components: AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogAction, AlertDialogCancel

Dialog

File: components/ui/dialog.tsx Description: Modal dialog for content and forms. Use cases: Forms, detailed views, confirmations Components: Dialog, AdaptiveDialog (responsive), DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter Example:

import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui";

<Dialog>
  <DialogTrigger>Open Dialog</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
    </DialogHeader>
    <p>Dialog content here...</p>
  </DialogContent>
</Dialog>

Drawer

File: components/ui/drawer.tsx Description: Slide-out panel from screen edge (mobile-first). Use cases: Mobile menus, side panels, filters Components: Drawer, DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter

Hover Card

File: components/ui/hover-card.tsx Description: Popup card on hover (like Twitter user cards). Use cases: User previews, additional info, tooltips

Popover

File: components/ui/popover.tsx Description: Floating content container. Use cases: Dropdown content, date pickers, custom menus Components: Popover, PopoverTrigger, PopoverContent, PopoverAnchor

Sheet

File: components/ui/sheet.tsx Description: Slide-out panel (more flexible than Drawer). Use cases: Settings panels, filters, side content Components: Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter

Tooltip

File: components/ui/tooltip.tsx Description: Informational popup on hover. Use cases: Icon explanations, help text, additional context Components: Tooltip, TooltipProvider, TooltipTrigger, TooltipContent Example:

import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui";

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger>Hover me</TooltipTrigger>
    <TooltipContent>Helpful information</TooltipContent>
  </Tooltip>
</TooltipProvider>

Forms & Inputs

Button

File: components/ui/button.tsx Description: Interactive button with multiple variants. Use cases: Actions, links, form submissions Variants: default, primary, secondary, success, warning, destructive, outline, ghost, link Example:

import { Button } from "@/components/ui";

<Button variant="primary" size="lg">Click me</Button>
<Button variant="outline">Secondary action</Button>
<Button variant="ghost" size="sm">Subtle action</Button>

Checkbox

File: components/ui/checkbox.tsx Description: Checkbox input for binary choices. Use cases: Agree to terms, filters, multi-select Example:

import { Checkbox } from "@/components/ui";

<Checkbox id="terms" />
<label htmlFor="terms">Accept terms and conditions</label>

Form

File: components/ui/form.tsx Description: Form wrapper with validation (react-hook-form). Use cases: Complex forms, validation, error handling Note: Use useWatch() hook instead of watch() due to React Compiler optimization

Input

File: components/ui/input.tsx Description: Text input field. Use cases: Text entry, search, form fields Example:

import { Input } from "@/components/ui";

<Input type="email" placeholder="Enter email" />

Input OTP

File: components/ui/input-otp.tsx Description: One-time password input with separate digit fields. Use cases: 2FA, verification codes, PIN entry

Label

File: components/ui/label.tsx Description: Form label with accessibility features. Use cases: Input labels, form field descriptions

Radio Group

File: components/ui/radio-group.tsx Description: Group of radio button inputs. Use cases: Single choice selection, options Example:

import { RadioGroup, RadioGroupItem } from "@/components/ui";

<RadioGroup defaultValue="option1">
  <div>
    <RadioGroupItem value="option1" id="opt1" />
    <label htmlFor="opt1">Option 1</label>
  </div>
  <div>
    <RadioGroupItem value="option2" id="opt2" />
    <label htmlFor="opt2">Option 2</label>
  </div>
</RadioGroup>

Select

File: components/ui/select.tsx Description: Dropdown select input. Use cases: Dropdowns, option selection Components: Select, SelectTrigger, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectValue Example:

import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui";

<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="1">Option 1</SelectItem>
    <SelectItem value="2">Option 2</SelectItem>
  </SelectContent>
</Select>

Slider

File: components/ui/slider.tsx Description: Range slider input. Use cases: Filters, volume, range selection

Switch

File: components/ui/switch.tsx Description: Toggle switch (on/off). Use cases: Settings, feature toggles, binary options Example:

import { Switch } from "@/components/ui";

<Switch id="notifications" />
<label htmlFor="notifications">Enable notifications</label>

Textarea

File: components/ui/textarea.tsx Description: Multi-line text input. Use cases: Comments, descriptions, long text

Toggle

File: components/ui/toggle.tsx Description: Toggle button (pressed/unpressed). Use cases: Formatting options, view toggles

Toggle Group

File: components/ui/toggle-group.tsx Description: Group of toggle buttons (single or multiple selection). Use cases: Text formatting, view modes, filters

Feedback & Display

Alert

File: components/ui/alert.tsx Description: Callout for user attention (info/warning/error). Use cases: Error messages, warnings, notifications Components: Alert, AlertTitle, AlertDescription Example:

import { Alert, AlertDescription, AlertTitle } from "@/components/ui";

<Alert variant="destructive">
  <AlertTitle>Error</AlertTitle>
  <AlertDescription>Something went wrong.</AlertDescription>
</Alert>

Avatar

File: components/ui/avatar.tsx Description: User profile image with fallback. Use cases: User profiles, author info, contact lists Components: Avatar, AvatarImage, AvatarFallback

Badge

File: components/ui/badge.tsx Description: Small status indicator or label. Use cases: Status tags, labels, counts, categories Variants: default, primary, secondary, success, warning, destructive, outline Example:

import { Badge } from "@/components/ui";

<Badge variant="success">In Stock</Badge>
<Badge variant="warning">Backorder</Badge>
<Badge variant="destructive">Out of Stock</Badge>

Calendar

File: components/ui/calendar.tsx Description: Date picker calendar component. Use cases: Date selection, scheduling, date ranges

Carousel

File: components/ui/carousel.tsx Description: Swipeable image/content carousel. Use cases: Image galleries, product showcases, testimonials Components: Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext

Chart

File: components/ui/chart.tsx Description: Data visualization charts (powered by Recharts). Use cases: Analytics, dashboards, statistics

Progress

File: components/ui/progress.tsx Description: Progress bar indicator. Use cases: Loading states, upload progress, completion status

Skeleton

File: components/ui/skeleton.tsx Description: Loading placeholder with shimmer effect. Use cases: Content loading, skeleton screens Example:

import { Skeleton } from "@/components/ui";

<Skeleton className="h-12 w-full" />

Table

File: components/ui/table.tsx Description: Data table with consistent styling. Use cases: Data grids, lists, structured data Components: Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption Example:

import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui";

<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Name</TableHead>
      <TableHead>Price</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Product 1</TableCell>
      <TableCell>$99</TableCell>
    </TableRow>
  </TableBody>
</Table>

Toast / Sonner

File: components/ui/toaster.tsx Description: Toast notifications (powered by Sonner). Use cases: Success messages, errors, notifications Example:

import { toast } from "sonner";

toast.success("Item added to cart");
toast.error("Failed to save changes");
toast("Info message", { description: "Additional details" });

🎨 Moby Design System Integration

All components use the data-surface attribute system for consistent theming:

// Example: Button with surface theming
<button data-surface="primary">Primary Button</button>
<button data-surface="secondary">Secondary Button</button>
<button data-surface="success">Success Button</button>

Surface variants:

• primary - Moby Blue (emphasis)
• secondary - Gray (subtle)
• success - Green (positive actions)
• warning - Orange (caution)
• destructive - Red (danger)
• outline - Transparent with border
• ghost - Minimal styling

🔧 Customization

All components are fully customizable:

1. Direct editing - Components are in your codebase (components/ui/)
2. Tailwind classes - Pass className prop to override styles
3. Variants - Use CVA (class-variance-authority) for new variants
4. Moby DS tokens - Consistent colors via data-surface

Example: Custom Button

// Use existing variant
<Button variant="primary">Standard Primary</Button>

// Override with Tailwind classes
<Button variant="primary" className="rounded-full px-8">
  Custom Styling
</Button>

// Extend in component file
// components/ui/button.tsx
const buttonVariants = cva("...", {
  variants: {
    variant: {
      // Add new variant
      custom: "bg-purple-500 hover:bg-purple-600"
    }
  }
});

📖 Usage Best Practices

1. Import from barrel file:

   import { Button, Card, Input } from "@/components/ui";

2. Use TypeScript types:

   import type { ButtonProps } from "@/components/ui";

3. Consistent spacing:

   <div className="flex gap-2"> {/* Use gap-2, gap-4, etc. */}
     <Button>Action 1</Button>
     <Button>Action 2</Button>
   </div>

4. Accessibility:

   • Always provide aria-label for icon-only buttons
   • Use semantic HTML (<button> not <div role="button">)
   • Ensure keyboard navigation works (Tab, Enter, Space)

5. Form components with react-hook-form:

   // ✅ Use useWatch with React Compiler
   const value = useWatch({ control, name: 'fieldName' });
   
   // ❌ Don't use watch() method
   // const value = watch('fieldName');

🚀 Getting Started

Adding a new component

bunx shadcn@latest add [component-name]

Updating components

bunx shadcn@latest add [component-name] --overwrite

List available components

bunx shadcn@latest add

📚 Additional Resources

• shadcn/ui Documentation
• Radix UI Primitives (underlying library)
• Tailwind CSS v4
• CVA - Class Variance Authority
• React Hook Form
• Sonner - Toast Library

🔍 Component Quick Reference

Last Updated: 2025-01-17 Components Version: shadcn/ui latest Project: CROP Front-end (Next.js 15 + Tailwind CSS v4)