Installation

Découvrez comment installer et configurer l

Définition

Ajouter à un projet Vue

Installer le package Nuxt UI

pnpm add @nuxt/ui tailwindcss

yarn add @nuxt/ui tailwindcss

npm install @nuxt/ui tailwindcss

bun add @nuxt/ui tailwindcss

Ajouter le plugin Nuxt UI Vite dans votre `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 enregistre unplugin-auto-import et unplugin-vue-components, ce qui générera des fichiers de déclaration de type auto-imports.d.ts et components.d.ts. Vous voudrez probablement les gitignore et les ajouter à votre 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

Le script create-vuebuild par défaut exécute vue-tsc en parallèle avec vite build (run-p type-check "build-only {@}"), donc sur une vérification de type propre peut commencer avant que les fichiers n'existent et échouer avec des erreurs comme Cannot find name 'useToast'.

package.json

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

En interne, l'interface utilisateur Nuxt utilise des alias personnalisés pour résoudre les types de thèmes. Si vous utilisez TypeScript, ajoutez ces alias à vos fichiers tsconfig pour activer la complétion automatique dans votre 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/*"
      ]
    }
  }
}

Utiliser le plugin 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')

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

Import Tailwind CSS et Nuxt UI dans votre CSS

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

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

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

Importez le fichier CSS dans votre point d'entrée.

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

Il est recommandé d'installer l'extension Tailwind CSS IntelliSense pour VSCode et d'ajouter les paramètres suivants:

.vscode/settings.json

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

Wrap votre application avec le composant App

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

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

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

Le composant App configure la configuration globale et est nécessaire pour Toast, Tooltip et overlays programmatique.

Ajouter la classe `isolate` à votre conteneur racine

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

Cela garantit que les styles sont adaptés à votre application et évite les problèmes de superpositions et de contextes d'empilement.

Utiliser un template Vue

Commencez avec l'un de nos templates officiels x en utilisant le bouton Use this template sur GitHub ou la 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

Un modèle minimal pour démarrer avec Nuxt UI.

Dashboard

Un modèle de tableau de bord avec une disposition multi-colonnes pour créer des interfaces d'administration sophistiquées.

Chat

Un modèle de chatbot AI pour construire votre propre chatbot alimenté par Vercel AI SDK.

Starter Adonis

Un modèle d'interface utilisateur Nuxt minimal pour AdonisJS en utilisant Inertia.js.

Starter Laravel

Un modèle d'interface utilisateur Nuxt minimal pour Laravel en utilisant Inertia.js.

options

Vous pouvez personnaliser l'interface utilisateur Nuxt en fournissant des options dans votre vite.config.ts.

x`prefix`

Utilisez l'option prefix pour modifier le préfixe des composants.

Par défaut: 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'
    })
  ]
})

x`ui`

Utilisez l'option ui pour fournir la configuration de l'interface utilisateur Nuxt. Ceci est l'équivalent Vue de la clé ui dans app.config.ts de Nuxt.

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`

Utilisez l'option dts pour activer ou désactiver la génération de fichiers de déclaration pour les composants et compositables importés automatiquement.

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

x`icon`

Utilisez l'option icon pour définir les accessoires par défaut pour le composant Icon (size, mode, customize) et pour configurer le regroupement d'icônes au moment de la construction via clientBundle. Le regroupement des icônes propres à l'interface utilisateur Nuxt est activé par défaut lorsque leur collection est installée.

Défaut: {}

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

En savoir plus sur les collections d'icônes et le regroupement de clients dans la documentation Icons.

x`colorMode`

Utilisez l'option colorMode pour activer ou désactiver l'intégration du mode couleur de @vueuse/core.

Par défaut: 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
    })
  ]
})

x`theme.colors`

Utilisez l'option theme.colors pour définir les alias de couleurs dynamiques utilisés pour générer le thème des composants.

Par défaut: ['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']
      }
    })
  ]
})

Chaque alias génère un ensemble complet de nuances et de variantes --ui-color-* dans les thèmes de composants qui ont des variantes de couleur, que votre application l'utilise ou non. Trimpez la liste aux alias que vous utilisez réellement et conservez error si vous utilisez des formulaires, car les styles de validation en dépendent.

En savoir plus sur la personnalisation des couleurs et la thématisation dans la section Thème.

x`theme.transitions`

Utilisez l'option theme.transitions pour activer ou désactiver les transitions sur les composants.

Par défaut: 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
      }
    })
  ]
})

Cette option ajoute la classe transition-colors sur les composants avec des états stationnaires ou actifs.

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

Utilisez l'option theme.unstyled pour supprimer toutes les classes de thèmes par défaut des composants, en ne conservant que leur structure et les classes que vous fournissez via class, ui ou app.config.ui.

Par défaut: 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
      }
    })
  ]
})

Cela supprime également les classes structural (positionnement, transitions, flex/grille), pas seulement celles cosmétiques. Les composants lourds en termes de mise en page comme Modal, Drawer ou Calendar auront besoin de vous pour réapprovisionner leur mise en page, similaire au mode non stylé de PrimeVue.

x`theme.defaultVariants`

Utilisez l'option theme.defaultVariants pour remplacer les variantes color et size par défaut pour les composants.

Seuls les paramètres par défaut qui sont exactement primary ou md sont remplacés, donc Avatar conserve color: 'neutral' et Separator conserve size: 'xs'.

