nuxt-ui-v4

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Nuxt UI v4 - Production Component Library

Nuxt UI v4 - 生产级组件库

Version: Nuxt UI v4.2.1 | Nuxt v4.0.0 | 125+ Components Last Verified: 2025-12-28
A comprehensive production-ready component library with 125+ accessible components, Tailwind CSS v4, Reka UI accessibility, and first-class AI integration.
MCP Integration: This plugin includes the official Nuxt UI MCP server for live component data.

版本: Nuxt UI v4.2.1 | Nuxt v4.0.0 | 125+ 组件 最后验证时间: 2025-12-28
这是一个全面的生产就绪组件库,包含125+个可访问性组件,支持Tailwind CSS v4、Reka UI无障碍标准,以及一流的AI集成。
MCP 集成: 该插件包含官方Nuxt UI MCP服务器,可提供实时组件数据。

When to Use / NOT Use

适用场景 / 不适用场景

Use when: Building Nuxt v4 dashboards, AI chat interfaces, landing pages, forms, admin panels, pricing pages, blogs, documentation sites, or any UI with Nuxt UI components
DON'T use: Vue-only projects (no Nuxt), React projects, Nuxt 3 or earlier, Tailwind CSS v3

适用场景: 构建Nuxt v4仪表板、AI聊天界面、着陆页、表单、管理面板、定价页面、博客、文档站点,或任何使用Nuxt UI组件的UI项目
不适用场景: 仅Vue项目(无Nuxt)、React项目、Nuxt 3或更早版本、Tailwind CSS v3

Quick Start

快速开始

bash
bunx nuxi init my-app && cd my-app
bun add @nuxt/ui
typescript
// nuxt.config.ts
export default defineNuxtConfig({ modules: ['@nuxt/ui'] })
vue
<!-- app.vue -->
<template><UApp><NuxtPage /></UApp></template>
<style>
@import "tailwindcss";
@import "@nuxt/ui";
</style>
Commands available:
/nuxt-ui-v4:setup
,
/nuxt-ui:migrate
,
/nuxt-ui:theme
,
/nuxt-ui:component

bash
bunx nuxi init my-app && cd my-app
bun add @nuxt/ui
typescript
// nuxt.config.ts
export default defineNuxtConfig({ modules: ['@nuxt/ui'] })
vue
<!-- app.vue -->
<template><UApp><NuxtPage /></UApp></template>
<style>
@import "tailwindcss";
@import "@nuxt/ui";
</style>
可用命令:
/nuxt-ui-v4:setup
,
/nuxt-ui:migrate
,
/nuxt-ui:theme
,
/nuxt-ui:component

Component Categories (125+ Total)

组件分类(共125+个)

Dashboard (11 components) - NEW

仪表板(11个组件)- 新增

Complete admin interface system:
  • DashboardGroup - Fixed layout wrapper with sidebar state management
  • DashboardSidebar - Resizable, collapsible sidebar
  • DashboardPanel - Main content panel with header/body/footer slots
  • DashboardNavbar - Top navigation bar
  • DashboardToolbar - Secondary toolbar under navbar
  • DashboardSearch - CommandPalette for dashboard search
  • DashboardSearchButton - Button to trigger search
  • DashboardSidebarCollapse - Collapse button for desktop
  • DashboardSidebarToggle - Toggle button for mobile
  • DashboardResizeHandle - Resize handle for sidebar/panels
vue
<template>
  <UDashboardGroup>
    <UDashboardSidebar>
      <UNavigationMenu :items="menuItems" />
    </UDashboardSidebar>
    <UDashboardPanel>
      <template #header><UDashboardNavbar /></template>
      <template #body><NuxtPage /></template>
    </UDashboardPanel>
  </UDashboardGroup>
</template>
Details: Load
references/dashboard-components.md
for complete dashboard patterns

