Nuxt UI Pro v1.0 is out with dashboard components! Discount ends 16 hours ago.

Getting Started

Installation

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

Setup

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

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

Modules

Nuxt UI will automatically install the @nuxtjs/tailwindcss, @nuxtjs/color-mode and nuxt-icon modules for you.

You should remove them from your modules and dependencies if you've previously installed them.

@nuxtjs/tailwindcss

This module is pre-configured and will automatically load the following plugins:

Note that the @tailwindcss/aspect-ratio plugin disables the default aspect ratio utilities:

  • aspect-auto
  • aspect-square
  • aspect-video

You can re-enable them by adding the following to your tailwind.config.ts:

tailwind.config.ts
import type { Config } from 'tailwindcss'

export default <Partial<Config>>{
  theme: {
    extend: {
      aspectRatio: {
        auto: 'auto',
        square: '1 / 1',
        video: '16 / 9'
      }
    }
  }
}

@nuxtjs/color-mode

This module is installed to provide dark mode support out of the box thanks to the Tailwind CSS dark mode class strategy.

You can read more about this in the Theming section.

nuxt-icon

This module is installed when using the dynamic prop on the Icon component or globally through the ui.icons.dynamic option in your app.config.ts.

You can read more about this in the Theming section and on the Icon component page.

TypeScript

This module is written in TypeScript and provides typings for all the components and composables. You can look at the source code to see all the available types.

You can read more about TypeScript on the official Nuxt documentation.

You can use those types in your own components by importing them from #ui/types, for example when defining wrapper components:

<template>
  <UBreadcrumb :links="links">
    <template #icon="{ link }">
      <UIcon :name="link.icon" />
    </template>
  </UBreadcrumb>
</template>

<script setup lang="ts">
import type { BreadcrumbLink } from '#ui/types'

export interface Props {
  links: BreadcrumbLink[]
}

defineProps<Props>()
</script>

You don't have to use TypeScript yourself, but doing so will give you access to prop validation and autocomplete.

We've managed to provide dynamic typings on props such as color, size, variant, etc. based on your custom config. For example, you'll be suggested the custom color and the subtle variant when using the Button component with an app.config.ts as such:

app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      color: {
        custom: {
          subtle: '...'
        }
      }
    }
  }
})
You can read more about components configuration in the Theming section.

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 lang="ts">
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.
disableGlobalStylesfalseDisable global CSS styles injected by the module.

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": "^2.11.0"
+   "@nuxt/ui": "npm:@nuxt/ui-edge@latest"
  }
}

Then run pnpm install, yarn install or npm install.