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:

• Identify component (e.g., "Button")

• Use mcp_nuxt-ui_get-component-metadata to see theme structure

• Provide ui prop example for requested customization

• Suggest global config if change should be app-wide

User wants to change brand colors:

• Explain semantic color system

• Show nuxt.config.ts theme.colors configuration

• Provide Tailwind color palette setup if needed

• Show component usage with new colors

User wants custom variants:

• Get component theme structure

• Show how to extend variants with ui prop

• 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