nuxt-ui-v4

Nuxt UI v4 - 生产级组件库

版本：Nuxt UI v4.6+ | Nuxt v4.0.0 | 125+ 个组件 最后验证时间：2026-03-30

全面的生产级组件库，包含 125+ 个无障碍组件、Tailwind CSS v4、Reka UI 无障碍支持，以及一流的 AI 集成。适用于 Nuxt 和纯 Vue 应用（Vite、Inertia、SSR）。

MCP 集成：此插件包含官方 Nuxt UI MCP 服务，可获取实时组件数据。

---

何时使用 / 不要使用

适用场景：使用 Nuxt UI 组件构建 Nuxt v4 仪表盘、AI 聊天界面、落地页、表单、管理面板、定价页、博客、文档站点或任何 UI

不要用于：React 项目、Nuxt 3 或更早版本、Tailwind CSS v3。纯 Vue 项目也受支持，可通过 Vite 插件使用。

---

快速开始

bunx nuxi init my-app && cd my-app
bun add @nuxt/ui tailwindcss

// 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>

或使用模板：

npm create nuxt@latest -- -t ui             # Starter
npm create nuxt@latest -- -t ui/dashboard    # Dashboard
npm create nuxt@latest -- -t ui/chat         # AI Chat
npm create nuxt@latest -- -t ui/landing      # Landing page
npm create nuxt@latest -- -t ui/saas         # SaaS
npm create nuxt@latest -- -t ui/docs         # Documentation
npm create nuxt@latest -- -t ui/portfolio    # Portfolio
npm create nuxt@latest -- -t ui/changelog    # Changelog
npm create nuxt@latest -- -t ui/editor       # Rich text editor

可用命令：/nuxt-ui-v4:setup、/nuxt-ui:migrate、/nuxt-ui:theme、/nuxt-ui:component

安全安装

UI 包会修改 CSS 和组件树 — 在允许其进入项目之前，请先进行验证。请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新版本的包
• 安装前审计 — 运行 socket package score npm <pkg> 或使用 socket npm install <pkg> 检查包

加载 dependency-upgrade 技能，获取完整安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

---

组件类别（共 125+ 个）

仪表盘（10 个组件）- 新增

完整的管理界面系统：

• DashboardGroup - 固定布局容器，带侧边栏状态管理
• DashboardSidebar - 可调整大小、可折叠的侧边栏
• DashboardPanel - 主内容面板，带页眉／主体／页脚插槽
• DashboardNavbar - 顶部导航栏
• DashboardToolbar - 导航栏下方的辅助工具栏
• DashboardSearch - 用于仪表盘搜索的 CommandPalette
• DashboardSearchButton - 触发搜索的按钮
• DashboardSidebarCollapse - 桌面端折叠按钮
• DashboardSidebarToggle - 移动端切换按钮
• DashboardResizeHandle - 侧边栏／面板的调整大小手柄

<template>
  <UDashboardGroup>
    <UDashboardSidebar>
      <UNavigationMenu :items="menuItems" />
    </UDashboardSidebar>
    <UDashboardPanel>
      <template #header><UDashboardNavbar /></template>
      <template #body><NuxtPage /></template>
    </UDashboardPanel>
  </UDashboardGroup>
</template>

详情：加载 references/dashboard-components.md，查看完整的仪表盘模式

---

聊天／AI（8 个组件）

专为使用 AI SDK v5 的 AI 聊天机器人打造：

• ChatMessage - 单条消息，带图标、头像和操作
• ChatMessages - 消息列表，支持自动滚动和状态指示器
• ChatPalette - 叠加层中的聊天界面
• ChatPrompt - 增强型 AI 提示词 Textarea
• ChatPromptSubmit - 带状态处理的提交按钮
• ChatReasoning - 可折叠的 AI 推理／思考过程（v4.6 新增）
• ChatTool - 可折叠的 AI 工具调用状态（v4.6 新增）
• ChatShimmer - 流式状态下的文本闪烁动画（v4.6 新增）

<script setup lang="ts">
import { isReasoningUIPart, isTextUIPart, isToolUIPart, getToolName } from 'ai'
import { Chat } from '@ai-sdk/vue'
import { isReasoningStreaming, isToolStreaming } from '@nuxt/ui/utils/ai'

const input = ref('')
const chat = new Chat({
  onError(error) { console.error(error) }
})

function onSubmit() {
  chat.sendMessage({ text: input.value })
  input.value = ''
}
</script>

