Customization

Learn how to customize components to match your brand.

Theme Customization

Colors

Customize your theme colors in app.config.ts:

export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      neutral: 'slate'
    }
  }
})

Available color options:

primary: Main brand color
neutral: Gray scale colors
error: Error states
warning: Warning states
success: Success states
info: Informational states

Component-Level Customization

Use the ui prop to customize individual components:

<UButton
  label="Custom Button"
  :ui="{
    background: 'bg-gradient-to-r from-blue-500 to-purple-500',
    rounded: 'rounded-full',
    padding: 'px-8 py-4'
  }"
/>

Global Component Defaults

Override default component props globally in app.config.ts:

export default defineAppConfig({
  ui: {
    button: {
      default: {
        size: 'lg',
        color: 'primary',
        variant: 'solid'
      }
    },
    card: {
      default: {
        variant: 'subtle'
      }
    }
  }
})

CSS Customization

Custom Styles

Add custom styles in assets/css/main.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .custom-card {
    @apply rounded-2xl border border-gray-200 dark:border-gray-800;
    @apply bg-white dark:bg-gray-900;
    @apply shadow-sm hover:shadow-md transition-shadow;
  }
}

Tailwind Configuration

Extend Tailwind in tailwind.config.ts:

export default {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          // ... more shades
          900: '#0c4a6e'
        }
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif']
      }
    }
  }
}

Component Variants

Create custom variants for components:

<UButton
  variant="custom"
  :ui="{
    variant: {
      custom: 'bg-gradient-to-r from-pink-500 to-yellow-500 text-white'
    }
  }"
/>

Dark Mode

Automatic Dark Mode

Dark mode is automatically handled by Nuxt UI. Toggle it with:

<UButton
  icon="i-lucide-moon"
  @click="$colorMode.preference = 'dark'"
/>

Custom Dark Mode Styles

.custom-element {
  @apply bg-white dark:bg-gray-900;
  @apply text-gray-900 dark:text-white;
}

Icons

Using Icons

Icons are provided by @iconify-json packages:

<UIcon
  name="i-lucide-star"
  class="w-6 h-6"
/>

Custom Icon Collections

Install additional icon collections:

npm install @iconify-json/heroicons

Then use them:

<UIcon name="i-heroicons-star" />

Typography

Prose Styling

Content rendered through ContentRenderer automatically gets prose styling:

<ContentRenderer
  :value="page"
  class="prose prose-primary dark:prose-invert"
/>

Custom Typography

@layer base {
  h1 {
    @apply text-4xl font-bold tracking-tight;
  }
  
  h2 {
    @apply text-3xl font-semibold mt-8 mb-4;
  }
  
  p {
    @apply text-base leading-7 text-gray-600 dark:text-gray-400;
  }
}

Animation

Custom Animations

Add custom animations in your CSS:

@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.animate-fade-in-up {
  animation: fadeInUp 0.5s ease-out;
}

Transition Groups

<TransitionGroup
  name="list"
  tag="div"
  class="space-y-4"
>
  <UCard
    v-for="item in items"
    :key="item.id"
    v-bind="item"
  />
</TransitionGroup>

<style scoped>
.list-move,
.list-enter-active,
.list-leave-active {
  transition: all 0.5s ease;
}

.list-enter-from,
.list-leave-to {
  opacity: 0;
  transform: translateX(30px);
}
</style>

Best Practices

Keep customizations in app.config.ts for consistency across your application.

Avoid overriding too many default styles - it can make maintenance difficult.

Use Tailwind's utility classes whenever possible for better performance.

Component Examples

Practical examples of using components in your application.

API Reference

Complete API reference for composables and utilities.