---
title: Colors
description: 'Learn to customize Nuxt UI component colors, enhancing your application visual theme.'
---

## Build colors

Nuxt UI components provide dynamic `color` variants. By default, these variants classes are generated based on the default Tailwind CSS colors. Let's take the [Button](/components/button) component as an example:

::component-code{slug="button"}
---
props:
  color: 'green'
slots:
  default: Button
---
::

You can change these colors with the [`theme.colors`](/getting-started/installation#themecolors) option in your `nuxt.config.ts` to select only the colors you're actually using.

For example, if you added a custom `cerise` color and only use the default `blue` and `green` colors in your application, you can configure the `colors` option like this:

::code-group

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    theme: {
      colors: ['cerise', 'blue', 'green']
    }
  }
})
```

```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  --color-cerise-50: #FEF2F4;
  --color-cerise-100: #FDE6E9;
  --color-cerise-200: #FBD0D9;
  --color-cerise-300: #F7AAB9;
  --color-cerise-400: #F27A93;
  --color-cerise-500: #E63F66;
  --color-cerise-600: #D42A5B;
  --color-cerise-700: #B21E4B;
  --color-cerise-800: #951C45;
  --color-cerise-900: #801B40;
  --color-cerise-950: #470A1F;
}
```
::

::caution
Make sure to use color ranges from `50` to `950`. You can use tools like [UI Colors](https://uicolors.app/) to generate your palette.
::

This configuration will ensure that only classes for those three colors are generated in your final CSS bundle. When you use the `color` prop, it will be typed and provide autocompletion in your editor with those three colors.

```vue
<template>
  <UButton color="cerise">Button</UButton>
</template>
```

## Runtime colors

### Default aliases

Nuxt UI introduces three key color aliases used to style components:

- `primary`: Main brand color, used as the default color for components.
  - Default: `green`{color="green"}
- `error`: For form error validation states.
  - Default: `red`{color="red"}
- `gray`: Neutral color for backgrounds, text, etc.
  - Default: `slate`
  - `slate | cool | zinc | neutral | stone`

::warning{to="https://tailwindcss.com/docs/customizing-colors#default-color-palette" target="_blank"}
The Tailwind CSS `gray` color is renamed to `cool` in Nuxt UI to avoid conflicts with the `gray` alias.
::

You can configure these aliases in your `app.config.ts` file under the `ui.colors` key:

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      error: 'orange',
      gray: 'zinc'
    }
  }
})
```

This powerful feature leverages Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file), enabling dynamic styling of all components at runtime. It allows for real-time theme customization without requiring an application rebuild.

::tip
We recommend using these colors in your application whenever possible with classes like `text-primary-500 dark:text-primary-400`, `border-gray-200 dark:border-gray-800` or `bg-white dark:bg-gray-900` for example.
::

::important
These alias colors don't need to be explicitly listed in the `colors` option of your `nuxt.config.ts`. Also, if you've set `primary` to a custom color (e.g., `cerise`), you don't need to list `cerise` in the `colors` array.
::

::note
You can try this out by using the :prose-icon{name="i-heroicons-swatch-20-solid" class="text-primary-500 dark:text-primary-400"} menu in the header of this documentation.
::

### Custom aliases

You can also add your own color aliases to be configurable at runtime in your `app.config.ts` file:

1. Define the alias color by using CSS variables to let Tailwind know about it:

```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  --color-secondary-50: var(--color-secondary-50);
  --color-secondary-100: var(--color-secondary-100);
  --color-secondary-200: var(--color-secondary-200);
  --color-secondary-300: var(--color-secondary-300);
  --color-secondary-400: var(--color-secondary-400);
  --color-secondary-500: var(--color-secondary-500);
  --color-secondary-600: var(--color-secondary-600);
  --color-secondary-700: var(--color-secondary-700);
  --color-secondary-800: var(--color-secondary-800);
  --color-secondary-900: var(--color-secondary-900);
  --color-secondary-950: var(--color-secondary-950);
}
```

2. Set a default value for the color alias in your `app.config.ts` file:

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    colors: {
      secondary: 'indigo'
    }
  }
})
```

3. Add this color to the `colors` option of your `nuxt.config.ts` file to generate classes:

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

4. You can use the `secondary` color alias in your application and use classes like `text-secondary-500 dark:text-secondary-400`:

```vue
<template>
  <UButton color="secondary">Button</UButton>
</template>
```