Installationen

Erfahren Sie, wie Sie Nuxt UI in Ihrer Vue-Anwendung installieren und konfigurieren, die sowohl mit Plain Vite als auch mit Inertia kompatibel ist.

setup (englisch)

Zu einem Vue-Projekt hinzufügen

Installieren Sie das Nuxt-UI-Paket

pnpm add @nuxt/ui tailwindcss

Add the Nuxt UI Vite plugin in your vite.config.ts Füge das Nuxt UI Vite Plugin in deinem vite.config.ts hinzu

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

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})
Nuxt UI registriert unplugin-auto-import und unplugin-vue-components, die auto-imports.d.ts und components.d.ts Typdeklarationsdateien generieren.
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
Diese Deklarationsdateien werden nur geschrieben, wenn Vite ausgeführt wird. Das Standardskript create-vuebuild führt vue-tsc parallel zu vite build (run-p type-check "build-only {@}") aus, so dass bei einem sauberen Checkout die Typprüfung beginnen kann, bevor die Dateien vorhanden sind, und mit Fehlern wie Cannot find name 'useToast' fehlschlägt.
package.json
{
  "scripts": {
    "build": "run-s build-only type-check"
  }
}
Wenn Sie TypeScript verwenden, fügen Sie diese Aliase Ihren tsconfig-Dateien hinzu, um die automatische Vervollständigung in Ihrem vite.config.ts zu aktivieren.
tsconfig.node.json
{
  "compilerOptions": {
    "paths": {
      "#build/ui": [
        "./node_modules/.nuxt-ui/ui"
      ]
    }
  }
}
tsconfig.app.json
{
  "compilerOptions": {
    "paths": {
      "#build/ui/*": [
        "./node_modules/.nuxt-ui/ui/*"
      ]
    }
  }
}

Verwenden Sie das Nuxt UI Vue-Plugin

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')

Importieren Sie Tailwind CSS und Nuxt UI in Ihrem CSS

@import "tailwindcss";
@import "@nuxt/ui";
Importieren Sie die CSS-Datei in Ihren Entrypoint.
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')
Es wird empfohlen, die Tailwind CSS IntelliSense Erweiterung für VSCode zu installieren und die folgenden Einstellungen hinzuzufügen:
.vscode/settings.json
{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "ui"],
  "tailwindCSS.classFunctions": ["defineAppConfig"]
}

Wickeln Sie Ihre App mit App-Komponente

<template>
  <UApp>
    <RouterView />
  </UApp>
</template>
Die App-Komponente richtet die globale Konfiguration ein und wird für Toast, Tooltip und programmatic overlays benötigt.

Fügen Sie die isolate-Klasse zu Ihrem Root-Container hinzu

<!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>
Dadurch wird sichergestellt, dass Stile auf Ihre App abgestimmt sind, und Probleme mit Overlays und Stapelkontexten werden vermieden.

Vue Template verwenden

Beginnen Sie mit einem unserer official templates, indem Sie die Use this template-Schaltfläche auf GitHub oder in der CLI verwenden:

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

Starter

Eine minimale Vorlage, um mit der Nuxt UI zu beginnen.

Dashboard

Eine Dashboard-Vorlage mit mehrspaltigem Layout zum Erstellen anspruchsvoller Admin-Oberflächen.

Chat

Eine KI-Chatbot-Vorlage zum Erstellen eines eigenen Chatbot mit Vercel AI SDK.

Starter Adonis

Ein minimales Nuxt UI-Template für AdonisJS mit Inertia.js.

Starter Laravel

Eine minimale Nuxt UI-Vorlage für Laravel mit Inertia.js.

Options (englisch)

Sie können die Nuxt-Benutzeroberfläche anpassen, indem Sie Optionen in Ihrem vite.config.ts bereitstellen.

prefix nicht

Verwenden Sie die Option prefix, um das Präfix der Komponenten zu ändern.

  • Standard: 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 nicht

Verwenden Sie die Option ui, um die Konfiguration für die Nuxt-Benutzeroberfläche bereitzustellen. Dies ist das Vue-Äquivalent des ui-Schlüssels in Nuxts app.config.ts.

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 nicht

Verwenden Sie die Option dts, um die Erzeugung von Deklarationsdateien für automatisch importierte Komponenten und Compositables zu aktivieren oder zu deaktivieren.

  • Default: 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
    })
  ]
})

xicon