完整的管理界面系统:
  • DashboardGroup - 固定布局包装器,带侧边栏状态管理
  • DashboardSidebar - 可调整大小、可折叠的侧边栏
  • DashboardPanel - 主内容面板,包含页眉/主体/页脚插槽
  • DashboardNavbar - 顶部导航栏
  • DashboardToolbar - 导航栏下方的二级工具栏
  • DashboardSearch - 用于仪表板搜索的命令面板
  • DashboardSearchButton - 触发搜索的按钮
  • DashboardSidebarCollapse - 桌面端折叠按钮
  • DashboardSidebarToggle - 移动端切换按钮
  • DashboardResizeHandle - 侧边栏/面板的调整大小手柄
vue
<template>
  <UDashboardGroup>
    <UDashboardSidebar>
      <UNavigationMenu :items="menuItems" />
    </UDashboardSidebar>
    <UDashboardPanel>
      <template #header><UDashboardNavbar /></template>
      <template #body><NuxtPage /></template>
    </UDashboardPanel>
  </UDashboardGroup>
</template>
详情: 加载
references/dashboard-components.md
获取完整的仪表板模式

Chat / AI (5 components) - NEW

聊天/AI(5个组件)- 新增

Purpose-built for AI chatbots with AI SDK v5:
  • ChatMessage - Single message with icon, avatar, actions
  • ChatMessages - Message list with auto-scroll, status indicator
  • ChatPalette - Chat interface inside an overlay
  • ChatPrompt - Enhanced Textarea for AI prompts
  • ChatPromptSubmit - Submit button with status handling
vue
<script setup>
import { Chat } from '@ai-sdk/vue'
const chat = new Chat({ api: '/api/chat' })
</script>

<template>
  <UChatMessages :messages="chat.messages" :status="chat.status">
    <template #content="{ message }">{{ message.content }}</template>
  </UChatMessages>
  <UChatPrompt v-model="input" @submit="chat.sendMessage({ text: input })">
    <UChatPromptSubmit :status="chat.status" />
  </UChatPrompt>
</template>
Details: Load
references/chat-components.md
for AI SDK integration, streaming, error handling

专为AI聊天机器人打造,支持AI SDK v5:
  • ChatMessage - 包含图标、头像、操作按钮的单条消息组件
  • ChatMessages - 带自动滚动、状态指示器的消息列表
  • ChatPalette - 浮层内的聊天界面
  • ChatPrompt - 增强型AI提示文本框
  • ChatPromptSubmit - 带状态处理的提交按钮
vue
<script setup>
import { Chat } from '@ai-sdk/vue'
const chat = new Chat({ api: '/api/chat' })
</script>

<template>
  <UChatMessages :messages="chat.messages" :status="chat.status">
    <template #content="{ message }">{{ message.content }}</template>
  </UChatMessages>
  <UChatPrompt v-model="input" @submit="chat.sendMessage({ text: input })">
    <UChatPromptSubmit :status="chat.status" />
  </UChatPrompt>
</template>
详情: 加载
references/chat-components.md
获取AI SDK集成、流式传输、错误处理相关内容

Editor (6 components) - NEW

编辑器(6个组件)- 新增

Rich text editing with TipTap:
  • Editor - TipTap-based editor with markdown/HTML/JSON support
  • EditorToolbar - Fixed, bubble, or floating toolbar
  • EditorDragHandle - Drag handle for reordering blocks
  • EditorMentionMenu - @ mention suggestions
  • EditorEmojiMenu - : emoji picker
  • EditorSuggestionMenu - / command menu
vue
<template>
  <UEditor v-model="content" :extensions="extensions">
    <template #toolbar>
      <UEditorToolbar />
    </template>
  </UEditor>
</template>
Details: Load
references/editor-components.md
for TipTap setup, extensions, toolbar customization

基于TipTap的富文本编辑组件:
  • Editor - 基于TipTap的编辑器,支持markdown/HTML/JSON
  • EditorToolbar - 固定、气泡或浮动工具栏
  • EditorDragHandle - 用于重新排序块的拖动手柄
  • EditorMentionMenu - @提及建议菜单
  • EditorEmojiMenu - 表情符号选择器
  • EditorSuggestionMenu - /命令菜单
