Installatie

Leer hoe u Nuxt UI installeert en configureert in uw Vue-applicatie, compatibel met zowel gewone Vite als Inertia.

Opstelling

Toevoegen aan een Vue-project

Installeer het Nuxt UI-pakket

pnpm add @nuxt/ui tailwindcss

yarn add @nuxt/ui tailwindcss

npm install @nuxt/ui tailwindcss

bun add @nuxt/ui tailwindcss

Voeg de Nuxt UI Vite plugin in uw `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()
  ]
})

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

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      refresh: true
    }),
    vue({
      template: {
        transformAssetUrls: {
          base: null,
          includeAbsolute: false
        }
      }
    }),
    ui({
      router: 'inertia'
    })
  ]
})

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

export default defineConfig({
  plugins: [
    adonisjs({
      entrypoints: ['inertia/app/app.ts'],
      reload: ['resources/views/**/*.edge']
    }),
    inertia(),
    vue(),
    ui({
      router: 'inertia'
    })
  ]
})

Nuxt UI registreert unplugin-auto-import en unplugin-vue-components, die auto-imports.d.ts en components.d.ts type declaratiebestanden zal genereren. U zult waarschijnlijk willen gitignore deze, en voeg ze toe aan uw 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

Deze declaratiebestanden worden alleen geschreven wanneer Vite wordt uitgevoerd. Het standaard create-vuebuild script draait vue-tsc parallel met vite build (run-p type-check "build-only {@}"), dus bij een schone checkout kan typecontrole beginnen voordat de bestanden bestaan en mislukt met fouten zoals Cannot find name 'useToast' . Voer in plaats daarvan de typecontrole uit na de build, zodat de verklaringen eerst worden gegenereerd.

package.json

{
  "scripts": {
    "build": "run-s build-only type-check"
  }
}

Intern vertrouwt Nuxt UI op aangepaste aliassen om de thematypen op te lossen. Als u TypeScript gebruikt, voegt u deze aliassen toe aan uw tsconfig-bestanden om automatische aanvulling in uw vite.config.ts mogelijk te maken.

tsconfig.node.json

{
  "compilerOptions": {
    "paths": {
      "#build/ui": [
        "./node_modules/.nuxt-ui/ui"
      ]
    }
  }
}

tsconfig.app.json

{
  "compilerOptions": {
    "paths": {
      "#build/ui/*": [
        "./node_modules/.nuxt-ui/ui/*"
      ]
    }
  }
}

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

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

Importeer Tailwind CSS en Nuxt UI in uw CSS

@import "tailwindcss";
@import "@nuxt/ui";

@import "tailwindcss";
@import "@nuxt/ui";

@import "tailwindcss";
@import "@nuxt/ui";

Importeer het CSS-bestand in uw 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')

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})

Het wordt aanbevolen om de Tailwind CSS IntelliSense extensie voor VSCode te installeren en de volgende instellingen toe te voegen:

.vscode/settings.json

{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "ui"],
  "tailwindCSS.classFunctions": ["defineAppConfig"]
}

Wikkel uw app met App-component

<template>
  <UApp>
    <RouterView />
  </UApp>
</template>

<template>
  <UApp>
    <!-- Your content goes here -->
  </UApp>
</template>

<template>
  <UApp>
    <!-- Your content goes here -->
  </UApp>
</template>

De App component stelt globale config in en is vereist voor Toast, Tooltip en programmatic overlays.

Voeg de klasse `isolate` toe aan uw rootcontainer

<!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>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead
    @vite('resources/js/app.ts')
  </head>
  <body>
    <div class="isolate">
        @inertia
    </div>
  </body>
</html>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead()
    @vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
  </head>
  <body>
    @inertia({ class: 'isolate' })
  </body>
</html>

Dit zorgt ervoor dat stijlen worden afgestemd op uw app en voorkomt problemen met overlays en stapelcontexten.

Een Vue-sjabloon gebruiken

Ga aan de slag met een van onze official templates met behulp van de Use this template knop op GitHub of de CLI:

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

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

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

Starter

Een minimale sjabloon om aan de slag te gaan met Nuxt UI.

Dashboard

Een dashboardsjabloon met lay-out met meerdere kolommen voor het bouwen van geavanceerde beheerdersinterfaces.

Chat

Een AI-chatbot-sjabloon om uw eigen chatbot te bouwen, mogelijk gemaakt door Vercel AI SDK.

Starter Adonis

Een minimale Nuxt UI-sjabloon voor AdonisJS met Inertia.js.

Starter Laravel

Een minimale Nuxt UI-sjabloon voor Laravel met Inertia.js.

Opties

U kunt Nuxt UI aanpassen door opties aan te bieden in uw vite.config.ts.

`prefix`

Gebruik de optie prefix om het voorvoegsel van de componenten te wijzigen.

Standaard: 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`