<template>
  <UChatMessages :messages="chat.messages" :status="chat.status">
    <template #content="{ message }">
      <template v-for="(part, index) in message.parts" :key="`${message.id}-${part.type}-${index}`">
        <UChatReasoning v-if="isReasoningUIPart(part)" :text="part.text" :streaming="isReasoningStreaming(message, index, chat)" />
        <UChatTool v-else-if="isToolUIPart(part)" :text="getToolName(part)" :streaming="isToolStreaming(part)" />
        <template v-else-if="isTextUIPart(part)">
          <MDC v-if="message.role === 'assistant'" :value="part.text" :cache-key="`${message.id}-${index}`" />
          <p v-else-if="message.role === 'user'" class="whitespace-pre-wrap">{{ part.text }}</p>
        </template>
      </template>
    </template>
  </UChatMessages>
  <UChatPrompt v-model="input" @submit="onSubmit">
    <UChatPromptSubmit :status="chat.status" @stop="chat.stop()" @reload="chat.regenerate()" />
  </UChatPrompt>
</template>

详情：加载 references/chat-components.md，了解完整的 AI SDK 集成、流式传输、推理和工具调用

---

编辑器（6 个组件）- 新增

使用 TipTap 进行富文本编辑：

• Editor - 基于 TipTap 的编辑器，支持 markdown／HTML／JSON
• EditorToolbar - 固定、气泡或浮动工具栏
• EditorDragHandle - 用于重新排序区块的拖动手柄
• EditorMentionMenu - @ 提及建议
• EditorEmojiMenu - : 表情选择器
• EditorSuggestionMenu - / 命令菜单

<template>
  <UEditor v-model="content" :extensions="extensions">
    <template #toolbar>
      <UEditorToolbar />
    </template>
  </UEditor>
</template>

详情：加载 references/editor-components.md，了解 TipTap 设置、扩展和工具栏自定义

---

页面布局（16 个组件）- 新增

落地页和内容布局：

• Page - 带左右列的网格布局
• PageHeader - 响应式页面页眉
• PageHero - 包含标题、描述和 CTA 的主视觉区域
• PageSection - 内容区块容器
• PageGrid - 响应式网格系统
• PageColumns - 多列布局
• PageFeature - 功能展示组件
• PageCTA - 行动号召区块
• PageCard - 预设样式的卡片，包含标题、描述和链接
• PageList - 垂直列表布局
• PageLogos - Logo 展示
• PageAnchors - 锚点链接列表
• PageAside - 粘性侧边栏
• PageBody - 主内容区域
• PageLinks - 链接列表

<template>
  <UPage>
    <UPageHero title="Welcome" description="Get started today" :links="heroLinks" />
    <UPageSection>
      <UPageGrid>
        <UPageFeature v-for="f in features" v-bind="f" />
      </UPageGrid>
    </UPageSection>
    <UPageCTA title="Ready?" :links="ctaLinks" />
  </UPage>
</template>

详情：加载 references/page-layout-components.md，了解落地页模式

---

内容（7 个组件）- 新增

文档和博客内容：

• BlogPost - 文章展示组件
• BlogPosts - 博客网格布局
• ChangelogVersion - 版本条目展示
• ChangelogVersions - 更新日志时间线
• ContentNavigation - 用于文档的手风琴式导航
• ContentSearch - 文档搜索 CommandPalette
• ContentSearchButton - 打开搜索的按钮
• ContentSurround - 上一页/下一页导航
• ContentToc - 粘性目录

<template>
  <UBlogPosts>
    <UBlogPost v-for="post in posts" v-bind="post" />
  </UBlogPosts>
</template>

详情：加载 references/content-components.md，了解博客和文档模式

---

定价（3 个组件）- 新增

SaaS 定价页面：

• PricingPlan - 单个方案卡片
• PricingPlans - 响应式方案网格
• PricingTable - 功能对比表

<template>
  <UPricingPlans>
    <UPricingPlan
      v-for="plan in plans"
      :title="plan.title"
      :price="plan.price"
      :features="plan.features"
    />
  </UPricingPlans>
</template>

详情：加载 references/pricing-components.md，了解定价页面模式

---

表单（22 个组件）

Input、InputDate、InputTime、InputNumber、InputTags、InputMenu、Select、SelectMenu、Textarea、Checkbox、CheckboxGroup、RadioGroup、Switch、Slider、Calendar、ColorPicker、PinInput、Form、FormField、FileUpload、FieldGroup、AuthForm

