安装

模板
了解如何在 Nuxt 应用中安装和配置 Nuxt UI。

设置

添加到 Nuxt 项目

安装 Nuxt UI 包

pnpm add @nuxt/ui tailwindcss

在你的 nuxt.config.ts 中添加 Nuxt UI 模块

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})
无需在 modules 数组中添加 @nuxt/icon、@nuxt/fonts 或 @nuxtjs/color-mode，因为 Nuxt UI 会自动注册它们。你仍然可以通过 icon、fonts 和 colorMode 键在 nuxt.config.ts 中配置这些模块。

在 CSS 中引入 Tailwind CSS 和 Nuxt UI

@import "tailwindcss";
@import "@nuxt/ui";
当使用 Nuxt Layers 时，该模块会自动为每个层目录生成 @source 指令，确保 Tailwind CSS 扫描所有层源文件中的工具类。
建议为 VSCode 安装 Tailwind CSS IntelliSense 扩展并添加以下设置
.vscode/settings.json
{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "ui"],
  "tailwindCSS.classFunctions": ["defineAppConfig"]
}

用 App 组件包裹您的应用程序

app.vue
<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>
App 组件提供全局配置，是 Toast、Tooltip 组件以及编程式覆盖层 (Programmatic Overlays) 正常工作所必需的。

使用 Nuxt 模板

通过 GitHub 上的 Use this template 按钮或使用 CLI，通过我们的官方模板开始你的项目

npm create nuxt@latest -- -t ui

启动器

一个用于开始使用 Nuxt UI 的最小模板。

着陆页

由 Nuxt Content 驱动的现代着陆页模板。

文档

由 Nuxt Content 驱动的文档模板。

SaaS

包含着陆页、定价、文档和博客的 SaaS 模板，由 Nuxt Content 驱动。

Dashboard

一个带有多列布局的仪表板模板，用于构建复杂的管理界面。

聊天

一个 AI 聊天机器人模板，用于构建您自己的聊天机器人，由 Vercel AI SDK 驱动。

作品集

一个精美的作品集模板，用于展示你的作品、技能和博客，由 Nuxt Content 驱动。

更新日志

一个变更日志模板，用于显示 GitHub 仓库的发布说明，由 Nuxt MDC 驱动。

编辑器

由 TipTap 驱动的富文本编辑器模板，支持 Markdown、HTML 和 JSON 内容类型。

选项

你可以在 nuxt.config.ts 中提供选项来定制 Nuxt UI。

prefix

使用 prefix 选项更改组件的前缀。

  • 默认值： U
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prefix: 'Nuxt'
  }
})

fonts

使用 fonts 选项来启用或禁用 @nuxt/fonts 模块。

  • 默认值： true
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    fonts: false
  }
})

colorMode

使用 colorMode 选项来启用或禁用 @nuxt/color-mode 模块。

  • 默认值： true
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    colorMode: false
  }
})

theme.colors

使用 theme.colors 选项定义用于生成组件主题的动态颜色别名。

  • 默认值： ['primary', 'secondary', 'success', 'info', 'warning', 'error']
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      colors: ['primary', 'error']
    }
  }
})
在主题部分了解更多关于颜色定制和主题的信息。

theme.transitions

使用 theme.transitions 选项启用或禁用组件上的过渡。

  • 默认值： true
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      transitions: false
    }
  }
})
此选项会在具有悬停或激活状态的组件上添加 transition-colors 类。

theme.defaultVariants

使用 theme.defaultVariants 选项来覆盖组件的默认 color 和 size 变体。

  • 默认值： { color: 'primary', size: 'md' }
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      defaultVariants: {
        color: 'neutral',
        size: 'sm'
      }
    }
  }
})

theme.prefix 4.2+

使用 theme.prefix 选项来配置与 Tailwind CSS 引入时设置相同的的前缀。这可确保 Nuxt UI 组件使用正确的前缀工具类和 CSS 变量。

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
若要配合 @nuxt/fonts 模块使用 prefix 选项，可能需要启用 fonts.processCSSVariables。
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  },
  fonts: {
    processCSSVariables: true
  }
})

这将自动为 Nuxt UI 组件主题中的所有 Tailwind 工具类和 CSS 变量添加前缀。

<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
在 Tailwind CSS 文档中了解更多关于使用前缀的信息。

prose

使用 prose 选项强制引入 Nuxt UI Prose 组件，即使未安装 @nuxtjs/mdc 或 @nuxt/content。

  • 默认值： false
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prose: true
  }
})

mdc 已弃用

使用prose请使用对应的选项。

内容

使用 content 选项强制引入 Nuxt UI <Prose> 和 <UContent> 组件，即使未安装 @nuxt/content。

  • 默认值： false
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    content: true
  }
})

experimental.componentDetection 4.1+

使用 experimental.componentDetection 选项来启用用于 Tree-shaking 的自动组件检测。此功能会扫描你的源代码以检测实际使用的组件，并仅为这些组件（包括其依赖项）生成必要的 CSS。

  • 默认值： false
  • 类型： boolean | string[]

启用自动检测

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

包含用于动态使用的额外组件

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: ['Modal', 'Dropdown', 'Popover']
    }
  }
})
当提供组件名称数组时，会自动启用检测，并保证这些组件（及其依赖项）被包含在内。这对于像 <component :is="..." /> 这样无法进行静态分析的动态组件非常有用。

持续发布

Nuxt UI 使用 pkg.pr.new 进行持续预览发布，使开发者无需等待官方发布即可即时访问最新功能和错误修复。

针对 v4 分支的所有提交和 PR 都会创建自动预览版本。通过使用特定的提交哈希或 PR 编号替换包版本即可使用它们。

package.json
{
  "dependencies": {
-   "@nuxt/ui": "^4.0.0",
+   "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@4c96909",
  }
}
pkg.pr.new 将自动在 PR 上评论安装 URL，方便测试更改。

介绍

迁移