Verwenden Sie die icon-Option, um Standard-Requisiten für die Komponente Icon (size, mode, customize) festzulegen und die Bündelung von Build-Time-Icons über clientBundle zu konfigurieren.

  • Standard: {}
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
        }
      }
    })
  ]
})
Weitere Informationen zu Icon-Sammlungen und Client-Bündelung finden Sie in der Dokumentation Icons.

colorMode nicht

Verwenden Sie die colorMode-Option, um die Farbmodusintegration von @vueuse/core zu aktivieren oder zu deaktivieren.

  • Standard: 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 nicht

Verwenden Sie die Option theme.colors, um die dynamischen Farbaliase zu definieren, die zum Generieren des Komponentendesigns verwendet werden.

  • Standard: ['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']
      }
    })
  ]
})
Jeder Alias generiert einen vollständigen Satz von --ui-color-*-Schattierungen und-Varianten in den Komponententhemen mit Farbvarianten, unabhängig davon, ob Ihre App sie verwendet oder nicht. Trimmen Sie die Liste auf die tatsächlich verwendeten Aliase und behalten Sie error bei, wenn Sie Formulare verwenden, da Validierungsstile darauf angewiesen sind.
Erfahren Sie mehr über die Farbanpassung und das Thema im Themenbereich.

theme.transitions (nicht)

Verwenden Sie die theme.transitions-Option, um Übergänge auf Komponenten zu aktivieren oder zu deaktivieren.

  • Standard: 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
      }
    })
  ]
})
Diese Option fügt die transition-colors-Klasse für Komponenten mit hover-oder aktiven Zuständen hinzu.

theme.unstyled: badge{label="4.9+" class="align-text-top"} (englisch)

Verwenden Sie die Option theme.unstyled, um alle Standardthemenklassen aus Komponenten zu entfernen und nur deren Struktur und die Klassen beizubehalten, die Sie über class, ui oder app.config.ui bereitstellen.

  • Default: 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
      }
    })
  ]
})
Dies entfernt auch structural-Klassen (Positionierung, Übergänge, Flex/Grid), nicht nur kosmetische. Layout-schwere Komponenten wie Modal, Drawer oder Calendar müssen Sie ihr Layout neu liefern, ähnlich wie im unstyled mode von PrimeVue.

theme.defaultVariants (englisch)

Verwenden Sie die Option theme.defaultVariants, um die Standardvarianten color und size für Komponenten außer Kraft zu setzen.

Nur Standardwerte, die genau primary oder md sind, werden ersetzt, sodass Avatar color: 'neutral' und Separator size: 'xs' behält.

  • Standard: { 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"} (Deutsche Übersetzung)

Verwenden Sie die Option theme.prefix, um das gleiche Präfix zu konfigurieren, das Sie beim Tailwind CSS-Import festgelegt haben. Dadurch wird sichergestellt, dass die Nuxt-UI-Komponenten die richtigen vordefinierten Hilfsklassen und CSS-Variablen verwenden.

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'
      }
    })
  ]
})

Dadurch werden automatisch alle Tailwind-Utility-Klassen und CSS-Variablen in Nuxt UI-Komponententhemen vorangestellt:

<!-- 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>
Weitere Informationen zur Verwendung eines Präfixes finden Sie in der Tailwind CSS-Dokumentation.

prose nicht

Verwenden Sie die prose-Option, um die Nuxt-Benutzeroberfläche Prose components und ihr Design zu aktivieren.

  • Standard: 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 (englisch)

Verwenden Sie die autoImport-Option, um den automatischen Import von Composable zu deaktivieren oder die unplugin-auto-import-Optionen anzupassen.

  • Standard: {}
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
    })
  ]
})
Wenn diese Option deaktiviert ist, können Sie Compositables weiterhin explizit aus @nuxt/ui/composables importieren.

xcomponents

Verwenden Sie die components-Option, um den automatischen Import von Komponenten zu deaktivieren oder die unplugin-vue-components-Optionen anzupassen.

  • Standard: {}
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
    })
  ]
})
Wenn deaktiviert, können Sie weiterhin Komponenten explizit importieren, z. B. import Button from '@nuxt/ui/components/Button.vue' oder import ProseCode from '@nuxt/ui/components/prose/Code.vue'.

router: badge{label="4.3+" class="align-text-top"} (Deutsche Übersetzung)