vue
<template>
  <UEditor v-model="content" :extensions="extensions">
    <template #toolbar>
      <UEditorToolbar />
    </template>
  </UEditor>
</template>
详情: 加载
references/editor-components.md
获取TipTap设置、扩展、工具栏定制相关内容

Page Layout (16 components) - NEW

页面布局(16个组件)- 新增

Landing pages and content layouts:
  • Page - Grid layout with left/right columns
  • PageHeader - Responsive page header
  • PageHero - Hero section with title, description, CTAs
  • PageSection - Content section container
  • PageGrid - Responsive grid system
  • PageColumns - Multi-column layout
  • PageFeature - Feature showcase component
  • PageCTA - Call-to-action section
  • PageCard - Pre-styled card with title, description, link
  • PageList - Vertical list layout
  • PageLogos - Logo showcase
  • PageAnchors - Anchor link list
  • PageAside - Sticky sidebar
  • PageBody - Main content area
  • PageLinks - Link list
vue
<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>
Details: Load
references/page-layout-components.md
for landing page patterns

着陆页和内容布局组件:
  • Page - 带左右列的网格布局
  • PageHeader - 响应式页面页眉
  • PageHero - 包含标题、描述、CTA的英雄区
  • PageSection - 内容区域容器
  • PageGrid - 响应式网格系统
  • PageColumns - 多列布局
  • PageFeature - 功能展示组件
  • PageCTA - 行动召唤区域
  • PageCard - 预样式化卡片,包含标题、描述、链接
  • PageList - 垂直列表布局
  • PageLogos - Logo展示组件
  • PageAnchors - 锚点链接列表
  • PageAside - 粘性侧边栏
  • PageBody - 主内容区域
  • PageLinks - 链接列表
vue
<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
获取着陆页模式

Content (7 components) - NEW

内容(7个组件)- 新增

Documentation and blog content:
  • BlogPost - Article display component
  • BlogPosts - Blog grid layout
  • ChangelogVersion - Version entry display
  • ChangelogVersions - Changelog timeline
  • ContentNavigation - Accordion-style nav for docs
  • ContentSearch - Documentation search CommandPalette
  • ContentSearchButton - Button to open search
  • ContentSurround - Prev/next navigation
  • ContentToc - Sticky table of contents
vue
<template>
  <UBlogPosts>
    <UBlogPost v-for="post in posts" v-bind="post" />
  </UBlogPosts>
</template>
Details: Load
references/content-components.md
for blog and documentation patterns

文档和博客内容组件:
  • BlogPost - 文章展示组件
  • BlogPosts - 博客网格布局
  • ChangelogVersion - 版本条目展示
  • ChangelogVersions - 更新日志时间线
  • ContentNavigation - 文档用手风琴式导航
  • ContentSearch - 文档搜索命令面板
  • ContentSearchButton - 打开搜索的按钮
  • ContentSurround - 上一页/下一页导航
  • ContentToc - 粘性目录
vue
<template>
  <UBlogPosts>
    <UBlogPost v-for="post in posts" v-bind="post" />
  </UBlogPosts>
</template>
详情: 加载
references/content-components.md
获取博客和文档模式

Pricing (3 components) - NEW

定价(3个组件)- 新增

SaaS pricing pages:
  • PricingPlan - Individual plan card
  • PricingPlans - Responsive plan grid
  • PricingTable - Feature comparison table
vue
<template>
  <UPricingPlans>
    <UPricingPlan
      v-for="plan in plans"
      :title="plan.title"
      :price="plan.price"
      :features="plan.features"
    />
  </UPricingPlans>
</template>
Details: Load
references/pricing-components.md
for pricing page patterns

SaaS定价页面组件:
  • PricingPlan - 单个计划卡片
  • PricingPlans - 响应式计划网格
  • PricingTable - 功能对比表格
vue
<template>
  <UPricingPlans>
    <UPricingPlan
      v-for="plan in plans"
      :title="plan.title"
      :price="plan.price"
      :features="plan.features"
    />
  </UPricingPlans>
</template>
详情: 加载
references/pricing-components.md
获取定价页面模式