Gebruik de optie ui om configuratie voor Nuxt UI te bieden. Dit is het Vue-equivalent van de ui-sleutel in Nuxt 's 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`

Gebruik de optie dts om het genereren van declaratiebestanden voor automatisch geïmporteerde componenten en composables in of uit te schakelen.

Standaard: 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`

Gebruik de optie icon om standaard props in te stellen voor de Icon component (size, mode, customize) en om build-time pictogrambundeling via clientBundle te configureren. Bundelen van de eigen pictogrammen van Nuxt UI is standaard ingeschakeld wanneer hun verzameling is geïnstalleerd. Stel clientBundle: false in om af te zien.

Standaard: {}

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

Lees meer over pictogramverzamelingen en clientbundeling in de Icons-documentatie.

`colorMode`

Gebruik de optie colorMode om de integratie van de kleurmodus van @vueuse/core in of uit te schakelen.

Standaard: 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`

Gebruik de optie theme.colors om de dynamische kleuraliassen te definiëren die worden gebruikt om het componententhema te genereren.

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

Elke alias genereert een volledige set --ui-color-*-tinten en varianten in de componentthema 's met kleurvarianten, of uw app deze nu gebruikt of niet. Knip de lijst bij naar de aliassen die u daadwerkelijk gebruikt en bewaar error als u formulieren gebruikt, aangezien validatiestijlen erop vertrouwen.

Lees meer over kleuraanpassing en thema 's in de sectie Thema.

`theme.transitions`

Gebruik de optie theme.transitions om overgangen op componenten in of uit te schakelen.

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

Deze optie voegt de klasse transition-colors toe aan componenten met zweef- of actieve toestanden.

`theme.unstyled`: speelgoed{label="4.9+" class="align-text-top"}

Gebruik de optie theme.unstyled om alle standaard themaklassen uit componenten te verwijderen, waarbij alleen de structuur en de klassen die u via class, ui of app.config.ui aanbiedt behouden blijven.

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

Dit verwijdert ook structural klassen (positionering, overgangen, flex / grid), niet alleen cosmetische. Lay-out-zware componenten zoals Modal, Drawer of Calendar hebben je nodig om hun lay-out opnieuw te leveren, vergelijkbaar met de ongestyleerde modus van PrimeVue.

`theme.defaultVariants`

Gebruik de optie theme.defaultVariants om de standaard color- en size-varianten voor componenten te overschrijven.

Alleen defaults die exact primary of md zijn worden vervangen, dus Avatar houdt color: 'neutral' en Separator houdt size: 'xs'.

