ahmadzakiy/nuxt-ui

Nuxt UI

Vue component library built on Reka UI + Tailwind CSS + Tailwind Variants. Works with Nuxt, Vue (Vite), Laravel (Vite + Inertia), and AdonisJS (Vite + Inertia).

MCP Server

For component API details (props, slots, events, full documentation, examples), use the Nuxt UI MCP server. If not already configured, add it:

Cursor — .cursor/mcp.json:

{ "mcpServers": { "nuxt-ui": { "type": "http", "url": "https://ui.nuxt.com/mcp" } } }

Claude Code:

claude mcp add --transport http nuxt-ui https://ui.nuxt.com/mcp

Key MCP tools:

• search_components — find components by name, description, or category (no params = list all)
• search_composables — find composables by name or description (no params = list all)
• search_icons — search Iconify icons (defaults to lucide), returns i-{prefix}-{name} names
• get_component — full component documentation with usage examples
• get_component_metadata — props, slots, events (lightweight, no docs content)
• get_example — real-world code examples

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

Core rules (always apply)

1. Always wrap the app in UApp — required for toasts, tooltips, and programmatic overlays. Accepts a locale prop for i18n.
2. Always use semantic colors — text-default, bg-elevated, border-muted, etc. Never use raw Tailwind palette colors like text-gray-500.
3. 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.
4. Override priority (highest wins): ui prop / class prop → global config → theme defaults.
5. 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.

How to use this skill

Based on the task, load the relevant reference files before writing any code. Don't load everything — only what's needed.

Reference files

Guidelines — design decisions and conventions:

• design-system — semantic colors, theming, brand customization, variants, the ui prop
• component-selection — decision matrices: when to use Modal vs Slideover, Select vs SelectMenu, Toast vs Alert, etc.
• conventions — coding patterns, slot naming, items arrays, composables, keyboard shortcuts
• forms — form validation, field layout, error handling, Standard Schema

Layouts — full page structure patterns:

• landing — landing pages, blog, changelog, pricing
• dashboard — admin UI with sidebar and panels
• docs — documentation sites with navigation and TOC
• chat — AI chat with Vercel AI SDK
• editor — rich text editor with toolbars

Recipes — complete patterns for common tasks:

• data-tables — tables with filters, pagination, sorting, selection
• auth — login, signup, forgot password forms
• overlays — modals, slideovers, drawers, command palette
• navigation — headers, sidebars, breadcrumbs, tabs

Quick reference:

• components — categorized component index for finding the right component name

Routing table

| Task | Load these references | |---|---| | Build a landing page | design-system, conventions, landing | | Build a dashboard / admin UI | conventions, component-selection, dashboard | | Add a settings page | conventions, forms | | Create a login / signup form | conventions, forms, auth | | Display data in a table | conventions, component-selection, data-tables | | Customize theme / brand colors | design-system | | Add a chat interface | conventions, chat | | Add a modal, slideover, or drawer | conventions, component-selection, overlays | | Build site navigation | conventions, component-selection, navigation | | Build a documentation site | conventions, docs | | Add a rich text editor | conventions, editor | | General UI work | conventions, component-selection |

Installation

Nuxt

pnpm add @nuxt/ui tailwindcss

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css']
})

/* app/assets/css/main.css */
@import "tailwindcss";
@import "@nuxt/ui";

<!-- app.vue -->
<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

Vue (Vite)

pnpm add @nuxt/ui tailwindcss

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})

// src/main.ts
import './assets/main.css'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)
const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)
app.mount('#app')

/* assets/main.css */
@import "tailwindcss";
@import "@nuxt/ui";

<!-- src/App.vue -->
<template>
  <UApp>
    <RouterView />
  </UApp>
</template>

Add class="isolate" to your root <div id="app"> in index.html. For Inertia: use ui({ router: 'inertia' }) in vite.config.ts.