Dies ist nützlich für Anwendungen, die vue-router nicht verwenden, z. B. Electron-Apps, MPAs oder Frameworks wie Inertia.js oder [Hybridly](https://hybridly.dev/xph75x.

  • Standard: true
WertDescription
true nichtVerwendet vue-router für die Navigation mit der RouterLink-Komponente.
false ÜbersetzungDeaktiviert Routing-Integration, Links werden als einfache <a>-Tags gerendert.
'inertia' ÜbersetzungVerwendet Inertia.js für die Navigation mit seiner Link Komponente.
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
    })
  ]
})
Sie können benutzerdefinierte Navigationslogik für Frameworks wie Hybridly bereitstellen, indem Sie router: false in der Vite Config festlegen und bei der Installation des Vue-Plugins eine Funktion übergeben:
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 })
  }
})
Wenn false oder 'inertia' eingestellt ist, ist vue-router nicht als Abhängigkeit erforderlich.

scanPackages: badge{label="4.3+" class="align-text-top"} (englisch)

Verwenden Sie die Option scanPackages, um zusätzliche npm-Pakete anzugeben, die mithilfe der Nuxt-Benutzeroberfläche nach Komponenten durchsucht werden sollen.

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']
    })
  ]
})
Standardmäßig wird nur @nuxt/ui gescannt. Verwenden Sie diese Option, wenn Ihre externen Pakete Vue-Komponenten enthalten, die Nuxt-Benutzeroberfläche verwenden.

root: badge{label="4.9+" class="align-text-top"} (englisch)

Verwenden Sie die root-Option, um das Verzeichnis zu überschreiben, in dem Nuxt UI sein .nuxt-ui-Verzeichnis generiert Standardmäßig verwendet es Vite's root, aber in Setups wie electron-vite zeigt der Renderer root auf ein Unterverzeichnis.(z.B. src/renderer), so dass die Vorlagen in src/renderer/node_modules/.nuxt-ui landen, wo Tailwind sie nicht scannt, was dazu führt, dass Theme-Klassen wie bg-default, ring-default und divide-default fehlen.

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
      })
    ]
  }
})
Zeigen Sie root auf Ihren Projektstamm, damit das generierte .nuxt-ui-Verzeichnis in einem node_modules endet, das Tailwind scannt.

experimental.componentDetection: badge{label="4.11+" class="align-text-top"} (englisch)

Verwenden Sie die Option experimental.componentDetection, um die automatische Komponentenerkennung für Baumschütteln zu aktivieren. Diese Funktion scannt Ihren Quellcode, um zu erkennen, welche Komponenten tatsächlich verwendet werden, und generiert nur das erforderliche CSS für diese Komponenten.(einschließlich ihrer Abhängigkeiten). Ohne sie, die Vite Plugin generiert das Thema CSS für jede Komponente. Detection deckt die Vite Wurzel, die Pakete, die in scanPackages aufgeführt sind, und jedes dirs von der components Option, die sich außerhalb des Root befindet.

  • Standard: false
  • Type: boolean | string[] (englisch)

**Automatische Erkennung aktivieren: **

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
      }
    })
  ]
})

**Fügen Sie zusätzliche Komponenten für die dynamische Verwendung hinzu: **

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']
      }
    })
  ]
})
Wenn Sie ein Array von Komponentennamen bereitstellen, wird die automatische Erkennung aktiviert und diese Komponenten (zusammen mit ihren Abhängigkeiten) werden garantiert einbezogen. Dies ist nützlich für dynamische Komponenten wie <component :is="..." />, die nicht statisch analysiert werden können.
Neu verwendete Komponenten werden beim nächsten Start des Dev-Servers aufgenommen. Wenn Sie eine Komponente hinzufügen und deren Stile fehlen, starten Sie den Dev-Server neu.

Continuous Releases veröffentlicht

Die Benutzeroberfläche von Nuxt verwendet pkg.pr.new für kontinuierliche Vorschauversionen und bietet Entwicklern sofortigen Zugriff auf die neuesten Funktionen und Fehlerbehebungen, ohne auf offizielle Veröffentlichungen warten zu müssen.

Automatische Vorschau-Releases werden für alle Commits und PRs im v4-Branch erstellt. Verwenden Sie sie, indem Sie Ihre Paketversion durch den spezifischen Commit-Hash oder die PR-Nummer ersetzen.

package.json
{
  "dependencies": {
-   "@nuxt/ui": "^4.0.0",
+   "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@4c96909",
  }
}
pkg.pr.new kommentiert PRs automatisch mit der Installations-URL, so dass Änderungen einfach getestet werden können.