Installation

Setup

Add to a Nuxt project

pnpm add @nuxt/ui

yarn add @nuxt/ui

npm install @nuxt/ui

bun add @nuxt/ui

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

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

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

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

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

Use a Nuxt template

To quickly get started with Nuxt UI, you can use the starter template by running:

npm create nuxt@latest -- -t ui

You can also get started with one of our official templates:

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

npm create nuxt@latest -- -t ui

npm create nuxt@latest -- -t ui/landing

npm create nuxt@latest -- -t ui/docs

npm create nuxt@latest -- -t ui/saas

npm create nuxt@latest -- -t ui/dashboard

npm create nuxt@latest -- -t ui/chat

npm create nuxt@latest -- -t ui/portfolio

npm create nuxt@latest -- -t ui/changelog

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

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

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

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

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

theme.transitions

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

• Default: true

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

theme.defaultVariants

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

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

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

theme.prefix

Use the theme.prefix option to configure the same prefix you set on your Tailwind CSS import. This ensures Nuxt UI components use the correct prefixed utility classes and CSS variables.

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

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

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  },
  fonts: {
    processCSSVariables: true
  }
})

This will automatically prefix all Tailwind utility classes and CSS variables in Nuxt UI component themes:

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

mdc

Use the mdc option to force the import of Nuxt UI <Prose> components even if @nuxtjs/mdc or @nuxt/content is not installed.

• Default: false

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

content

Use the content option to force the import of Nuxt UI <Prose> and <UContent> components even if @nuxt/content is not installed (@nuxtjs/mdc is installed by @nuxt/content).

• Default: false

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

experimental.componentDetection

Use the experimental.componentDetection option to enable automatic component detection for tree-shaking. This feature scans your source code to detect which components are actually used and only generates the necessary CSS for those components (including their dependencies).

• Default: false
• Type: boolean | string[]

Enable automatic detection:

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

Include additional components for dynamic usage:

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

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 v4 branch. Use them by replacing your package version with the specific commit hash or PR number.

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