/nuxt-ui

Component Selection

Decision matrices for choosing the right component. When in doubt, use the MCP search-components tool.

Overlays

Rules

• Use UModal for destructive confirmations ("Are you sure you want to delete?")
• Use USlideover for detail views in dashboards (email preview, user profile)
• Use UDrawer for mobile navigation or action sheets
• Use UDashboardSidebar with mode="drawer" for a drawer-based mobile menu; UModal and USlideover don't expose a mode prop
• For programmatic overlays, use useOverlay() instead of v-model:open
• Never put interactive content (buttons, links) inside UTooltip

Navigation

Rules

• Use UNavigationMenu with orientation="vertical" in sidebars, default horizontal in headers
• Use UTabs when switching views that don't need their own URL
• Use route-based navigation (to prop) when views should have shareable URLs
• UCommandPalette is typically opened via Cmd+K shortcut — use defineShortcuts to wire it up

Inputs

Rules

• Use UAuthForm for login/signup pages — handles fields, social providers, validation, and layout out of the box
• Use USelect for short, known lists (country, status, role)
• Use USelectMenu when the list is long or needs search
• Use UInputMenu when the user might want to type a value that's not in the list
• Wrap all form inputs in UFormField for labels, descriptions, hints, and validation errors
• Group related inline inputs with UFieldGroup

Feedback

Rules

• Use useToast() for action feedback: "Item saved", "Email sent", "Error occurred"
• Use UAlert for contextual warnings in forms or sections
• Use UBanner for site-wide messages (maintenance, new feature)
• Never use a toast for information the user needs to act on — use an alert or modal instead

Markdown

When 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.).

Rules

• Prose components use native Vue slots — Comark maps named #slot blocks directly to <slot name="..." />
• Theme via appConfig.ui.prose.<name> using the same override pattern as other Nuxt UI components
• Callout colors: neutral (default), primary, secondary, info, success, warning, error

Layout containers

Rules

• Don't overuse UCard — plain content with spacing is often better than wrapping everything in cards
• Use UPageCard instead of UCard when you need icon, badge, highlight, or links — it's designed for feature grids and landing pages
• Use UPageSection for marketing/landing page sections, not for app UI
• Use UContainer inside UDashboardPanel body for consistent content width