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)

export 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)

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

3. Component Level (ui prop)

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

4. Utility Classes (class prop)

<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

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

// 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:

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

<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

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

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

Responsive Theming

<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