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

## Setup

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

::code-group

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

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

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

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

::

2. Add it to your `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 ✨

## Modules

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

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

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

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

::callout{icon="i-heroicons-light-bulb"}
You can read more about this in the [Theming](/getting-started/theming#dynamic-icons) section and on the [Icon](/components/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](https://github.com/nuxt/ui/tree/dev/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*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["/\\*ui\\*/\\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>
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.                                                                                 |
| `icons`               | `['heroicons']` | Icon collections to load.                                                                                   |
| `safelistColors`      | `['primary']`   | Force safelisting of colors to need be purged.                                                              |
| `disableGlobalStyles` | `false`         | Disable [global CSS styles](https://github.com/nuxt/ui/blob/dev/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,
    icons: ['mdi', 'simple-icons']
  }
})
```

## Edge

To use the latest updates pushed on the [`dev`](https://github.com/nuxt/ui/tree/dev) branch, you can use `@nuxt/ui-edge`.

Update your `package.json` to the following:

```diff [package.json]
{
  "devDependencies": {
-   "@nuxt/ui": "^2.11.0"
+   "@nuxt/ui": "npm:@nuxt/ui-edge@latest"
  }
}
```

Then run `pnpm install`, `yarn install` or `npm install`.