Installation

Setup

Add to a Nuxt project

1. Add @nuxt/ui module to your project:

npx nuxi@latest module add ui

2. Add it to the modules section in your 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 ✨

Use Nuxt starter

Nuxt Starter template makes it easy to get started with Nuxt UI. The Nuxt Starter template is available from the nuxi init command.

npx nuxi@latest init -t ui

Please check nuxt/starter for details.

Modules

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

@nuxt/icon

This module is installed to provide an easy way to use icons in your application. You can use the UIcon component to display any icon from Iconify.

@nuxtjs/tailwindcss

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

• @tailwindcss/forms
• @tailwindcss/typography
• @tailwindcss/aspect-ratio
• @tailwindcss/container-queries
• @headlessui/tailwindcss

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:

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.

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

export default defineAppConfig({
  ui: {
    button: {
      color: {
        custom: {
          subtle: '...'
        }
      }
    }
  }
})

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:

{
  "files.associations": {
      "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
      "strings": true
  }
}

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

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:

{
  "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:

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

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

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

{
  "tailwindCSS.classAttributes": [
    "class",
    "className",
    "ngClass",
    "ui"
  ]
}

Options

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

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

Edge

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

Update your package.json to the following:

{
  "devDependencies": {
-   "@nuxt/ui": "^2.11.0"
+   "@nuxt/ui": "npm:@nuxt/ui-edge@latest"
  }
}

Then run pnpm install, yarn install or npm install.