Instalación

Aprenda a instalar y configurar la interfaz de usuario de Nuxt en su aplicación Vue, compatible con Vite e Inertia.

Configuración

Añadir a un proyecto Vue

Instalar el paquete Nuxt UI

pnpm add @nuxt/ui tailwindcss

yarn add @nuxt/ui tailwindcss

npm install @nuxt/ui tailwindcss

bun add @nuxt/ui tailwindcss

Añadir el plugin Nuxt UI Vite en su `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'
    })
  ]
})

La interfaz de usuario de Nuxt registra unplugin-auto-import y unplugin-vue-components, lo que generará archivos de declaración de tipo auto-imports.d.ts y components.d.ts.

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

El script create-vuebuild por defecto ejecuta vue-tsc en paralelo con vite build (run-p type-check "build-only {@}"), por lo que en una comprobación de tipo de comprobación limpia puede comenzar antes de que los archivos existan y fallar con errores como Cannot find name 'useToast'.

package.json

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

Internamente, la interfaz de usuario de Nuxt se basa en alias personalizados para resolver los tipos de tema. Si está utilizando TypeScript, agregue estos alias a sus archivos tsconfig para habilitar la autofinalización en su 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/*"
      ]
    }
  }
}

Use el complemento 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)
  }
})

Importar Tailwind CSS y Nuxt UI en su CSS

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

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

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

Importe el archivo CSS en su punto de entrada.

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

Se recomienda instalar la extensión Tailwind CSS IntelliSense para VSCode y añadir los siguientes ajustes:

.vscode/settings.json

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

Wrap su aplicación con el componente de aplicación

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

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

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

El componente App configura la configuración global y es necesario para Toast, Tooltip y programmatic overlays.

Añadir la clase `isolate` a su contenedor raíz

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

Esto garantiza que los estilos se ajusten a su aplicación y evita problemas con las superposiciones y los contextos de apilamiento.

Usar una plantilla de Vue

Comience con uno de nuestros plantillas oficiales x usando el botón Use this template en GitHub o 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

Una plantilla mínima para empezar con Nuxt UI.

Dashboard

Una plantilla de tablero con diseño de varias columnas para crear interfaces de administración sofisticadas.

Chat

Una plantilla de chatbot de IA para construir su propio chatbot impulsado por Vercel AI SDK.

Starter Adonis

Una plantilla mínima de interfaz de usuario de Nuxt para AdonisJS usando Inertia.js.

Starter Laravel

Una plantilla de interfaz de usuario mínima de Nuxt para Laravel usando Inertia.js.

Opciones

Puede personalizar la interfaz de usuario de Nuxt proporcionando opciones en su vite.config.ts.

x`prefix` y

Use la opción prefix para cambiar el prefijo de los componentes.

Default: U (en español)

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` (Edición española)

Utilice la opción ui para proporcionar la configuración de la interfaz de usuario de Nuxt. Este es el equivalente de Vue de la clave ui en 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'
        }
      }
    })
  ]
})

x`dts`

Utilice la opción dts para habilitar o deshabilitar la generación de archivos de declaración para componentes y composibles importados automáticamente.

Default: truex{lang="ts-type"} (en inglés)

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

xx`icon` (Edición española)

Utilice la opción icon para establecer los accesorios predeterminados para el componente Icon (size, mode, customize) y para configurar la agrupación de iconos en tiempo de compilación a través de clientBundle.

Default: {} (en español)

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

Obtenga más información sobre las colecciones de iconos y la agrupación de clientes en la documentación de Icons.

xx`colorMode` (Edición española)

Utilice la opción colorMode para habilitar o deshabilitar la integración del modo de color de @vueuse/core.

Default: true (en inglés)

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`

Utilice la opción theme.colors para definir los alias de color dinámicos utilizados para generar el tema de los componentes.

Default: ['primary', 'secondary', 'success', 'info', 'warning', 'error'] (por defecto)

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

Cada alias genera un conjunto completo de tonos y variantes --ui-color-* en los temas de componentes que tienen variantes de color, ya sea que la aplicación lo use o no. Recorte la lista a los alias que realmente usa y mantenga error si usa formularios, ya que los estilos de validación dependen de él.

Obtenga más información sobre la personalización del color y la tematización en la sección Tema.

x`theme.transitions` (Edición española)

Utilice la opción theme.transitions para habilitar o deshabilitar las transiciones en los componentes.

Default: true (en inglés)

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

Esta opción agrega la clase transition-colors a los componentes con estados de desplazamiento o activos.

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

Utilice la opción theme.unstyled para eliminar todas las clases de tema predeterminadas de los componentes, manteniendo solo su estructura y las clases que proporciona a través de class, ui o app.config.ui.

Default: false (en inglés)

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

Esto elimina también las clases structural (posicionamiento, transiciones, flex/grid), no solo las cosméticas.Los componentes pesados en la disposición como Modal, Drawer o Calendar necesitarán que vuelva a suministrar su diseño, similar al modo sin estilo de PrimeVue.

xx`theme.defaultVariants` (Edición española)

Utilice la opción theme.defaultVariants para anular las variantes color y size predeterminadas para los componentes.

Sólo los valores predeterminados que son exactamente primary o md se sustituyen, por lo que Avatar mantiene color: 'neutral' y Separator mantiene size: 'xs'.

Default: { color: 'primary', size: 'md' } (en inglés)

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` y badge{label="4.2+" class="align-text-top"}

