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

description

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

Overview

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

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 TailwindCSS under the hood, you can use any of the TailwindCSS colors 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, Badge and 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 class strategy and the @nuxtjs/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 file. You can override them in your 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.

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

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

Icons

You can use any icon (100,000+) from Iconify.

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

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

You can also use the Icon component to add an icon anywhere in your app by following this pattern: i-{collection_name}-{icon_name}.

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

By default, the module uses Heroicons but you can change it from the module options in your 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. ::

Unlike the official nuxt-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.

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

yarn add --dev @iconify/json-{collection_name}

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: {
        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'
        }
      }
    }
  }
})