getting started

Installation

Learn how to install and configure the module in your Nuxt app.

Quick Start

  1. Install @nuxt/ui dependency to your project:
pnpm
pnpm i -D @nuxt/ui
  1. Add it to your modules section in your nuxt.config:
nuxt.config
export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})

That's it! You can now use all the components and composables in your Nuxt app ✨

As this module installs @nuxtjs/tailwindcss and @nuxtjs/color-mode for you, you should remove them from your modules and dependencies if you've previously installed them manually.

IntelliSense

If you're using VSCode, you can install the Tailwind CSS IntelliSense extension to get autocompletion for the classes.

You can read more on how to set it up on the @nuxtjs/tailwindcss module documentation, but to summarize, you'll need to add the following to your .vscode/settings.json:

.vscode/settings.json
{
  "files.associations": {
      "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
      "strings": true
  }
}

You can write your tailwind.config in TypeScript as such:

tailwind.config.ts
import type { Config } from 'tailwindcss'
export default <Partial<Config>> {
  content: [
    'docs/content/**/*.md'
  ]
}

If you do so, you'll need to add the following to your .vscode/settings.json:

.vscode/settings.json
{
  "tailwindCSS.experimental.configFile": "tailwind.config.ts"
}

Note, the extension won't work when writing classes in your app.config.ts by default.

Also, you might want IntelliSense on objects in your SFC by prefixing with /*ui*/.

To enable these two features, you can add the following to your .vscode/settings.json:

.vscode/settings.json
{
  "tailwindCSS.experimental.classRegex": [
    ["ui:\\s*{([^)]*)\\s*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["/\\*ui\\*/\\s*{([^;]*)}", ":\\s*[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

An example SFC using IntelliSense (note the /*ui*/ prefix, also works with ref()):

example.vue
<template>
  <UCard :ui="ui" />
</template>
<script setup>
const ui = /*ui*/ {
  background: 'bg-white dark:bg-slate-900'
}
</script>

You can also add the following to your .vscode/settings.json to enable IntelliSense when using the ui prop:

.vscode/settings.json
{
  "tailwindCSS.classAttributes": [
    "class",
    "className",
    "ngClass",
    "ui"
  ]
}

Options

KeyDefaultDescription
prefixuDefine the prefix of the imported components.
globalfalseExpose components globally.
icons['heroicons']Icon collections to load.
safelistColors['primary']Force safelisting of colors to need be purged.

Configure options in your nuxt.config.ts as such:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    global: true,
    icons: ['mdi', 'simple-icons']
  }
})

Edge

To use the latest updates pushed on the dev branch, you can use @nuxt/ui-edge.

Update your package.json to the following:

package.json
{
  "devDependencies": {
    "@nuxt/ui": "npm:@nuxt/ui-edge@latest"
  }
}

Then run pnpm install, yarn install or npm install.