Par défaut: { 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'
        }
      }
    })
  ]
})

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

Utilisez l'option theme.prefix pour configurer le même préfixe que celui que vous avez défini sur votre importation CSS Tailwind. Cela garantit que les composants de l'interface utilisateur Nuxt utilisent les classes utilitaires et les variables CSS préfixées correctes.

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";

Cela préfixe automatiquement toutes les classes d'utilitaires Tailwind et les variables CSS dans les thèmes de composants Nuxt UI:

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

En savoir plus sur l'utilisation d'un préfixe dans la documentation CSS Tailwind.

x`prose`

Utilisez l'option prose pour activer les composants Prosex de Nuxt UI et leur thème.

Par défaut: falsex{lang="ts-type"}

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

x`autoImport`

Utilisez l'option autoImport pour désactiver les importations automatiques composables ou pour personnaliser les options unplugin-auto-import.

Par défaut: {}

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

Lorsque cette fonctionnalité est désactivée, vous pouvez toujours importer des composables explicitement depuis @nuxt/ui/composables.

x`components`

Utilisez l'option components pour désactiver l'importation automatique de composants ou pour personnaliser les options unplugin-vue-components.

Par défaut: {}

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

Lorsque cette option est désactivée, vous pouvez toujours importer des composants explicitement, par exemple import Button from '@nuxt/ui/components/Button.vue' ou import ProseCode from '@nuxt/ui/components/prose/Code.vue'.

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

Utilisez l'option router pour configurer l'intégration de routage. Ceci est utile pour les applications qui n'utilisent pas vue-router, telles que les applications Electron, les MPA ou les frameworks tels que [https://inertiajs.com/) ou [Hybridly](https://hybridly.dev/ph75x.

Default: true

Valeur	Description
`true`x{lang="ts-type"}	Utilise `vue-router` pour la navigation avec le composant `RouterLink`.
`false`	Désactive l'intégration de routage, les liens s'affichent sous forme de balises `<a>` simples.
`'inertia'`x{lang="ts-type"}	Utilise Inertia.js pour la navigation avec son composant `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
    })
  ]
})

Vous pouvez fournir une logique de navigation personnalisée pour des frameworks tels que Hybridly en définissant router: false dans la configuration de Vite et en passant une fonction lors de l'installation du plugin Vue:

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

Lorsqu 'il est défini sur false ou 'inertia', vue-router n'est pas nécessaire en tant que dépendance.

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

Utilisez l'option scanPackages pour spécifier des paquets npm supplémentaires qui doivent être analysés à la recherche de composants utilisant l'interface utilisateur Nuxt. Ceci est utile lorsque vous disposez d'une bibliothèque de composants partagée qui utilise des composants de l'interface utilisateur Nuxt en interne.

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

Par défaut, seul @nuxt/ui est analysé. Utilisez cette option lorsque vos paquets externes contiennent des composants Vue qui utilisent l'interface utilisateur Nuxt.

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

Utilisez l'option root pour remplacer le répertoire où Nuxt UI génère son répertoire .nuxt-ui (contenant les modèles de thème). Par défaut, il utilise root de Vite, mais dans des configurations comme electron-vite, le moteur de rendu root pointe vers un sous-répertoire (par exemple, src/renderer), de sorte que les modèles atterrissent dans src/renderer/node_modules/.nuxt-ui où Tailwind ne les analyse pas, ce qui fait que les classes de thèmes comme bg-default, ring-default et divide-default sont manquantes.

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

Pointez root à la racine de votre projet afin que le répertoire .nuxt-ui généré se retrouve dans un node_modules que Tailwind analyse.

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

Utilisez l'option experimental.componentDetection pour activer la détection automatique des composants pour le tree-shaking. Cette fonctionnalité analyse votre code source pour détecter les composants réellement utilisés et génère uniquement le CSS nécessaire pour ces composants.(y compris leurs dépendances). Sans cela, le plugin Vite génère le thème CSS pour chaque composant. Detection couvre la racine de Vite, les paquets listés dans scanPackages et tout dirs de l'option components situé en dehors de la racine.

Par défaut: false Xph899xType: boolean | string[]

**Enable détection automatique: **

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

**Inclut des composants supplémentaires pour une utilisation dynamique: **

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

Lorsque vous fournissez un tableau de noms de composants, la détection automatique est activée et ces composants (ainsi que leurs dépendances) sont garantis d'être inclus. Ceci est utile pour les composants dynamiques comme <component :is="..." /> qui ne peuvent pas être analysés statiquement.

Les composants nouvellement utilisés sont récupérés au prochain démarrage du serveur de développement. Si vous ajoutez un composant et que ses styles sont manquants, redémarrez le serveur de développement.

Libérations continues

Nuxt UI utilise pkg.pr.new pour les versions d'aperçu continues, offrant aux développeurs un accès instantané aux dernières fonctionnalités et corrections de bogues sans attendre les versions officielles.

Les versions d'aperçu automatiques sont créées pour tous les commits et les PR de la branche v4.Utilisez-les en remplaçant la version de votre paquet par le hash de commit ou le numéro de PR.

package.json

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

pkg.pr.new commentera automatiquement les RP avec l'URL d'installation, ce qui facilite le test des modifications.

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.