Skip to content

secondsky/claude-skills / plugins/nuxt-ui-v4/skills/nuxt-ui-v4

nuxt-ui-v4

Verified

Nuxt UI v4 component library for building Nuxt v4 applications. 125+ accessible components with Tailwind v4, Reka UI, dark mode, theming. Use for dashboards, forms, overlays, editors, page layouts, pricing pages, or encountering component, theming, or TypeScript errors.

FileKindSize
SKILL.mdskill md13.0 KB
references/COMMON_ERRORS_DETAILED.mdmarkdown24.7 KB
references/accessibility-patterns.mdmarkdown822 B
references/ai-sdk-v5-integration.mdmarkdown6.4 KB
references/auth-form.mdmarkdown6.4 KB
references/chat-components.mdmarkdown13.2 KB
references/chat-reasoning.mdmarkdown3.0 KB
references/chat-shimmer.mdmarkdown1.6 KB
references/chat-tool.mdmarkdown3.6 KB
references/command-palette-setup.mdmarkdown1.1 KB
references/common-components.mdmarkdown1.2 KB
references/component-theming-guide.mdmarkdown13.2 KB
references/composables-guide.mdmarkdown908 B
references/content-components.mdmarkdown7.3 KB
references/css-variables-reference.mdmarkdown14.9 KB
references/dark-mode-guide.mdmarkdown10.9 KB
references/dashboard-components.mdmarkdown8.1 KB
references/data-display-components.mdmarkdown11.7 KB
references/design-system-guide.mdmarkdown16.1 KB
references/editor-components.mdmarkdown7.9 KB
references/feedback-components-reference.mdmarkdown11.4 KB
references/form-advanced-patterns.mdmarkdown1.7 KB
references/form-components-reference.mdmarkdown14.0 KB
references/form-validation-patterns.mdmarkdown6.4 KB
references/i18n-integration.mdmarkdown12.8 KB
references/icon-system-guide.mdmarkdown14.5 KB
references/layout-components-reference.mdmarkdown9.5 KB
references/loading-feedback-patterns.mdmarkdown1.0 KB
references/navigation-components-reference.mdmarkdown8.8 KB
references/nuxt-content-integration.mdmarkdown15.7 KB
references/nuxt-v4-features.mdmarkdown8.0 KB
references/overlay-decision-guide.mdmarkdown1.3 KB
references/page-layout-components.mdmarkdown8.4 KB
references/performance-optimization.mdmarkdown12.8 KB
references/pricing-components.mdmarkdown7.7 KB
references/responsive-patterns.mdmarkdown795 B
references/semantic-color-system.mdmarkdown1.3 KB
references/tailwind-prefix-guide.mdmarkdown7.6 KB
references/typescript-setup.mdmarkdown10.8 KB
scripts/check-versions.shexecutablescript1.3 KB
templates/app.config.tsscript2.5 KB
templates/app.vueother1.1 KB
templates/components/ui-avatar-badge.vueother7.7 KB
templates/components/ui-card-layouts.vueother5.9 KB
templates/components/ui-carousel-gallery.vueother1.4 KB
templates/components/ui-chat-full.vueother3.4 KB
templates/components/ui-chat-interface.vueother8.8 KB
templates/components/ui-command-palette.vueother1.8 KB
templates/components/ui-content-prose.vueother7.2 KB
templates/components/ui-dark-mode-toggle.vueother7.4 KB
templates/components/ui-data-table.vueother7.1 KB
templates/components/ui-drawer-mobile.vueother5.2 KB
templates/components/ui-dropdown-menu.vueother6.3 KB
templates/components/ui-empty-state.vueother5.2 KB
templates/components/ui-feedback-states.vueother6.2 KB
templates/components/ui-form-example.vueother4.5 KB
templates/components/ui-input-date.vueother5.2 KB
templates/components/ui-input-time.vueother5.8 KB
templates/components/ui-modal-dialog.vueother8.0 KB
templates/components/ui-navigation-tabs.vueother7.2 KB
templates/components/ui-popover-tooltip.vueother2.6 KB
templates/components/ui-toast-notifications.vueother8.9 KB
templates/composables/useAIChat.tsscript2.9 KB
templates/composables/useI18nForm.tsscript9.6 KB
templates/composables/useNuxtUITheme.tsscript2.4 KB
templates/layouts/dashboard.vueother3.7 KB
templates/nuxt.config.tsscript1.3 KB
templates/pages/landing.vueother5.9 KB

references/component-theming-guide.md

View on GitHub
# Component Theming Guide

## Customization Hierarchy (Order of Specificity)