<UForm :state="state" :schema="schema" @submit="onSubmit">
  <UFormField name="email" label="Email">
    <UInput v-model="state.email" type="email" />
  </UFormField>
  <UButton type="submit">Submit</UButton>
</UForm>

详情：加载 references/form-components-reference.md，了解验证、嵌套表单和文件上传

---

导航（8 个组件）

Tabs、Breadcrumb、Link、Pagination、CommandPalette、NavigationMenu、Stepper、Tree

<UTabs v-model="tab" :items="items" />
<UCommandPalette :groups="groups" placeholder="Search..." />
<UStepper v-model="step" :items="steps" />

详情：加载 references/navigation-components-reference.md，了解相关模式

---

覆盖层（8 个组件）

Modal、Drawer、Slideover、Dialog、Popover、DropdownMenu、ContextMenu、Tooltip

<UModal v-model="isOpen"><UCard>Content</UCard></UModal>
<UDrawer v-model="isOpen" side="right">...</UDrawer>

详情：加载 references/overlay-decision-guide.md，了解何时使用各组件

---

反馈（7 个组件）

Alert、Toast、Progress、Skeleton、Empty、Error、Banner

<UAlert color="warning" title="Warning message" />
<UEmpty icon="i-heroicons-inbox" title="No items" />
<UBanner title="Important announcement" />

详情：加载 references/feedback-components-reference.md

---

布局（6 个组件）

Card、Container、Main、Header、Footer、FooterColumns、Separator

---

数据（2 个组件）

Table（支持虚拟化）、ScrollArea

---

通用（15 个组件）

Button、FieldGroup、Avatar、AvatarGroup、Badge、Accordion、Carousel、Chip、Collapsible、Icon、Kbd、Marquee、Timeline、User、App

---

色彩模式（6 个组件）

ColorModeAvatar、ColorModeButton、ColorModeImage、ColorModeSelect、ColorModeSwitch、LocaleSelect

---

组合式函数

核心：useToast、useOverlay、useFormField、useScrollShadow 实用工具：defineShortcuts、defineLocale、extendLocale、extractShortcuts

const { add } = useToast()
add({ title: 'Success', color: 'success' })

defineShortcuts({ 'meta_k': () => openSearch() })

AI 实用工具：isReasoningStreaming、isToolStreaming、getTextFromMessage（来自 @nuxt/ui/utils/ai）

---

常见错误（前 5 项）

1. 缺少 UApp 包装器 → 使用 <UApp> 包装应用 2. CSS 导入顺序错误 → 先导入 @import "tailwindcss"，再导入 @import "@nuxt/ui" 3. 缺少 tailwindcss 包 → bun add @nuxt/ui tailwindcss（两者都必需） 4. 找不到模块 → 在 nuxt.config.ts 的 modules 中添加 '@nuxt/ui' 5. 找不到 useChat → AI SDK v5 使用 new Chat() 类，而不是 useChat() 组合式函数

完整列表：加载 references/COMMON_ERRORS_DETAILED.md，查看 25 个以上错误的解决方案

---

何时加载参考资料

仪表板/管理后台：dashboard-components.md AI 聊天：chat-components.md、ai-sdk-v5-integration.md 聊天子组件：chat-reasoning.md、chat-tool.md、chat-shimmer.md 富文本：editor-components.md 落地页：page-layout-components.md 定价/SaaS：pricing-components.md 博客/文档：content-components.md 身份验证/登录：auth-form.md 表单：form-components-reference.md、form-validation-patterns.md 主题：semantic-color-system.md、component-theming-guide.md 故障排除：COMMON_ERRORS_DETAILED.md

---

可用命令

• /nuxt-ui-v4:setup - 在项目中初始化 Nuxt UI
• /nuxt-ui:migrate - 从 v2/v3 迁移到 v4
• /nuxt-ui:theme - 生成主题配置
• /nuxt-ui:component - 使用 Nuxt UI 模式搭建组件

可用 Agent

• nuxt-ui-component-selector - 根据使用场景推荐最佳组件
• nuxt-ui-migration-assistant - 指导从 v2/v3 迁移到 v4
• nuxt-ui-troubleshooter - 诊断并修复常见问题

MCP 集成

此插件包含官方 Nuxt UI MCP 服务（https://ui.nuxt.com/mcp），提供：

• 组件列表和元数据
• 文档访问
• 迁移指南
• 模板发现