Forms (20 components)

表单(20个组件)

Input, InputDate, InputTime, InputNumber, InputTags, InputMenu, Select, SelectMenu, Textarea, Checkbox, CheckboxGroup, RadioGroup, Switch, Slider, Calendar, ColorPicker, PinInput, Form, FormField, FileUpload, AuthForm
vue
<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>
Details: Load
references/form-components-reference.md
for validation, nested forms, file uploads

Input、InputDate、InputTime、InputNumber、InputTags、InputMenu、Select、SelectMenu、Textarea、Checkbox、CheckboxGroup、RadioGroup、Switch、Slider、Calendar、ColorPicker、PinInput、Form、FormField、FileUpload、AuthForm
vue
<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
获取验证、嵌套表单、文件上传相关内容

Navigation (8 components)

导航(8个组件)

Tabs, Breadcrumb, Link, Pagination, CommandPalette, NavigationMenu, Stepper, Tree
vue
<UTabs v-model="tab" :items="items" />
<UCommandPalette :groups="groups" placeholder="Search..." />
<UStepper v-model="step" :items="steps" />
Details: Load
references/navigation-components-reference.md
for patterns

Tabs、Breadcrumb、Link、Pagination、CommandPalette、NavigationMenu、Stepper、Tree
vue
<UTabs v-model="tab" :items="items" />
<UCommandPalette :groups="groups" placeholder="Search..." />
<UStepper v-model="step" :items="steps" />
详情: 加载
references/navigation-components-reference.md
获取相关模式

Overlays (8 components)

浮层(8个组件)

Modal, Drawer, Slideover, Dialog, Popover, DropdownMenu, ContextMenu, Tooltip
vue
<UModal v-model="isOpen"><UCard>Content</UCard></UModal>
<UDrawer v-model="isOpen" side="right">...</UDrawer>
Details: Load
references/overlay-decision-guide.md
for when to use each

Modal、Drawer、Slideover、Dialog、Popover、DropdownMenu、ContextMenu、Tooltip
vue
<UModal v-model="isOpen"><UCard>Content</UCard></UModal>
<UDrawer v-model="isOpen" side="right">...</UDrawer>
详情: 加载
references/overlay-decision-guide.md
了解各组件的适用场景

Feedback (7 components)

反馈(7个组件)

Alert, Toast, Progress, Skeleton, Empty, Error, Banner
vue
<UAlert color="warning" title="Warning message" />
<UEmpty icon="i-heroicons-inbox" title="No items" />
<UBanner title="Important announcement" />
Details: Load
references/feedback-components-reference.md

Alert、Toast、Progress、Skeleton、Empty、Error、Banner
vue
<UAlert color="warning" title="Warning message" />
<UEmpty icon="i-heroicons-inbox" title="No items" />
<UBanner title="Important announcement" />
详情: 加载
references/feedback-components-reference.md

Layout (6 components)

布局(6个组件)

Card, Container, Main, Header, Footer, FooterColumns, Separator

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

Data (2 components)

数据(2个组件)

Table (with virtualization), ScrollArea

Table(带虚拟化)、ScrollArea

General (15 components)

通用(15个组件)

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

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

Color Mode (6 components)

颜色模式(6个组件)

ColorModeAvatar, ColorModeButton, ColorModeImage, ColorModeSelect, ColorModeSwitch, LocaleSelect

ColorModeAvatar、ColorModeButton、ColorModeImage、ColorModeSelect、ColorModeSwitch、LocaleSelect

Composables

Composables

Core:
useToast
,
useOverlay
,
useColorMode
,
useFormField
Utilities:
defineShortcuts
,
defineLocale
,
extendLocale
,
extractShortcuts
typescript
const { add } = useToast()
add({ title: 'Success', color: 'success' })

defineShortcuts({ 'meta_k': () => openSearch() })
Details: Load
references/composables-guide.md

核心:
useToast
,
useOverlay
,
useColorMode
,
useFormField
工具类:
defineShortcuts
,
defineLocale
,
extendLocale
,
extractShortcuts
typescript
const { add } = useToast()
add({ title: 'Success', color: 'success' })

