ui/docs/content/1.getting-started/3.theming.md

---
description: 'Learn how to customize the look and feel of the components.'
---

## Overview

This module relies on Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) file to customize the look and feel of the components at runtime with HMR (hot-module-replacement).

## Colors

Components are based on a `primary` and a `gray` color. You can change them in your `app.config.ts`.

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    primary: 'green',
    gray: 'cool'
  }
})
```

As this module uses TailwindCSS under the hood, you can use any of the [TailwindCSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) or your own custom colors. By default, the `primary` color is `green` and the `gray` color is `cool`.

To provide dynamic colors that can be changed at runtime, this module uses CSS variables. As TailwindCSS already has a `gray` color, the module automatically renames it to `cool` to avoid conflicts (`coolGray` was renamed to `gray` when Tailwind CSS v3.0 was released).

::alert{icon="i-heroicons-light-bulb"}
Try to change the `primary` and `gray` colors in the navbar and see the colors change live.
::

Components that have a `color` prop like [Avatar](/elements/avatar), [Badge](/elements/badge) and [Button](/elements/button) will use the `primary` color by default but will handle all the colors defined in your `tailwind.config.ts` or the default TailwindCSS colors.

## Dark mode

All the components are styled with dark mode in mind.

Thanks to [TailwindCSS dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually) `class` strategy and the [@nuxtjs/color-mode](https://github.com/nuxt-modules/color-mode) module, you literally have nothing to do.

## Components

Components are styled with TailwindCSS but classes are all defined in the default [app.config.ts](https://github.com/nuxtlabs/ui/blob/dev/src/runtime/app.config.ts) file. You can override them in your `app.config.ts`.

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    container: {
      constrained: 'max-w-5xl'
    }
  }
})
```

Each component has a `ui` prop that allows you to customize everything specifically.

```vue
<template>
  <UContainer :ui="{ constrained: 'max-w-2xl' }">
    <slot />
  </UContainer>
</template>
```

::alert{icon="i-heroicons-light-bulb"}
You can find the default classes for each component under the `Preset` section.
::

Some component props like `size`, `color`, `variant`, etc. have a default value that you can override in your `app.config.ts`.

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    button: {
      default: {
        size: 'md',
        color: 'gray',
        variant: 'ghost'
      }
    }
  }
})
```

## Icons

You can use any icon (100,000+) from [Iconify](https://iconify.design/).

Some components have an `icon` prop that allows you to add an icon to the component.

```vue
<template>
  <UButton icon="i-heroicons-magnifying-glass" />
</template>
```

You can also use the [Icon](/elements/icon) component to add an icon anywhere in your app by following this pattern: `i-{collection_name}-{icon_name}`.

```vue
<template>
  <UIcon name="i-heroicons-moon" />
</template>
```

By default, the module uses [Heroicons](https://heroicons.com/) but you can change it from the module options in your `nuxt.config.ts`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  ui: {
    icons: ['mdi', 'simple-icons']
  }
})
```

::alert{icon="i-heroicons-light-bulb"}
Search the icon you want to use on https://icones.js.org built by [@antfu](https://github.com/antfu).
::

Unlike the official [nuxt-icon](https://github.com/nuxt-modules/icon/) module, this module will not fetch any icon from the web and will only bundle the icons you use in your app thanks to [egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons).

However, you will need to install the icon packages you want to use.

::code-group

```bash [yarn]
yarn add -D @iconify/json-{collection_name}
```

```bash [npm]
npm install -D @iconify/json-{collection_name}
```

```sh [pnpm]
pnpm i -D @iconify/json-{collection_name}
```

::

You can easily replace all the default icons of the components in your `app.config.ts`.

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    button: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    input: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    select: {
      default: {
        trailingIcon: 'i-octicon-chevron-down-24'
      }
    },
    selectMenu: {
      default: {
        selectedIcon: 'i-octicon-check-24'
      }
    },
    notification: {
      default: {
        close: {
          icon: 'i-octicon-x-24'
        }
      }
    },
    commandPalette: {
      default: {
        icon: 'i-octicon-search-24',
        selectedIcon: 'i-octicon-check-24',
        empty: {
          icon: 'i-octicon-search-24'
        }
      }
    }
  }
})
```