---

name: nuxt-ui-theming description: Help customize Nuxt UI component themes and colors. Use when users ask about styling, theming, or customizing component appearance.

Nuxt UI Theming Guide

Assist with customizing Nuxt UI component themes, colors, and appearance.

When to Use

DO USE when:

• User wants to customize component appearance
• Questions about theme configuration
• Need to change colors or design tokens
• Want to create custom component variants
• Questions about the ui prop

DO NOT USE when:

• Basic component usage (covered in instructions)
• Finding which components exist (use nuxt-ui-component-finder)

Theming Levels

1. Global Configuration (nuxt.config.ts)

Copyexport default defineNuxtConfig({
  ui: {
    // Change component prefix (default: 'U')
    prefix: 'Nuxt',
    
    // Define theme colors
    theme: {
      colors: ['primary', 'secondary', 'success', 'error'],
      transitions: true,
      defaultVariants: {
        color: 'primary',
        size: 'md'
      }
    }
  }
})

2. App Configuration (app/app.config.ts)

Copyexport default defineAppConfig({
  ui: {
    // Global component defaults
    button: {
      default: {
        color: 'primary',
        size: 'md'
      }
    }
  }
})

3. Component Level (ui prop)

Copy<UButton
  :ui="{
    base: 'font-bold',
    variant: {
      solid: 'bg-blue-500 hover:bg-blue-600'
    }
  }"
>
  Custom Button
</UButton>

4. Utility Classes (class prop)

Copy<UButton class="shadow-lg rounded-full">
  Button with classes
</UButton>

Color System

Semantic Colors

Default semantic colors (configurable):

• primary - Main brand color
• secondary - Secondary brand color
• success - Success states (green)
• error - Error states (red)
• warning - Warning states (yellow/orange)
• info - Info states (blue)
• neutral - Neutral/gray

Using Colors

Copy<template>
  <UButton color="primary">Primary</UButton>
  <UButton color="error">Error</UButton>
  <UAlert color="success">Success message</UAlert>
</template>

Custom Colors

Add custom colors in Tailwind config:

Copy// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    theme: {
      colors: ['primary', 'secondary', 'brand', 'accent']
    }
  }
})

Component Customization

Using ui Prop

The ui prop accepts an object matching the component's theme structure:

Copy<template>
  <!-- Button customization -->
  <UButton
    :ui="{
      base: 'relative disabled:cursor-not-allowed',
      variant: {
        solid: 'bg-{color}-500 hover:bg-{color}-600',
        outline: 'border-2 border-{color}-500'
      },
      size: {
        lg: 'px-6 py-3 text-lg'
      }
    }"
  >
    Custom Button
  </UButton>

  <!-- Card customization -->
  <UCard
    :ui="{
      header: { 
        base: 'border-b',
        padding: 'px-6 py-4' 
      },
      body: { padding: 'p-6' }
    }"
  >
    <template #header>Header</template>
    Body content
  </UCard>
</template>

Slots-Based Theming

Components use slots for theme customization:

Copy<UCard
  :ui="{
    header: { base: 'bg-gray-50' },
    body: { base: 'space-y-4' },
    footer: { base: 'bg-gray-50' }
  }"
>
  <template #header>Custom Header Styling</template>
  Body with custom spacing
  <template #footer>Custom Footer</template>
</UCard>

Common Patterns

Creating Reusable Themed Components

Copy<!-- components/BrandButton.vue -->
<template>
  <UButton
    v-bind="$attrs"
    :ui="{
      variant: {
        solid: 'bg-gradient-to-r from-purple-500 to-pink-500'
      }
    }"
  >
    <slot />
  </UButton>
</template>

Dark Mode Styling

Copy<UButton
  :ui="{
    variant: {
      solid: 'bg-blue-500 dark:bg-blue-600'
    }
  }"
>
  Dark mode aware
</UButton>

Responsive Theming

Copy<UCard
  :ui="{
    body: {
      padding: 'p-4 md:p-6 lg:p-8'
    }
  }"
>
  Responsive padding
</UCard>

Process

User wants to customize a component:

1. Identify component (e.g., "Button")
2. Use mcp_nuxt-ui_get-component-metadata to see theme structure
3. Provide ui prop example for requested customization
4. Suggest global config if change should be app-wide

User wants to change brand colors:

1. Explain semantic color system
2. Show nuxt.config.ts theme.colors configuration
3. Provide Tailwind color palette setup if needed
4. Show component usage with new colors

User wants custom variants:

1. Get component theme structure
2. Show how to extend variants with ui prop
3. Suggest creating wrapper component for reuse

Resources

• Theming Documentation
• Design System
• Tailwind Variants

Tips

• Use ui prop for component-level customization
• Use app.config.ts for app-wide defaults
• Use class prop for simple utility class additions
• Color placeholders like {color} are replaced at runtime
• Dark mode classes (dark:) work automatically with color mode
• Check component metadata for available theme slots