Nuxt UI v3-alpha has been released!

Try it out
Getting Started

Installation

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

Setup

Add to a Nuxt project

  1. Add @nuxt/ui module to your project:
npx nuxi@latest module add ui
  1. Add it to the modules section in your nuxt.config.ts:
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.

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

@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.

You can read more about this in the Theming section.

@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.

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*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["/\\*\\s?ui\\s?\\*/\\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.
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
  }
})

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.