Theming

This module relies on Nuxt App Config file to customize the look and feel of the components at runtime with HMR (hot-module-replacement).

Colors

Configuration

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

export default defineAppConfig({
  ui: {
    primary: 'green',
    gray: 'cool'
  }
})

As this module uses Tailwind CSS under the hood, you can use any of the Tailwind CSS colors or your own custom colors or groups, such as brand.primary. By default, the primary color is green and the gray color is cool.

When using custom colors or adding additional colors through the extend key in your tailwind.config.ts, you'll need to make sure to define all the shades from 50 to 950 as most of them are used in the components config defined in ui.config/ directory. You can generate your colors using tools such as https://uicolors.app/ for example.

import type { Config } from 'tailwindcss'
import defaultTheme from 'tailwindcss/defaultTheme'

export default <Partial<Config>>{
  theme: {
    extend: {
      colors: {
        green: {
          50: '#EFFDF5',
          100: '#D9FBE8',
          200: '#B3F5D1',
          300: '#75EDAE',
          400: '#00DC82',
          500: '#00C16A',
          600: '#00A155',
          700: '#007F45',
          800: '#016538',
          900: '#0A5331',
          950: '#052e16'
        }
      }
    }
  }
}

CSS Variables

To provide dynamic colors that can be changed at runtime, this module uses CSS variables. As Tailwind CSS 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).

Likewise, you can't define a primary color in your tailwind.config.ts as it would conflict with the primary color defined by the module.

The primary color also has a DEFAULT shade that changes based on the theme. It is 500 in light mode and 400 in dark mode. You can use as a shortcut in your components and pages, e.g. text-primary, bg-primary, focus-visible:ring-primary, etc.

Smart Safelisting

Components having a color prop like Avatar, Badge, Button, Input (inherited in Select and SelectMenu), RadioGroup, Checkbox, Toggle, Range and Notification will use the primary color by default but will handle all the colors defined in your tailwind.config.ts or the default Tailwind CSS colors.

Variant classes of those components are defined with a syntax like bg-{color}-500 dark:bg-{color}-400 so they can be used with any color. However, this means that Tailwind will not find those classes and therefore will not generate the corresponding CSS.

The module uses the Tailwind CSS safelist feature to force the generation of all the classes for the primary color only as it is the default color for all the components.

Then, the module will automatically detect when you use one of those components with a color and will safelist it for you. This means that if you use a red color for a Button component, the red color classes will be safelisted for the Button component only. This will allow to keep the CSS bundle size as small as possible.

There is one case where you would want to force the safelisting of a color. For example, if you've set the default color of the Button component to orange in your app.config.ts.

export default defineAppConfig({
  ui: {
    button: {
      default: {
        color: 'orange'
      }
    }
  }
})

This will apply the orange color when using a default <UButton />. You'll need to safelist this color manually in your nuxt.config.ts ui options as we won't be able to detect it automatically. You can do so through the safelistColors option which defaults to ['primary'].

export default defineNuxtConfig({
  ui: {
    safelistColors: ['orange']
  }
})

This can also happen when you bind a dynamic color to a component: <UBadge :color="color" />, <UAvatar :chip-color="statuses[user.status]" />, etc. In this case, you'll need to safelist the possible color values manually as well.

Components

app.config.ts

You can override component config in your own app.config.ts:

export default defineAppConfig({
  ui: {
    container: {
      constrained: 'max-w-5xl'
    }
  }
})

The available options for each component should auto-complete, and you can review the defaults for each component using your IDE's function such as Cmd+Click (these files can be found in src/runtime/ui.config/).

Thanks to tailwind-merge, the app.config.ts is smartly merged with the default config. This means you don't have to rewrite everything.

You can change this behavior by setting strategy to override in your app.config.ts:

export default defineAppConfig({
  ui: {
    strategy: 'override',
    button: {
      color: {
        white: {
          solid: 'bg-white dark:bg-gray-900'
        }
      }
    }
  }
})

ui prop

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

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

Thanks to tailwind-merge, the ui prop is smartly merged with the config. This means you don't have to rewrite everything.

For example, the default preset of the FormGroup component looks like this:

{
  "label": {
    "base": "block font-medium text-gray-700 dark:text-gray-200"
  }
}

To change the font of the label, you only need to write:

<UFormGroup name="email" label="Email" :ui="{ label: { base: 'font-semibold' } }" />

This will smartly replace the font-medium by font-semibold and prevent any class duplication and any class priority issue.

You can change this behavior by setting strategy to override inside the ui prop:

<UButton
  to="https://github.com/nuxt/ui"
  :ui="{
    strategy: 'override',
    color: {
      white: {
        solid: 'bg-white dark:bg-gray-900'
      }
    }
  }"
