安装

模板
了解如何在Vue应用程序中安装和配置Nuxt UI，兼容普通Vite和Inertia。

设置

添加到Vue项目

安装Nuxt UI包

pnpm add @nuxt/ui tailwindcss

在您的vite.config.ts中添加Nuxt UI Vite插件

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})
Nuxt UI注册unplugin-auto-import和unplugin-vue-components，这将生成auto-imports.d.ts和components.d.ts类型声明文件。您可能希望gitignore这些文件，并将其添加到tsconfig中。
tsconfig.app.json
{
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
}
.gitignore
# Auto-generated type declarations
auto-imports.d.ts
components.d.ts
这些声明文件仅在Vite运行时写入。默认的create-vuebuild脚本并行运行vue-tsc和vite build（run-p type-check "build-only {@}"），因此在干净的检出中，类型检查可能会在文件存在之前启动，并因错误（如Cannot find name 'useToast'）而失败。请在构建后运行类型检查，以便首先生成声明。
package.json
{
  "scripts": {
    "build": "run-s build-only type-check"
  }
}
在内部，Nuxt UI依赖自定义别名来解析主题类型。如果您使用TypeScript，请将这些别名添加到tsconfig文件中，以在vite.config.ts中启用自动完成。
tsconfig.node.json
{
  "compilerOptions": {
    "paths": {
      "#build/ui": [
        "./node_modules/.nuxt-ui/ui"
      ]
    }
  }
}
tsconfig.app.json
{
  "compilerOptions": {
    "paths": {
      "#build/ui/*": [
        "./node_modules/.nuxt-ui/ui/*"
      ]
    }
  }
}

使用Nuxt UI Vue插件

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')

在CSS中导入Tailwind CSS和Nuxt UI

@import "tailwindcss";
@import "@nuxt/ui";
在你的入口点导入CSS文件。
import './assets/css/main.css'

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')
建议为VSCode安装[Tailwind CSS IntelliSenseph282xhttps://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)扩展，并添加以下设置：
.vscode/settings.json
{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "ui"],
  "tailwindCSS.classFunctions": ["defineAppConfig"]
}

使用App组件包装您的应用

<template>
  <UApp>
    <RouterView />
  </UApp>
</template>
App组件设置全局配置，Toast、Tooltip和编程覆盖需要该组件。

将isolate类添加到根容器

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nuxt UI</title>
  </head>
  <body>
    <div id="app" class="isolate"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
这可以确保样式适用于您的应用，并防止叠加和堆叠上下文出现问题。

使用Vue模板

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

npm create nuxt@latest -- --no-modules -t ui-vue

Starter

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

Dashboard

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

Chat

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

Starter Adonis

AdonisJS的最小Nuxt UI模板，使用Inertia.js。

Starter Laravel

Laravel的最小Nuxt UI模板，使用Inertia.js。

选项

您可以通过在vite.config.ts中提供选项来自定义Nuxt UI。

prefix

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

  • 默认值：U
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prefix: 'Nuxt'
    })
  ]
})

ui

使用ui选项为Nuxt UI提供配置。这是Nuxt的app.config.ts中ui键的Vue等效项。

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        colors: {
          primary: 'green',
          neutral: 'slate'
        }
      }
    })
  ]
})

dts

使用dts选项可以启用或禁用为自动导入的组件和可组合项生成声明文件。

  • 默认值：true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      dts: false
    })
  ]
})

icon

使用icon选项可以设置Icon组件（size，mode，customize）的默认属性，并通过clientBundle配置构建时图标绑定。在安装Nuxt UI自己的图标集时，默认情况下会启用图标绑定。将clientBundle: false设置为退出。

  • 默认值：{}
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      icon: {
        mode: 'svg',
        clientBundle: {
          scan: true
        }
      }
    })
  ]
})
在Icons文档中了解有关图标集合和客户端捆绑的更多信息。

colorMode

使用colorMode选项启用或禁用@vueuse/core的颜色模式集成。

  • 默认值：true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      colorMode: false
    })
  ]
})