Standaard: { 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"}

Gebruik de optie theme.prefix om hetzelfde voorvoegsel te configureren dat u hebt ingesteld op uw Tailwind CSS-import. Dit zorgt ervoor dat Nuxt UI-componenten de juiste voorgeprogrammeerde hulpprogramma-klassen en CSS-variabelen gebruiken.

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

@import "tailwindcss" prefix(tw);
@import "@nuxt/ui";

Dit zal automatisch alle Tailwind-nutsklassen en CSS-variabelen in Nuxt UI-componentthema 's prefixeren:

<!-- 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>

Lees meer over het gebruik van een voorvoegsel in de Tailwind CSS-documentatie.

`prose`

Gebruik de optie prose om Nuxt UI Prose components en hun thema in te schakelen.

Standaard: 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`

Gebruik de optie autoImport om samenstelbare auto-import uit te schakelen of om unplugin-auto-import opties aan te passen.

Standaard: {}

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

Indien uitgeschakeld, kunt u compositiebestanden nog steeds expliciet importeren vanuit @nuxt/ui/composables.

`components`

Gebruik de optie components om automatisch importeren van componenten uit te schakelen of om unplugin-vue-components aan te passen.

Standaard: {}

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

Indien uitgeschakeld, kunt u nog steeds componenten expliciet importeren, bijv. import Button from '@nuxt/ui/components/Button.vue' of import ProseCode from '@nuxt/ui/components/prose/Code.vue'.

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

Gebruik de optie router om routeringsintegratie te configureren. Dit is handig voor toepassingen die geen vue-router gebruiken, zoals Electron-apps, MPA 's of frameworks zoals Inertia.js of Hybridly.

Standaard: true

Waarde	Omschrijving
`true`	Gebruikt `vue-router` voor navigatie met `RouterLink` component.
`false`	Schakelt routeringsintegratie uit, links worden weergegeven als gewone `<a>`-tags.
`'inertia'`	Gebruikt Inertia.js voor navigatie met zijn `Link`-component.

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

U kunt aangepaste navigatielogica bieden voor frameworks zoals Hybridly door router: false in te stellen in de Vite-configuratie en een functie door te geven bij het installeren van de Vue-plug-in:

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

Wanneer ingesteld op false of 'inertia', is vue-router niet vereist als afhankelijkheid.

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

Gebruik de optie scanPackages om extra npm-pakketten op te geven die moeten worden gescand op componenten met Nuxt UI. Dit is handig wanneer u een gedeelde componentenbibliotheek hebt die Nuxt UI gebruikt componenten intern.

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

Standaard wordt alleen @nuxt/ui gescand. Gebruik deze optie wanneer uw externe pakketten Vue-componenten bevatten die Nuxt UI gebruiken.

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

Gebruik de optie root om de map te overschrijven waar Nuxt UI zijn .nuxt-ui-map genereert (met de themasjablonen). Standaard gebruikt hij Vite 's root, maar in setups zoals electron-vite wijst de root van de renderer naar een sub-directory (b.v. src/renderer), dus de templates landen in src/renderer/node_modules/.nuxt-ui waar Tailwind niet scannen, waardoor themaklassen als bg-default, ring-default en divide-default ontbreken.

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

Richt root op je project root zodat de gegenereerde .nuxt-ui directory in een node_modules terechtkomt die Tailwind scant.

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

Gebruik de optie experimental.componentDetection om automatische componentdetectie in te schakelen voor het schudden van bomen. Deze functie scant uw broncode om te detecteren welke componenten daadwerkelijk worden gebruikt en genereert alleen de benodigde CSS voor die componenten (inclusief hun afhankelijkheden). Zonder dit genereert de Vite-plug-in het thema CSS voor elk onderdeel. Detectie omvat de Vite-root, de pakketten die worden vermeld in scanPackages en elke dirs van de components optie die zich buiten de root bevindt.

Standaard: false
Type: boolean | string[]

**Automatische detectie inschakelen: **

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

**Inclusief extra componenten voor dynamisch gebruik: **

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

Bij het verstrekken van een reeks componentnamen is automatische detectie ingeschakeld en worden deze componenten (samen met hun afhankelijkheden) gegarandeerd opgenomen. Dit is handig voor dynamische componenten zoals <component :is="..." /> die niet statisch kunnen worden geanalyseerd.

Nieuw gebruikte componenten worden opgepikt bij de volgende start van de dev-server. Als u een component toevoegt en de stijlen ontbreken, start u de dev-server opnieuw op.

Continue versies

Nuxt UI gebruikt pkg.pr.new voor continue preview-releases, waardoor ontwikkelaars direct toegang hebben tot de nieuwste functies en bugfixes zonder te wachten op officiële releases.

Automatische preview-releases worden gemaakt voor alle commits en PR 's naar de v4-branch. Gebruik ze door uw pakketversie te vervangen door de specifieke commit-hash of PR-nummer.

package.json

{
  "dependencies": {
-   "@nuxt/ui": "^4.0.0",
+   "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@4c96909",
  }
}

pkg.pr.new zal automatisch reageren op PR 's met de installatie-URL, waardoor het gemakkelijk is om wijzigingen te testen.

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.