1# Component Selection
2 
3Decision matrices for choosing the right component. When in doubt, use the MCP `search_components` tool.
4 
5## Overlays
6 
7| Need | Component | Why |
8|---|---|---|
9| Confirmation dialog, focused task, form | `UModal` | Blocks page interaction, centered, draws focus |
10| Detail panel, settings, secondary content | `USlideover` | Slides from edge, doesn't feel as interruptive as modal |
11| Mobile-first bottom sheet | `UDrawer` | Natural mobile pattern, swipe to dismiss |
12| Contextual info attached to a trigger | `UPopover` | No backdrop, positioned relative to trigger |
13| Simple hover hint | `UTooltip` | Non-interactive, hover/focus only |
14 
15### Rules
16- Use `UModal` for destructive confirmations ("Are you sure you want to delete?")
17- Use `USlideover` for detail views in dashboards (email preview, user profile)
18- Use `UDrawer` for mobile navigation or action sheets
19- Modal and Slideover support `mode="drawer"` for automatic mobile drawer behavior
20- For programmatic overlays, use `useOverlay()` instead of `v-model:open`
21- Never put interactive content (buttons, links) inside `UTooltip`
22 
23## Navigation
24 
25| Need | Component | Why |
26|---|---|---|
27| Primary site/app navigation | `UNavigationMenu` | Horizontal (header) or vertical (sidebar) |
28| Switch between views on same page | `UTabs` | Content stays on page, no route change needed |
29| Show current location in hierarchy | `UBreadcrumb` | Nested page structures |
30| Search + keyboard-driven navigation | `UCommandPalette` | Power users, global search |
31| Contextual actions on a trigger element | `UDropdownMenu` | Right-click menus, action buttons |
32| Step-by-step process | `UStepper` | Multi-step forms, wizards |
33 
34### Rules
35- Use `UNavigationMenu` with `orientation="vertical"` in sidebars, default horizontal in headers
36- Use `UTabs` when switching views that don't need their own URL
37- Use route-based navigation (`to` prop) when views should have shareable URLs
38- `UCommandPalette` is typically opened via `Cmd+K` shortcut — use `defineShortcuts` to wire it up
39 
40## Inputs
41 
42| Need | Component | Why |
43|---|---|---|
44| Small fixed list (< 10 items) | `USelect` | Native-like, simple, lightweight |
45| Searchable list, multiple selection, groups | `USelectMenu` | Rich dropdown with search, multi-select, grouped items |
46| Autocomplete / combobox (type + select) | `UInputMenu` | User can type freely AND pick from suggestions |
47| Free text entry | `UInput` | Plain text, email, password, search |
48| Multi-line text | `UTextarea` | With `autoresize` and `maxrows` |
49| Numeric value with +/- controls | `UInputNumber` | Min/max/step constraints |
50| Date selection | `UInputDate` | Calendar dropdown, supports ranges |
51| Time selection | `UInputTime` | Hour/minute picker, 12/24 hour |
52| Tags / multi-value free text | `UInputTags` | Chip-style input with max limit |
53| Verification code | `UPinInput` | Fixed-length code entry |
54| Boolean toggle | `USwitch` | On/off, enable/disable |
55| Boolean checkbox | `UCheckbox` | Single option with label |
56| Multiple choices from a list | `UCheckboxGroup` | Multiple selection, vertical or horizontal |
57| Single choice from a list (visible) | `URadioGroup` | All options visible, one selected |
58| Range value | `USlider` | Min/max with visual track |
59| Color value | `UColorPicker` | Hex/RGB/HSL picker |
60| File upload | `UFileUpload` | Button or drop area variants |
61 
62### Rules
63- Use `UAuthForm` for login/signup pages — handles fields, social providers, validation, and layout out of the box
64- Use `USelect` for short, known lists (country, status, role)
65- Use `USelectMenu` when the list is long or needs search
66- Use `UInputMenu` when the user might want to type a value that's not in the list
67- Wrap all form inputs in `UFormField` for labels, descriptions, hints, and validation errors
68- Group related inline inputs with `UFieldGroup`
69 
70## Feedback
71 
72| Need | Component | Why |
73|---|---|---|
74| Ephemeral notification after action | `useToast()` | Auto-dismisses, stacks, non-blocking |
75| Inline persistent message | `UAlert` | Stays visible, in-page context |
76| App-wide announcement | `UBanner` | Sticky top bar, dismissible |
77| Loading state | `USkeleton` | Placeholder shimmer while loading |
78| Progress indicator | `UProgress` | Determinate or indeterminate progress |
79 
80### Rules
81- Use `useToast()` for action feedback: "Item saved", "Email sent", "Error occurred"
82- Use `UAlert` for contextual warnings in forms or sections
83- Use `UBanner` for site-wide messages (maintenance, new feature)
84- Never use a toast for information the user needs to act on — use an alert or modal instead
85 
86## Markdown
87 
88When rendering Markdown (for instance with Comark), **prefer Prose components** — they are styled and tuned for Markdown contexts. Generic Nuxt UI components can also be used. `<ComarkRenderer>` (or `<Comark>`) auto-resolves `ProseX` components when `@nuxt/ui` is installed. In Markdown, the `Prose` prefix can be omitted (`::callout`, `::steps`, etc.).
89 
90| Need | Use | Not |
91|---|---|---|
92| Note / warning / tip | `Callout` | `UAlert` |
93| Tabbed content | `Tabs` + `TabsItem` | `UTabs` |
94| Step-by-step list | `Steps` | custom list |
95| Content card grid | `Card` + `CardGroup` | `UCard` |
96| Collapsible section | `Collapsible` / `Accordion` | `UCollapsible` / `UAccordion` |
97| Tabbed code blocks | `CodeGroup` | manual tabs |
98 
99### Rules
100- Prose components use native Vue slots — Comark maps named `#slot` blocks directly to `<slot name="..." />`
101- Theme via `appConfig.ui.prose.<name>` using the same override pattern as other Nuxt UI components
102- `Callout` colors: `neutral` (default), `primary`, `secondary`, `info`, `success`, `warning`, `error`
103 
104## Layout containers
105 
106| Need | Component | Why |
107|---|---|---|
108| Grouped content with header/body/footer | `UCard` | Bordered/shadow container with slots |
109| Rich content card with icon, badge, links | `UPageCard` | Extended card for grids — supports icon, badge, highlight, links |
110| Marketing page section | `UPageSection` | Full-width section with headline, title, features |
111| Page hero | `UPageHero` | Title + description + links + optional media |
112| Call to action | `UPageCTA` | Highlighted section with action links |
113| Feature grid | `UPageGrid` + `UPageCard` | Multi-column card grid |
114| Centered content wrapper | `UContainer` | Max-width container |
115| Collapsible section | `UCollapsible` | Animated expand/collapse |
116| Accordion (multiple collapsibles) | `UAccordion` | FAQ, grouped collapsible content |
117 
118### Rules
119- Don't overuse `UCard` — plain content with spacing is often better than wrapping everything in cards
120- Use `UPageCard` instead of `UCard` when you need icon, badge, highlight, or links — it's designed for feature grids and landing pages
121- Use `UPageSection` for marketing/landing page sections, not for app UI
122- Use `UContainer` inside `UDashboardPanel` body for consistent content width
123