Theming

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 Tailwind CSS under the hood, you can use any of the Tailwind CSS 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 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.

Components that have a color prop like Avatar, Badge, Button 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.

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.

Components

Components are styled with Tailwind CSS 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>

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']
  }
})

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 either @iconify/json (full icon collections, 50MB) or the individual icon packages you want to use in your app.

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

When using @iconify/json, you can specifiy icons: 'all' in your nuxt.config.ts to use any icon in your app.

export default defineNuxtConfig({
  ui: {
    icons: 'all'
  }
})

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