Installation^PRO

Learn how to install and configure Nuxt UI Pro in your Vue application.

Nuxt UI Pro is a collection of Vue components, composables and utils built on top of Nuxt UI, oriented on structure and layout and designed to be used as building blocks for your app.

Setup

Add to a Vue project

Install the Nuxt UI Pro package

pnpm add @nuxt/ui-pro@3

yarn add @nuxt/ui-pro@3

npm install @nuxt/ui-pro@3

bun add @nuxt/ui-pro

If you're using pnpm, ensure that you either set shamefully-hoist=true in your .npmrc file or install tailwindcss, vue-router and @unhead/vue in your project's root directory.

Add the Nuxt UI Pro Vite plugin in your `vite.config.ts`

vite.config.ts

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

export default defineConfig({
  plugins: [
    vue(),
    uiPro()
  ]
})

Nuxt UI registers unplugin-auto-import and unplugin-vue-components, which will generate auto-imports.d.ts and components.d.ts type declaration files. You will likely want to gitignore these, and add them to your 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

Internally, Nuxt UI relies on custom alias to resolve the theme types. If you're using TypeScript, you should add an alias to your tsconfig to enable auto-completion in your vite.config.ts.

tsconfig.node.json

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

Use the Nuxt UI Vue plugin in your `main.ts`

main.ts

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

If you're using Inertia.js, you can skip the vue-router setup as Inertia provides its own routing system.

Import Tailwind CSS and Nuxt UI Pro in your CSS

assets/main.css

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

Import the CSS file in your main.ts.

main.ts

import './assets/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')

It's recommended to install the Tailwind CSS IntelliSense extension for VSCode and add the following settings:

.vscode/settings.json

{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "ui"],
  "tailwindCSS.experimental.classRegex": [
    ["ui:\\s*{([^)]*)\\s*}", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

Wrap your app with App component

App.vue

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

The App component sets up global config and is required for Toast, Tooltip and programmatic overlays.

Add the `isolate` class to your root container

index.html

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

This ensures styles are scoped to your app and prevents issues with overlays and stacking contexts.

Upgrade from Nuxt UI

Replace `@nuxt/ui` package with `@nuxt/ui-pro`

package.json

{
  "dependencies": {
-   "@nuxt/ui": "^3.0.0",
+   "@nuxt/ui-pro": "^3.0.0",
  }
}

Replace `@nuxt/ui` vite plugin with `@nuxt/ui-pro`

vite.config.ts

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

export default defineConfig({
  plugins: [
    vue(),
-   ui(),
+   uiPro()
  ]
})

Replace `@nuxt/ui` CSS import with `@nuxt/ui-pro`

assets/css/main.css

@import "tailwindcss";
- @import "@nuxt/ui";
+ @import "@nuxt/ui-pro";

Use an official template

You can get started with our official Vue templates:

Dashboard

A Vue dashboard template with multi-column layout.

Starter Vue

A minimal Nuxt UI Pro setup for Vue.

Starter Adonis

A minimal Nuxt UI Pro setup for AdonisJS using Inertia.js.

Starter Laravel

A minimal Nuxt UI Pro setup for Laravel using Inertia.js.

You can use the Use this template button on GitHub to create a new repository or use the CLI:

npx giget@latest gh:nuxt-ui-templates/starter-vue#v3 my-vue-starter

npx giget@latest gh:nuxt-ui-templates/dashboard-vue#v3 my-vue-dashboard

Once the directory is created, you can install the dependencies and start the development server using the npm run dev command.

Options

You can customize Nuxt UI Pro by providing options in your vite.config.ts.

`prefix`

Use the prefix option to change the prefix of the components.

Default: U

vite.config.ts

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

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

`ui`

Use the ui option to provide configuration for Nuxt UI.

vite.config.ts

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

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

`uiPro`

Use the uiPro option to provide configuration for Nuxt UI Pro.

vite.config.ts

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

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      uiPro: {
        pageHero: {
          slots: {
            title: 'font-light'
          }
        }
      }
    })
  ]
})

`colorMode`

Use the colorMode option to enable or disable the color mode integration from @vueuse/core.

Default: true

vite.config.ts

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

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

`theme.colors`

Use the theme.colors option to define the dynamic color aliases used to generate components theme.

Default: ['primary', 'secondary', 'success', 'info', 'warning', 'error']

vite.config.ts

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

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      theme: {
        colors: ['primary', 'error']
      }
    })
  ]
})

Learn more about color customization and theming in the Theme section.

`theme.transitions`

Use the theme.transitions option to enable or disable transitions on components.

Default: true

vite.config.ts

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

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      theme: {
        transitions: false
      }
    })
  ]
})

This option adds the transition-colors class on components with hover or active states.

`theme.defaultVariants` New

Use the theme.defaultVariants option to override the default color and size variants for components.

Default: { color: 'primary', size: 'md' }

vite.config.ts

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

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

`inertia`

Use the inertia option to enable compatibility with Inertia.js.

vite.config.ts

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

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      inertia: true
    })
  ]
})

When using this option, vue-router is not required as Inertia.js provides its own routing system. The components that would normally use RouterLink will automatically use Inertia's InertiaLink component instead.

Continuous Releases

Nuxt UI Pro uses pkg.pr.new for continuous preview releases, providing developers with instant access to the latest features and bug fixes without waiting for official releases.

Automatic preview releases are created for all commits and PRs to the v3 branch. Use them by replacing your package version with the specific commit hash or PR number.

package.json

{
  "dependencies": {
-   "@nuxt/ui-pro": "^3.0.0",
+   "@nuxt/ui-pro": "https://pkg.pr.new/@nuxt/ui-pro@fb69f59",
  }
}

pkg.pr.new will automatically comment on PRs with the installation URL, making it easy to test changes.

Introduction

Nuxt UI harnesses the combined strengths of Reka UI, Tailwind CSS, and Tailwind Variants to offer developers an unparalleled set of tools for creating sophisticated, accessible, and highly performant user interfaces.

Migration

A comprehensive guide to migrate your application from Nuxt UI v2 to Nuxt UI v3.

InstallationPRO

Installation^PRO