nuxt-ui

Nuxt UI v4

基于 Reka UI（无头组件）+ Tailwind CSS v4 + Tailwind Variants 构建的 Vue 3 和 Nuxt 4+ 组件库。

当前稳定版本： v4.3.0（2025 年 12 月）

适用场景

• 安装/配置 @nuxt/ui
• 使用 UI 组件（Button、Card、Table、Form 等）
• 自定义主题（颜色、变体、CSS 变量）
• 构建带验证的表单
• 使用覆盖层（Modal、Toast、CommandPalette）
• 使用组合式函数（useToast、useOverlay）

Vue 组件模式： 使用 vue 技能
Nuxt 路由/服务端： 使用 nuxt 技能

可用指南

文件	主题
references/installation.md	Nuxt/Vue 设置、pnpm 注意事项、UApp 包装器、模块选项、前缀、摇树优化
references/theming.md	语义颜色、CSS 变量、app.config.ts、Tailwind Variants
references/components.md	按类别排列的组件索引（125+ 个组件）
components/*.md	各组件详情（button.md、modal.md 等）
references/forms.md	表单组件、验证（Zod/Valibot）、useFormField
references/overlays.md	Toast、Modal、Slideover、Drawer、CommandPalette
references/composables.md	useToast、useOverlay、defineShortcuts、useScrollspy

使用模式

根据上下文加载：

• 安装 Nuxt UI？→ references/installation.md
• 自定义主题？→ references/theming.md
• 组件索引 → references/components.md
• 特定组件 → components/button.md、components/modal.md 等
• 构建表单？→ references/forms.md
• 使用覆盖层？→ references/overlays.md
• 使用组合式函数？→ references/composables.md

不要一次性读取所有文件。 根据上下文加载。

核心概念

概念	描述
UApp	Toast、Tooltip 和覆盖层所需的包装器组件
Tailwind Variants	支持插槽、变体和复合变体的类型安全样式
语义颜色	primary、secondary、success、error、warning、info、neutral
Reka UI	无头组件基元（内置无障碍功能）

关于无头组件基元（API 详情、无障碍模式、asChild）：请阅读 reka-ui 技能

快速参考

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

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

<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

资源

• Nuxt UI 文档
• 组件参考
• 主题自定义

---

令牌效率：主技能约 300 个令牌，每个子文件约 800-1200 个令牌