theme.colors

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

  • 默认值：['primary', 'secondary', 'success', 'info', 'warning', 'error']
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        colors: ['primary', 'error']
      }
    })
  ]
})
每个别名都会在具有颜色变体的组件主题中生成一整套--ui-color-*阴影和变体，无论您的应用是否使用它。将列表修剪为您实际使用的别名，如果您使用表单，请保留error，因为验证样式依赖于它。
在“主题”部分了解有关颜色自定义和主题化的更多信息。

theme.transitions

使用theme.transitions选项启用或禁用组件上的转换。

  • 默认值：true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        transitions: false
      }
    })
  ]
})
此选项将transition-colors类添加到具有悬停或活动状态的组件上。

theme.unstyled：badge{label="4.9+" class="align-text-top"}

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

  • 默认值：false
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    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' }
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        defaultVariants: {
          color: 'neutral',
          size: 'sm'
        }
      }
    })
  ]
})

theme.prefix：badge{label="4.2+" class="align-text-top"}

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

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        prefix: 'tw'
      }
    })
  ]
})

这将自动为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组件及其主题。

  • 默认值：false
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prose: true
    })
  ]
})

autoImport

使用autoImport选项禁用可组合的自动导入或自定义unplugin-auto-import选项。

  • 默认值：{}
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      autoImport: false
    })
  ]
})
禁用时，您仍然可以从@nuxt/ui/composables显式导入组合。

components

使用components选项禁用组件自动导入或自定义unplugin-vue-components选项。

  • 默认值：{}
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      components: false
    })
  ]
})
禁用时，您仍然可以显式导入组件，例如import Button from '@nuxt/ui/components/Button.vue'或import ProseCode from '@nuxt/ui/components/prose/Code.vue'。

router：badge{label="4.3+" class="align-text-top"}

使用router选项配置路由集成。这对于不使用vue-router的应用程序非常有用，例如Electron应用程序、MPA或Inertia.js或Hybridly等框架。

  • 默认值：true
值描述
true使用vue-router和RouterLink组件进行导航。
false禁用路由集成，链接呈现为普通<a>标记。
'inertia'使用Inertia.js及其Link组件进行导航。
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      router: false
    })
  ]
})
你可以通过在Vite配置中设置router: false，并在安装Vue插件时传递一个函数，为Hybridly等框架提供自定义导航逻辑：
src/main.ts
import ui from '@nuxt/ui/vue-plugin'
import { router } from 'hybridly'

app.use(ui, {
  router: (event, { href, external }) => {
    if (external) {
      return
    }

    event.preventDefault()

    router.navigate({ url: href })
  }
})
当设置为false或'inertia'时，vue-router不需要作为依赖项。

scanPackages：badge{label="4.3+" class="align-text-top"}

使用scanPackages选项指定应使用Nuxt UI扫描组件的其他npm包。当您拥有内部使用Nuxt UI组件的共享组件库时，这很有用。

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      scanPackages: ['@my-org/ui-components']
    })
  ]
})
默认情况下，仅扫描@nuxt/ui。当您的外部包包含使用Nuxt UI的Vue组件时，请使用此选项。

root：badge{label="4.9+" class="align-text-top"}

使用root选项覆盖Nuxt UI生成其.nuxt-ui目录的目录（包含主题模板）。默认情况下，它使用Vite的root，但在electron-vite等设置中，渲染器的root指向子目录（例如src/renderer），因此模板在src/renderer/node_modules/.nuxt-ui中不会被Tailwind扫描，导致bg-default，ring-default和divide-default等主题类丢失。

electron.vite.config.ts
import { defineConfig } from 'electron-vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  renderer: {
    root: 'src/renderer',
    plugins: [
      vue(),
      ui({
        root: __dirname
      })
    ]
  }
})
将root指向您的项目根目录，这样生成的.nuxt-ui目录最终会出现在Tailwind扫描的node_modules目录中。

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

使用experimental.componentDetection选项启用自动组件检测以进行树抖动。此功能扫描您的源代码以检测实际使用的组件，并仅为这些组件生成必要的CSS（包括它们的依赖项）。如果没有它，Vite插件会为每个组件生成主题CSS。检测覆盖Vite根，在scanPackages中列出的软件包和位于根目录之外的components选项中的任何dirs。

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

启用自动检测：

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      experimental: {
        componentDetection: true
      }
    })
  ]
})

包含用于动态使用的附加组件：

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    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.