/>

class attribute

You can also use the class attribute to add classes to the component.

<template>
  <UButton label="Button" class="rounded-full" />
</template>

Again, with tailwind-merge, this will smartly merge the classes with the ui prop and the config.

Default values

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

export default defineAppConfig({
  ui: {
    button: {
      default: {
        size: 'md',
        color: 'gray',
        variant: 'ghost'
      }
    }
  }
})

Extend Tailwind Merge

Tailwind Merge is a library that allows you to efficiently merge Tailwind CSS classes. It is used by this module to merge the classes from the ui prop, the class attribute, and the default classes.

By default, Tailwind Merge doesn't handle custom Tailwind CSS configuration like custom colors, spacing, or other utilities you may have defined. You'll need to extend it to handle your custom configuration.

You can extend Tailwind Merge by using the tailwindMerge option in your app.config.ts:

export default defineAppConfig({
  ui: {
    tailwindMerge: {
      extend: {
        theme: {
          spacing: ['sm', 'md', 'lg', 'xl', '2xl']
        }
      }
    }
  }
})

Dark mode

All the components are styled with dark mode in mind.

Thanks to Tailwind CSS dark mode class strategy and the @nuxtjs/color-mode module, you literally have nothing to do.

You can disable dark mode by setting the preference to light instead of system in your nuxt.config.ts.

export default defineNuxtConfig({
  colorMode: {
    preference: 'light'
  }
})

You can easily build a color mode button by using the useColorMode composable from @nuxtjs/color-mode.

<script setup lang="ts">
const colorMode = useColorMode()
const isDark = computed({
  get () {
    return colorMode.value === 'dark'
  },
  set () {
    colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
  }
})
</script>

<template>
  <ClientOnly>
    <UButton
      :icon="isDark ? 'i-heroicons-moon-20-solid' : 'i-heroicons-sun-20-solid'"
      color="gray"
      variant="ghost"
      aria-label="Theme"
      @click="isDark = !isDark"
    />
    <template #fallback>
      <div class="w-8 h-8" />
    </template>
  </ClientOnly>
</template>

Icons

Thanks to @nuxt/icon, add 200,000+ ready to use icons to your Nuxt application based on Iconify.

You can use any name from the https://icones.js.org collection such as the i- prefix (for example, i-heroicons-cog) with:

• any icon prop available across the components:

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

• the UIcon component to use icons anywhere:

<template>
  <UIcon name="i-heroicons-moon" class="w-5 h-5 text-primary-500" />
</template>

Collections

It's highly recommended to install the icons collections locally with:

pnpm i @iconify-json/{collection_name}

For example, to use the i-uil-github icon, install it's collection with @iconify-json/uil. This way the icons can be served locally or from your serverless functions, which is faster and more reliable on both SSR and client-side.

Defaults

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

export default defineAppConfig({
  ui: {
    button: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    input: {
      default: {
        loadingIcon: 'i-octicon-sync-24'
      }
    },
    select: {
      default: {
        loadingIcon: 'i-octicon-sync-24',
        trailingIcon: 'i-octicon-chevron-down-24'
      }
    },
    selectMenu: {
      default: {
        selectedIcon: 'i-octicon-check-24'
      }
    },
    notification: {
      default: {
        closeButton: {
          icon: 'i-octicon-x-24'
        }
      }
    },
    commandPalette: {
      default: {
        icon: 'i-octicon-search-24',
        loadingIcon: 'i-octicon-sync-24',
        selectedIcon: 'i-octicon-check-24',
        emptyState: {
          icon: 'i-octicon-search-24'
        }
      }
    },
    table: {
      default: {
        sortAscIcon: 'i-octicon-sort-asc-24',
        sortDescIcon: 'i-octicon-sort-desc-24',
        sortButton: {
          icon: 'i-octicon-arrow-switch-24'
        },
        loadingState: {
          icon: 'i-octicon-sync-24'
        },
        emptyState: {
          icon: 'i-octicon-database-24'
        }
      }
    },
    pagination: {
      default: {
        firstButton: {
          icon: 'i-octicon-chevron-left-24'
        },
        prevButton: {
          icon: 'i-octicon-arrow-left-24'
        },
        nextButton: {
          icon: 'i-octicon-arrow-right-24'
        },
        lastButton: {
          icon: 'i-octicon-chevron-right-24'
        }
      }
    },
    accordion: {
      default: {
        openIcon: 'i-octicon-chevron-down-24'
      }
    },
    breadcrumb: {
      default: {
        divider: 'i-octicon-chevron-right-24'
      }
    }
  }
})