Component Selection

Overlay Components: Dialog vs Sheet vs Drawer

When to Use Each

Decision Flow

Need to interrupt user for focused action?
├── Yes → Is it a simple confirmation?
│         ├── Yes → AlertDialog
│         └── No → Dialog
└── No → Is it supplementary/contextual content?
          ├── Yes → Does it need significant space?
          │         ├── Yes → Sheet
          │         └── No → Popover
          └── No → Is it mobile navigation?
                    ├── Yes → Drawer
                    └── No → Consider inline content

Specific Use Cases

Feedback Components: Alert vs Toast vs Dialog

When to Use Each

Decision Flow

Is immediate user action required?
├── Yes → Is it destructive/irreversible?
│         ├── Yes → AlertDialog with confirm
│         └── No → AlertDialog or Dialog
└── No → Should it persist until dismissed?
          ├── Yes → Alert (inline)
          └── No → Toast (Sonner)

Feedback Severity Hierarchy

State Combination Patterns

// Loading → Error
{isLoading && <Skeleton />}
{error && <Alert variant="destructive">...</Alert>}
{data && <Content />}

// Loading → Empty
{isLoading && <Skeleton />}
{!isLoading && data.length === 0 && <EmptyState />}
{!isLoading && data.length > 0 && <DataTable data={data} />}

Specific Use Cases

Selection Components: Select vs Combobox vs RadioGroup

When to Use Each

Decision Flow

How many options?
├── 2-5 options → Are they mutually exclusive?
│                 ├── Yes → RadioGroup
│                 └── No → Multiple Checkboxes
├── 5-15 options → Select
└── 15+ options → Combobox (searchable)

Need to select multiple?
├── Yes → Is it a short list?
│         ├── Yes → Checkbox group
│         └── No → Multi-select Combobox
└── No → Select, Combobox, or RadioGroup

Specific Use Cases

Text Input Components: Input vs Textarea vs Rich Text

When to Use Each

Decision Flow

Is the content single-line?
├── Yes → Input (with appropriate type)
└── No → Does it need formatting?
          ├── Yes → Rich Text Editor
          └── No → Textarea

Input Types

Navigation Components: Tabs vs Accordion vs Stepper

When to Use Each

Decision Flow

Is this a multi-step process?
├── Yes → Stepper or multi-page wizard
└── No → Are sections peer-level content?
          ├── Yes → Is space limited?
          │         ├── Yes → Tabs
          │         └── No → Separate cards
          └── No → Is it Q&A or details?
                    ├── Yes → Accordion
                    └── No → Tabs or separate sections

Specific Use Cases

Button Variants

When to Use Each Variant

Decision Flow

Is this the main action on the page?
├── Yes → default (primary)
└── No → Is it destructive?
          ├── Yes → destructive
          └── No → Is it a cancel/dismiss?
                    ├── Yes → outline
                    └── No → Is it in a toolbar?
                              ├── Yes → ghost
                              └── No → secondary

Button Pairing Rules

Rule: Never pair two default buttons side by side.

Menu Components: DropdownMenu vs ContextMenu vs Menubar

When to Use Each

Decision Flow

How is the menu triggered?
├── Click on button → DropdownMenu
├── Right-click → ContextMenu
├── Keyboard shortcut → Command (palette)
└── App navigation bar → Menubar

Data Display: Table vs DataTable vs List

When to Use Each

Decision Flow

Is the data tabular (rows/columns)?
├── Yes → Needs sorting/filtering?
│         ├── Yes → DataTable (with TanStack)
│         └── No → Table
└── No → Is each item visually rich?
          ├── Yes → Card grid/list
          └── No → Simple list

Tooltip vs Popover vs HoverCard

When to Use Each

Decision Flow

Is the content interactive (buttons, links)?
├── Yes → Popover
└── No → Is it a rich preview?
          ├── Yes → HoverCard
          └── No → Tooltip

Specific Use Cases

Quick Reference Table

Last updated: February 4, 2026