---
title: Installation
description: 'Learn how to install and configure Nuxt UI in your application.'
---

## Setup

### Add to a Nuxt project

1. Install the `@nuxt/ui` dependency in your project:

::code-group

```bash [pnpm]
pnpm add @nuxt/ui@2
```

```bash [yarn]
yarn add @nuxt/ui@2
```

```bash [npm]
npm install @nuxt/ui@2
```

```bash [bun]
bun add @nuxt/ui@2
```

::

2. Register the `@nuxt/ui` module in your `nuxt.config.ts`:

```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](https://nuxt.new/) template makes it easy to get started with Nuxt UI.
The Nuxt Starter template is available from the `nuxi init` command.

```bash
npx nuxi@latest init -t ui2
```

Please check [nuxt/starter](https://github.com/nuxt/starter/tree/ui) for details.

## Modules

Nuxt UI will automatically install the [@nuxt/icon](https://github.com/nuxt/icon), [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org/) and [@nuxtjs/color-mode](https://color-mode.nuxtjs.org/) modules for you.

::callout{icon="i-heroicons-exclamation-triangle"}
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.

::callout{icon="i-heroicons-light-bulb"}
You can read more about this in the [Theming](/getting-started/theming#icons) section.
::

### `@nuxtjs/tailwindcss`

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

- [@tailwindcss/forms](https://github.com/tailwindlabs/tailwindcss-forms)
- [@tailwindcss/typography](https://github.com/tailwindlabs/tailwindcss-typography)
- [@tailwindcss/aspect-ratio](https://github.com/tailwindlabs/tailwindcss-aspect-ratio)
- [@tailwindcss/container-queries](https://github.com/tailwindlabs/tailwindcss-container-queries)
- [@headlessui/tailwindcss](https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-vue)

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

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

::callout{icon="i-heroicons-light-bulb"}
You can read more about this in the [Theming](/getting-started/theming#dark-mode) section.
::

## TypeScript

This module is written in TypeScript and provides typings for all the components and composables. You can look at the [source code](https://github.com/nuxt/ui/tree/v2/src/runtime/types) to see all the available types.

::callout{icon="i-heroicons-light-bulb" to="https://nuxt.com/docs/guide/concepts/typescript" target="_blank"}
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:

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

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    button: {
      color: {
        custom: {
          subtle: '...'
        }
      }
    }
  }
})
```

::callout{icon="i-heroicons-light-bulb"}
You can read more about components configuration in the [Theming](/getting-started/theming#appconfigts) section.
::

## IntelliSense

If you're using VSCode, you can install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension to get autocompletion for the classes.

You can read more on how to set it up on the [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org/tailwind/editor-support) module documentation, but to summarize, you'll need to add the following to your `.vscode/settings.json`:

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

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

```ts [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`:

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

```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()`):

```vue [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:

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

## Options

| Key                   | Default         | Description                                                                                                 |
|-----------------------|-----------------|-------------------------------------------------------------------------------------------------------------|
| `prefix`              | `u`             | Define the prefix of the imported components.                                                               |
| `global`              | `false`         | Expose components globally.                                                                                 |
| `safelistColors`      | `['primary']`   | Force safelisting of colors to need be purged.                                                              |
| `disableGlobalStyles` | `false`         | Disable [global CSS styles](https://github.com/nuxt/ui/blob/v2/src/runtime/ui.css) injected by the module. |

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

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

## Continuous Releases

Nuxt UI uses [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) for continuous preview releases, providing developers with instant access to the latest features and bug fixes without waiting for official releases.

Preview releases are automatically generated for every commit to the `dev` branch and pull requests targeting the `dev` branch. To use it into your project, replace the version in your `package.json` with the commit hash or pull request number.

```diff [package.json]
{
  "dependencies": {
-   "@nuxt/ui": "^2.21.0",
+   "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@bf1c9e7",
  }
}
```

::note
**pkg.pr.new** will automatically comment on PRs with the installation URL, making it easy to test changes.
::