安装

模板
了解如何在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']
})
无需将@nuxt/icon、@nuxt/fonts或@nuxtjs/color-mode添加到modules阵列中，因为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和编程覆盖需要该组件。

使用Nuxt模板

使用GitHub上的Use this template按钮或CLI开始使用我们的官方模板：

npm create nuxt@latest -- -t ui

Starter

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

Landing

由Nuxt Content提供支持的现代着陆页模板。

Docs

由Nuxt Content提供支持的文档模板。

SaaS

一个SaaS模板，包含登陆、定价、文档和博客，由Nuxt Content提供支持。

Dashboard

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

Chat

一个AI聊天机器人模板，用于构建由Vercel AI SDK提供支持的聊天机器人。

Portfolio

一个时尚的投资组合模板，以展示您的工作，技能和博客由Nuxt内容供电。

Changelog

一个用于显示您的存储库的changelog模板，它来自由Comark提供支持的GitHub。

Editor

由TipTap提供支持的富文本编辑器模板，支持markdown，HTML和JSON内容类型。

Calendar

一个苹果日历模板与日，周和月的意见，拖放和乐观的更新。

选项

您可以通过在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']
    }
  }
})
每个别名都会在具有颜色变体的组件主题中生成一整套--ui-color-*阴影和变体，无论您的应用是否使用它。将列表修剪为您实际使用的别名，如果您使用表单，请保留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.unstyled：badge{label="4.9+" class="align-text-top"}

使用theme.unstyled选项从组件中删除所有默认主题类，只保留它们的结构和通过class、ui或app.config.ui提供的类。

  • 默认值：false
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      unstyled: true
    }
  }
})
这也剥离了structural类（定位，过渡，flex/grid），而不仅仅是装饰性的。像Modal，Drawer或Calendar这样的布局重的组件需要你重新提供它们的布局，类似于PrimeVue的无样式模式。

theme.defaultVariants

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

只有完全为primary或md的默认值才会被替换，因此Avatar保留color: 'neutral'，Separator保留size: 'xs'。

  • 默认值：{ 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：badge{label="4.2+" class="align-text-top"}

使用theme.prefix选项来配置您在Tailwind CSS导入中设置的相同前缀。这可以确保Nuxt UI组件使用正确的前缀实用程序类和CSS变量。

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
您可能需要启用fonts.processCSSVariables才能对@nuxt/fonts模块使用prefix选项：
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或@comark/nuxt。

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

mdc：badge{label="Deprecated" color="warning" class="align-text-top"}

请改用prose选项。

content

使用content选项强制导入Nuxt UI散文和内容组件，即使未安装@nuxt/content。

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

experimental.componentDetection：badge{label="4.1+" class="align-text-top"}

使用experimental.componentDetection选项启用自动组件检测以进行树抖动。此功能扫描您的源代码以检测实际使用的组件，并仅为这些组件（包括其依赖项）生成必要的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', 'DropdownMenu', '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会自动对带有安装URL的PR进行注释，从而可以轻松测试更改。

Introduction

Nuxt UI is a comprehensive Vue UI component library (Nuxt optional), offering 125+ accessible, Tailwind CSS components for building modern web applications.

Migration

A comprehensive guide to migrate your application from Nuxt UI v3 to Nuxt UI v4.