1. **Global Config** (`app.config.ts`)
2. **Component `ui` Prop** (per-instance)
3. **Slot `class` Prop** (per-element)

## Global Theming

```typescript
export default defineAppConfig({
  ui: {
    theme: {
      defaultVariants: {
        Button: { size: 'md', color: 'primary' },
        Input: { size: 'md', variant: 'outline' }
      }
    }
  }
})
```

## Component-Level

```vue
<UButton :ui="{ base: 'font-bold', rounded: 'rounded-full' }">
  Custom Button
</UButton>
```

## Slot-Level

```vue
<UCard :ui="{ header: 'bg-primary text-white' }">
  <template #header>Header</template>
</UCard>
```

---

## Understanding Slots

### What Are Slots?

Slots are **distinct HTML elements or sections** within a component. Each slot can be styled independently.

**Example: UCard Component Structure**
```vue
<UCard>
  <!-- root slot: The outer container -->
  <div class="root-slot">
    <!-- header slot: Optional header section -->
    <div class="header-slot">
      <slot name="header" />
    </div>

    <!-- body slot: Main content area -->
    <div class="body-slot">
      <slot />  <!-- Default slot -->
    </div>

    <!-- footer slot: Optional footer section -->
    <div class="footer-slot">
      <slot name="footer" />
    </div>
  </div>
</UCard>
```

### Typical Slot Names

Most components follow these patterns:

**Container Components (Card, Modal, Drawer):**
- `root` - Outer container
- `header` - Top section
- `body` - Main content
- `footer` - Bottom section

**Form Components (Input, Select):**
- `root` - Wrapper element
- `base` - Input element itself
- `leading` - Icon/content before input
- `trailing` - Icon/content after input
- `label` - Label element
- `hint` - Helper text
- `error` - Error message

**Button Component:**
- `root` or `base` - Button element
- `leading` - Leading icon slot
- `label` - Text label slot
- `trailing` - Trailing icon slot

### Styling Individual Slots

```vue
<template>
  <UCard
    :ui="{
      root: 'shadow-lg border-2 border-primary',
      header: 'bg-primary text-white p-6',
      body: 'p-6 bg-elevated',
      footer: 'bg-muted p-4 border-t border-default'
    }"
  >
    <template #header>
      <h2>Card Title</h2>
    </template>

    <p>Card content goes here</p>

    <template #footer>
      <UButton>Action</UButton>
    </template>
  </UCard>
</template>
```

**Result:** Each section has its own independent styling.

---

## Variants System

### What Are Variants?

Variants map **component props** to **style definitions**. They enable dynamic styling based on prop values.

**Example: Avatar Size Variants**
```typescript
variants: {
  size: {
    xs: { root: 'size-6 text-xs' },
    sm: { root: 'size-7 text-sm' },
    md: { root: 'size-8 text-base' },  // default
    lg: { root: 'size-9 text-lg' },
    xl: { root: 'size-10 text-xl' }
  }
}
```

**Usage:**
```vue
<template>
  <UAvatar size="sm" />  <!-- Uses 'sm' variant: size-7 text-sm -->
  <UAvatar size="lg" />  <!-- Uses 'lg' variant: size-9 text-lg -->
  <UAvatar />            <!-- Uses default 'md': size-8 text-base -->
</template>
```

### How Variants Work

1. **Component receives prop** (e.g., `size="lg"`)
2. **Variant system looks up** the size variant
3. **Applies corresponding classes** to relevant slots

### Multiple Variants Example

Components often have multiple variant props:

```typescript
// Button variants
variants: {
  size: {
    xs: { root: 'px-2 py-1 text-xs' },
    sm: { root: 'px-3 py-1.5 text-sm' },
    md: { root: 'px-4 py-2 text-base' },
    lg: { root: 'px-5 py-2.5 text-lg' }
  },
  variant: {
    solid: { root: 'bg-primary text-white' },
    outline: { root: 'border border-primary text-primary bg-transparent' },
    ghost: { root: 'bg-transparent text-primary hover:bg-primary/10' },
    link: { root: 'bg-transparent text-primary underline' }
  },
  color: {
    primary: { root: 'theme-primary' },
    success: { root: 'theme-success' },
    error: { root: 'theme-error' }
  }
}
```

**Usage:**
```vue
<template>
  <!-- Combines size + variant + color variants -->
  <UButton
    size="lg"
    variant="outline"
    color="success"
  >
    Large Outline Success Button
  </UButton>
</template>
```

### Default Variants

Set defaults globally for all component instances:

