1---
2name: nuxt-ui
3description: Build UIs with @nuxt/ui v4 — 125+ accessible Vue components with Tailwind CSS theming. Use when creating interfaces, customizing themes to match a brand, building forms, or composing layouts like dashboards, docs sites, and chat interfaces.
4---
5 
6# Nuxt UI
7 
8Vue component library built on [Reka UI](https://reka-ui.com/) + [Tailwind CSS](https://tailwindcss.com/) + [Tailwind Variants](https://www.tailwind-variants.org/). Works with Nuxt, Vue (Vite), Laravel (Vite + Inertia), and AdonisJS (Vite + Inertia).
9 
10## MCP Server
11 
12For component API details (props, slots, events, full documentation, examples), use the [Nuxt UI MCP server](https://ui.nuxt.com/docs/getting-started/ai/mcp). If not already configured, add it:
13 
14**Cursor** — `.cursor/mcp.json`:
15 
16```json
17{ "mcpServers": { "nuxt-ui": { "type": "http", "url": "https://ui.nuxt.com/mcp" } } }
18```
19 
20**Claude Code**:
21 
22```bash
23claude mcp add --transport http nuxt-ui https://ui.nuxt.com/mcp
24```
25 
26Key MCP tools:
27- `search_components` — find components by name, description, or category (no params = list all)
28- `search_composables` — find composables by name or description (no params = list all)
29- `search_icons` — search Iconify icons (defaults to `lucide`), returns `i-{prefix}-{name}` names
30- `get_component` — full component documentation with usage examples
31- `get_component_metadata` — props, slots, events (lightweight, no docs content)
32- `get_example` — real-world code examples
33 
34When you need to know **what a component accepts** or **how its API works**, use the MCP. This skill teaches you **when to use which component** and **how to build well**.
35 
36## Core rules (always apply)
37 
381. **Always wrap the app in `UApp`** — required for toasts, tooltips, and programmatic overlays. Accepts a `locale` prop for i18n.
392. **Always use semantic colors** — `text-default`, `bg-elevated`, `border-muted`, etc. Never use raw Tailwind palette colors like `text-gray-500`.
403. **Read generated theme files for slot names** — Nuxt: `.nuxt/ui/<component>.ts`, Vue: `node_modules/.nuxt-ui/ui/<component>.ts`. These show every slot, variant, and default class for any component.
414. **Override priority** (highest wins): `ui` prop / `class` prop → global config → theme defaults.
425. **Icons use `i-{collection}-{name}` format** — `lucide` is the default collection. Use the MCP `search_icons` tool to find icons, or browse at [icones.js.org](https://icones.js.org).
43 
44## How to use this skill
45 
46Based on the task, load the relevant reference files **before writing any code**. Don't load everything — only what's needed.
47 
48### Reference files
49 
50**Guidelines** — design decisions and conventions:
51- [design-system](references/guidelines/design-system.md) — semantic colors, theming, brand customization, variants, the `ui` prop
52- [component-selection](references/guidelines/component-selection.md) — decision matrices: when to use Modal vs Slideover, Select vs SelectMenu, Toast vs Alert, etc.
53- [conventions](references/guidelines/conventions.md) — coding patterns, slot naming, items arrays, composables, keyboard shortcuts
54- [forms](references/guidelines/forms.md) — form validation, field layout, error handling, Standard Schema
55 
56**Layouts** — full page structure patterns:
57- [landing](references/layouts/landing.md) — landing pages, blog, changelog, pricing
58- [dashboard](references/layouts/dashboard.md) — admin UI with sidebar and panels
59- [docs](references/layouts/docs.md) — documentation sites with navigation and TOC
60- [chat](references/layouts/chat.md) — AI chat with Vercel AI SDK
61- [editor](references/layouts/editor.md) — rich text editor with toolbars
62 
63**Recipes** — complete patterns for common tasks:
64- [data-tables](references/recipes/data-tables.md) — tables with filters, pagination, sorting, selection
65- [auth](references/recipes/auth.md) — login, signup, forgot password forms
66- [overlays](references/recipes/overlays.md) — modals, slideovers, drawers, command palette
67- [navigation](references/recipes/navigation.md) — headers, sidebars, breadcrumbs, tabs
68 
69**Quick reference:**
70- [components](references/components.md) — categorized component index for finding the right component name
71 
72### Routing table
73 
74| Task | Load these references |
75|---|---|
76| Build a landing page | design-system, conventions, landing |
77| Build a dashboard / admin UI | conventions, component-selection, dashboard |
78| Add a settings page | conventions, forms |
79| Create a login / signup form | conventions, forms, auth |
80| Display data in a table | conventions, component-selection, data-tables |
81| Customize theme / brand colors | design-system |
82| Add a chat interface | conventions, chat |
83| Add a modal, slideover, or drawer | conventions, component-selection, overlays |
84| Build site navigation | conventions, component-selection, navigation |
85| Build a documentation site | conventions, docs |
86| Render markdown | component-selection, components, docs |
87| Add a rich text editor | conventions, editor |
88| General UI work | conventions, component-selection |
89 
90## Installation
91 
92### Nuxt
93 
94```bash
95pnpm add @nuxt/ui tailwindcss
96```
97 
98```ts
99// nuxt.config.ts
100export default defineNuxtConfig({
101  modules: ['@nuxt/ui'],
102  css: ['~/assets/css/main.css']
103})
104```
105 
106```css
107/* app/assets/css/main.css */
108@import "tailwindcss";
109@import "@nuxt/ui";
110```
111 
112```vue
113<!-- app.vue -->
114<template>
115  <UApp>
116    <NuxtPage />
117  </UApp>
118</template>
119```
120 
121### Vue (Vite)
122 
123```bash
124pnpm add @nuxt/ui tailwindcss
125```
126 
127```ts
128// vite.config.ts
129import { defineConfig } from 'vite'
130import vue from '@vitejs/plugin-vue'
131import ui from '@nuxt/ui/vite'
132 
133export default defineConfig({
134  plugins: [
135    vue(),
136    ui()
137  ]
138})
139```
140 
141```ts
142// src/main.ts
143import './assets/css/main.css'
144import { createApp } from 'vue'
145import { createRouter, createWebHistory } from 'vue-router'
146import ui from '@nuxt/ui/vue-plugin'
147import App from './App.vue'
148 
149const app = createApp(App)
150const router = createRouter({
151  routes: [],
152  history: createWebHistory()
153})
154 
155app.use(router)
156app.use(ui)
157app.mount('#app')
158```
159 
160```css
161/* src/assets/css/main.css */
162@import "tailwindcss";
163@import "@nuxt/ui";
164```
165 
166```vue
167<!-- src/App.vue -->
168<template>
169  <UApp>
170    <RouterView />
171  </UApp>
172</template>
173```
174 
175> Add `class="isolate"` to your root `<div id="app">` in `index.html`.
176> For Inertia: use `ui({ router: 'inertia' })` in `vite.config.ts`.
177