Utilice la opción theme.prefix para configurar el mismo prefijo que configuró en su importación de Tailwind CSS. Esto garantiza que los componentes de la interfaz de usuario de Nuxt utilicen las clases de utilidad y las variables CSS prefijadas correctas.

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

Esto prefijará automáticamente todas las clases de utilidad Tailwind y las variables CSS en los temas de componentes de interfaz de usuario de Nuxt:

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

Obtenga más información sobre el uso de un prefijo en la documentación de Tailwind CSS.

x`prose`

Utilice la opción prose para habilitar los componentes de Nuxt UI Prose y su tema.

Default: falsex{lang="ts-type"} por defecto

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` (Edición española)

Utilice la opción autoImport para deshabilitar las importaciones automáticas componibles o para personalizar las opciones de unplugin-auto-import.

Default: {} (en inglés)

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

Cuando está deshabilitado, todavía puede importar composables explícitamente desde @nuxt/ui/composables.

x`components` (Edición española)

Utilice la opción components para deshabilitar las importaciones automáticas de componentes o para personalizar las opciones de unplugin-vue-components.

xDefault: {}x{lang="ts-type"} por defecto

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

Cuando está desactivado, todavía puede importar componentes explícitamente, por ejemplo, import Button from '@nuxt/ui/components/Button.vue' o import ProseCode from '@nuxt/ui/components/prose/Code.vue'.

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

Esto es útil para aplicaciones que no usan vue-router, como aplicaciones Electron, MPAs o marcos como Inertia.js o Hybridly.

Default: truex{lang="ts-type"} por defecto

Valoración	Descripción
`true`x{lang="ts-type"}	Utiliza `vue-router` para la navegación con el componente `RouterLink`.
`false`x{lang="ts-type"}	Deshabilita la integración de enrutamiento, los enlaces se renderizan como etiquetas `<a>` simples.
`'inertia'`xx{lang="ts-type"} (Edición española)	Utiliza Inertia.js para la navegación con su componente `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
    })
  ]
})

Puede proporcionar una lógica de navegación personalizada para marcos como Hybridly configurando router: false en la configuración de Vite y pasando una función al instalar el complemento 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 })
  }
})

Cuando se establece en false o 'inertia', vue-router no es necesario como dependencia.

`scanPackages`: badge{label="4.3+" class="align-text-top"} (en inglés)

Utilice la opción scanPackages para especificar paquetes npm adicionales que deben analizarse en busca de componentes que utilicen la interfaz de usuario 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({
      scanPackages: ['@my-org/ui-components']
    })
  ]
})

De forma predeterminada, solo se escanea @nuxt/ui.Utilice esta opción cuando sus paquetes externos contengan componentes de Vue que utilicen la interfaz de usuario de Nuxt.

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

Utilice la opción root para reemplazar el directorio donde Nuxt UI genera su directorio .nuxt-ui Por defecto utiliza root de Vite, pero en configuraciones como electron-vite root del renderizador apunta a un subdirectorio.(por ejemplo, src/renderer), por lo que las plantillas aterrizan en src/renderer/node_modules/.nuxt-ui donde Tailwind no las escanea, lo que hace que falten clases de temas como bg-default, ring-default y 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
      })
    ]
  }
})

Apunte root a la raíz del proyecto para que el directorio .nuxt-ui generado termine en un node_modules que Tailwind escanea.

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

Utilice la opción experimental.componentDetection para habilitar la detección automática de componentes para el tree-shaking. Esta función escanea su código fuente para detectar qué componentes se utilizan realmente y solo genera el CSS necesario para esos componentes.(incluyendo sus dependencias). Sin él, el plugin de Vite genera el tema CSS para cada componente. Detection cubre la raíz de Vite, Los paquetes listados en scanPackages y cualquier dirs de la opción components ubicada fuera de la raíz.

Default: falsex{lang="ts-type"} por defecto Especificaciones: XPH900x{lang="ts-type"}

**Habilitar la detección automática: **

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

**Incluir componentes adicionales para uso dinámico: **

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

Cuando se proporciona una matriz de nombres de componentes, se habilita la detección automática y se garantiza que estos componentes (junto con sus dependencias) se incluirán. Esto es útil para componentes dinámicos como <component :is="..." /> que no se pueden analizar estáticamente.

Los componentes recién utilizados se recogen en el siguiente inicio del servidor de desarrollo. Si agrega un componente y faltan sus estilos, reinicie el servidor de desarrollo.

Liberaciones continuas.

La interfaz de usuario de Nuxt utiliza pkg.pr.new para versiones de vista previa continuas, proporcionando a los desarrolladores acceso instantáneo a las últimas funciones y correcciones de errores sin esperar a versiones oficiales.

Se crean versiones de vista previa automáticas para todos los commits y PRs de la rama v4.Utilízalos reemplazando la versión de tu paquete con el hash de commit o número de PR específico.

package.json

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

pkg.pr.new comentará automáticamente los PR con la URL de instalación, lo que facilita la prueba de cambios.

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.