```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    theme: {
      defaultVariants: {
        Button: {
          size: 'md',       // All buttons default to medium
          variant: 'solid',  // All buttons default to solid
          color: 'primary'   // All buttons default to primary color
        },
        Input: {
          size: 'md',
          variant: 'outline'
        }
      }
    }
  }
})
```

Now every `<UButton>` uses these defaults unless overridden:

```vue
<UButton>              <!-- md + solid + primary -->
<UButton size="lg">    <!-- lg + solid + primary -->
<UButton variant="ghost"> <!-- md + ghost + primary -->
```

---

## Compound Variants

### What Are Compound Variants?

Compound variants apply styles when **multiple conditions** are met simultaneously.

**Example: Button with Primary Color + Large Size**
```typescript
compoundVariants: [
  {
    color: 'primary',
    size: 'lg',
    class: 'shadow-lg font-semibold'
  },
  {
    variant: 'outline',
    color: 'error',
    class: 'border-2 hover:bg-error/10'
  }
]
```

**Result:**
```vue
<!-- Applies compound variant: shadow-lg font-semibold -->
<UButton color="primary" size="lg">
  Large Primary Button
</UButton>

<!-- Applies compound variant: border-2 hover:bg-error/10 -->
<UButton variant="outline" color="error">
  Outline Error Button
</UButton>

<!-- No compound variant applied -->
<UButton color="primary" size="md">
  Medium Primary Button
</UButton>
```

### Use Cases for Compound Variants

**1. Enhanced Emphasis**
```typescript
compoundVariants: [
  {
    color: 'error',
    variant: 'solid',
    class: 'shadow-error-md animate-pulse'  // Extra attention for destructive actions
  }
]
```

**2. Responsive Adjustments**
```typescript
compoundVariants: [
  {
    size: 'lg',
    variant: 'solid',
    class: 'md:px-8 md:py-4'  // Larger padding on desktop for large solid buttons
  }
]
```

**3. Accessibility Enhancements**
```typescript
compoundVariants: [
  {
    variant: 'ghost',
    color: 'neutral',
    class: 'focus:ring-2 focus:ring-offset-2'  // Extra focus visibility for subtle buttons
  }
]
```

---

## `class` vs `ui` Prop

### Critical Distinction

**`class` Prop:**
- Targets **root/base slot ONLY**
- Simple string of classes
- Cannot target other slots

**`ui` Prop:**
- Targets **ANY slot**
- Object with slot names as keys
- Full component customization

### Examples

```vue
<template>
  <!-- ✅ class prop: Styles root element only -->
  <UButton class="w-full">
    Full Width Button
  </UButton>
  <!-- Result: <button class="w-full ...">...</button> -->

  <!-- ✅ ui prop: Styles multiple slots -->
  <UButton
    :ui="{
      root: 'w-full',
      leading: 'size-5',
      label: 'font-bold'
    }"
  >
    <template #leading>
      <UIcon name="i-lucide-star" />
    </template>
    Customized Button
  </UButton>

  <!-- ❌ WRONG: class prop cannot target leading slot -->
  <UButton class="leading:size-5">
    <!-- This won't work -->
  </UButton>
</template>
```

### When to Use Each

**Use `class` when:**
- Styling root element only
- Simple utility class additions
- Quick one-off styling

**Use `ui` when:**
- Customizing multiple slots
- Targeting specific internal elements
- Complex component styling
- Building reusable variants

### Combining Both

You can use both together:

```vue
<template>
  <UButton
    class="w-full md:w-auto"
    :ui="{
      root: 'shadow-lg',
      label: 'font-semibold'
    }"
  >
    Hybrid Styling
  </UButton>
</template>
```

**Result:** `class` and `ui.root` both apply to root element, `ui.label` applies to label slot.

---

## Vue-Only Configuration

### For Vue (Not Nuxt) Projects

If using **Vue without Nuxt**, configure in `vite.config.ts`:

**vite.config.ts:**
```typescript
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        // Theme configuration
        colors: {
          primary: 'indigo',
          secondary: 'purple',
          success: 'green',
          error: 'red'
        },

        // Default variants
        theme: {
          defaultVariants: {
            Button: {
              size: 'md',
              variant: 'solid'
            }
          }
        },

        // Global component styling
        button: {
          slots: {
            root: 'font-semibold transition-all',
            leading: 'size-5'
          },
          variants: {
            size: {
              xs: { root: 'px-2 py-1 text-xs' },
              sm: { root: 'px-3 py-1.5 text-sm' },
              md: { root: 'px-4 py-2 text-base' },
              lg: { root: 'px-6 py-3 text-lg' }
            }
          }
        }
      }
    })
  ]
})
```