defineShortcuts({ 'meta_k': () => openSearch() })
详情: 加载
references/composables-guide.md

Common Errors (Top 5)

常见错误(前5个)

1. Missing UApp Wrapper → Wrap app with
<UApp>
2. CSS Import Order
@import "tailwindcss"
FIRST, then
@import "@nuxt/ui"
3. Template Refs (v4.2+) → Use
ref.value?.focus()
not
ref.value.$el.focus()
4. Module Not Found → Add
'@nuxt/ui'
to
modules
in nuxt.config.ts 5. Dark Mode Not Working → Set
ui: { colorMode: true }
in nuxt.config.ts
Full list: Load
references/COMMON_ERRORS_DETAILED.md
for 25+ error solutions

1. 缺少UApp包装器 → 用
<UApp>
包裹应用 2. CSS导入顺序错误 → 先导入
@import "tailwindcss"
,再导入
@import "@nuxt/ui"
3. 模板引用(v4.2+) → 使用
ref.value?.focus()
而非
ref.value.$el.focus()
4. 模块未找到 → 在nuxt.config.ts的
modules
中添加
'@nuxt/ui'
5. 深色模式不生效 → 在nuxt.config.ts中设置
ui: { colorMode: true }
完整列表: 加载
references/COMMON_ERRORS_DETAILED.md
获取25+个错误的解决方案

When to Load References

何时加载参考文档

Dashboard/Admin:
dashboard-components.md
AI Chat:
chat-components.md
,
ai-sdk-v5-integration.md
Rich Text:
editor-components.md
Landing Pages:
page-layout-components.md
Pricing/SaaS:
pricing-components.md
Blog/Docs:
content-components.md
Forms:
form-components-reference.md
,
form-validation-patterns.md
Theming:
semantic-color-system.md
,
component-theming-guide.md
Troubleshooting:
COMMON_ERRORS_DETAILED.md

仪表板/管理后台:
dashboard-components.md
AI聊天:
chat-components.md
,
ai-sdk-v5-integration.md
富文本编辑:
editor-components.md
着陆页:
page-layout-components.md
定价/SaaS:
pricing-components.md
博客/文档:
content-components.md
表单:
form-components-reference.md
,
form-validation-patterns.md
主题定制:
semantic-color-system.md
,
component-theming-guide.md
故障排查:
COMMON_ERRORS_DETAILED.md

Available Commands

可用命令

  • /nuxt-ui-v4:setup
    - Initialize Nuxt UI in project
  • /nuxt-ui:migrate
    - Migrate from v2/v3 to v4
  • /nuxt-ui:theme
    - Generate theme configuration
  • /nuxt-ui:component
    - Scaffold component with Nuxt UI patterns
  • /nuxt-ui-v4:setup
    - 在项目中初始化Nuxt UI
  • /nuxt-ui:migrate
    - 从v2/v3迁移到v4
  • /nuxt-ui:theme
    - 生成主题配置
  • /nuxt-ui:component
    - 基于Nuxt UI模式搭建组件

Available Agents

可用Agent

  • nuxt-ui-component-selector - Recommends best components for use cases
  • nuxt-ui-migration-assistant - Guides v2/v3 → v4 migration
  • nuxt-ui-troubleshooter - Diagnoses and fixes common issues
  • nuxt-ui-component-selector - 根据使用场景推荐最佳组件
  • nuxt-ui-migration-assistant - 指导从v2/v3迁移到v4
  • nuxt-ui-troubleshooter - 诊断并修复常见问题

MCP Integration

MCP集成

This plugin includes the official Nuxt UI MCP server (
https://ui.nuxt.com/mcp
) providing:
  • Component listing and metadata
  • Documentation access
  • Migration guides
  • Template discovery
该插件包含官方Nuxt UI MCP服务器(
https://ui.nuxt.com/mcp
),提供以下功能:
  • 组件列表和元数据
  • 文档访问
  • 迁移指南
  • 模板发现