ui/docs/content/1.getting-started/2.installation/1.nuxt.md

title, description, framework, module, links, navigation.icon

title	description	framework	module	links	navigation.icon
Installation	Learn how to install and configure Nuxt UI in your Nuxt application.	nuxt	ui	label to icon Playground https://codesandbox.io/p/devbox/nuxt-ui3-n3sxks i-lucide-codesandbox	i-lucide-square-play

::callout{to="/getting-started/installation/vue" icon="i-logos-vue" class="hidden"} Looking for the Vue version? ::

Setup

Add to a Nuxt project

::steps{level="4"}

Install the Nuxt UI package

::code-group{sync="pm"}

pnpm add @nuxt/ui

yarn add @nuxt/ui

npm install @nuxt/ui

bun add @nuxt/ui

::

::warning If you're using pnpm, ensure that you either set shamefully-hoist=true in your .npmrc file or install tailwindcss in your project's root directory. ::

Add the Nuxt UI module in your nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})

Import Tailwind CSS and Nuxt UI in your CSS

::code-group

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

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css']
})

::

::callout{icon="i-simple-icons-visualstudiocode"} It's recommended to install the Tailwind CSS IntelliSense extension for VSCode and add the following settings:

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

::

Wrap your app with App component

<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

::note{to="/components/app"} The App component provides global configurations and is required for Toast, Tooltip components to work as well as Programmatic Overlays. ::

::

Use our Nuxt Starter

Start your project using the nuxt/starter#ui template with Nuxt UI pre-configured.

Create a new project locally by running the following command:

npm create nuxt@latest -- -t ui

::note The <my-app> argument is the name of the directory where the project will be created, replace it with your project name. ::

Once the installation is complete, navigate into your project and start the development server:

cd <my-app>
npm run dev

Options

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

prefix

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

• Default: U{lang="ts-type"}

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prefix: 'Nuxt'
  }
})

fonts

Use the fonts option to enable or disable the @nuxt/fonts module.

• Default: true{lang="ts-type"}

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    fonts: false
  }
})

colorMode

Use the colorMode option to enable or disable the @nuxt/color-mode module.

• Default: true{lang="ts-type"}

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    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']{lang="ts-type" class="inline"}

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      colors: ['primary', 'error']
    }
  }
})

::tip{to="/getting-started/theme#colors"} 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{lang="ts-type"}

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      transitions: false
    }
  }
})

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

theme.defaultVariants :badge

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

• Default: { color: 'primary', size: 'md' }{lang="ts-type"}

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      defaultVariants: {
        color: 'neutral',
        size: 'sm'
      }
    }
  }
})

Continuous Releases

Nuxt UI 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.

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

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