### Nuxt vs Vue Configuration

| Feature | Nuxt | Vue (vite.config.ts) |
|---------|------|----------------------|
| Runtime Colors | `app.config.ts` | `vite.config.ts` |
| Default Variants | `app.config.ts` | `vite.config.ts` |
| Global Slots | `app.config.ts` | `vite.config.ts` |
| Hot Reload | Yes | Requires restart |

---

## Advanced Patterns

### Conditional Slot Styling

```vue
<script setup lang="ts">
const hasError = ref(false)

const cardUi = computed(() => ({
  root: hasError.value ? 'border-2 border-error' : 'border border-default',
  header: hasError.value ? 'bg-error/10 text-error' : 'bg-default'
}))
</script>

<template>
  <UCard :ui="cardUi">
    <template #header>
      {{ hasError ? 'Error State' : 'Normal State' }}
    </template>
    <p>Content</p>
  </UCard>
</template>
```

### Extending Component Variants

```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      variants: {
        // Add custom size
        size: {
          '2xl': { root: 'px-8 py-4 text-2xl' }
        },
        // Add custom variant
        variant: {
          gradient: {
            root: 'bg-gradient-to-r from-primary to-secondary text-white'
          }
        }
      }
    }
  }
})
```

**Usage:**
```vue
<UButton size="2xl" variant="gradient">
  Custom Gradient Button
</UButton>
```

### Responsive Variants with Tailwind

```vue
<template>
  <UButton
    :ui="{
      root: 'w-full md:w-auto',
      label: 'text-sm md:text-base'
    }"
  >
    Responsive Button
  </UButton>
</template>
```

---

## Best Practices

### 1. Prefer Global Defaults

```typescript
// ✅ GOOD: Set once globally
// app.config.ts
defaultVariants: {
  Button: { size: 'md', variant: 'solid' }
}

// ❌ AVOID: Repeating on every instance
<UButton size="md" variant="solid">...</UButton>
<UButton size="md" variant="solid">...</UButton>
<UButton size="md" variant="solid">...</UButton>
```

### 2. Use `ui` Prop for Complex Styling

```vue
<!-- ✅ GOOD: Use ui prop for multi-slot styling -->
<UCard
  :ui="{
    root: 'shadow-xl',
    header: 'bg-primary text-white',
    body: 'prose'
  }"
/>

<!-- ❌ AVOID: class prop can't target slots -->
<UCard class="shadow-xl header:bg-primary body:prose" />
```

### 3. Create Composables for Reusable Styles

```typescript
// composables/useCardStyles.ts
export const useCardStyles = (variant: 'default' | 'error' | 'success') => {
  const styles = {
    default: {
      root: 'border border-default',
      header: 'bg-elevated'
    },
    error: {
      root: 'border-2 border-error',
      header: 'bg-error/10 text-error'
    },
    success: {
      root: 'border-2 border-success',
      header: 'bg-success/10 text-success'
    }
  }

  return styles[variant]
}
```

**Usage:**
```vue
<script setup lang="ts">
const cardStyles = useCardStyles('error')
</script>

<template>
  <UCard :ui="cardStyles">
    <template #header>Error Card</template>
    <p>Content</p>
  </UCard>
</template>
```

### 4. Document Custom Variants

When adding custom variants, document them:

```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    button: {
      variants: {
        /**
         * Custom button sizes
         * - xs: Extra small (mobile)
         * - 2xl: Extra large (hero CTAs)
         */
        size: {
          xs: { root: 'px-1.5 py-0.5 text-xs' },
          '2xl': { root: 'px-8 py-4 text-2xl' }
        }
      }
    }
  }
})
```

---

## Troubleshooting

### Styles Not Applying

**Problem:** `ui` prop styles don't appear.

**Solution:** Check slot names match component structure. Use browser DevTools to inspect actual slot names.

### Conflicting Styles

**Problem:** Global and component styles conflict.

**Solution:** Remember the hierarchy:
1. Global config (lowest priority)
2. Component `ui` prop
3. Slot `class` prop (highest priority)

### Variant Not Working

**Problem:** Custom variant doesn't apply.

**Solution:** Ensure variant is registered in global config and prop name matches:

```typescript
// app.config.ts
ui: {
  button: {
    variants: {
      customSize: {  // ← Must match prop name
        huge: { root: 'px-10 py-6' }
      }
    }
  }
}
```

```vue
<UButton customSize="huge">  <!-- ← Must match config -->
```

---

**Last Updated**: 2025-01-09
**Nuxt UI Version**: 4.0.0
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall