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/tailwind-prefix-guide.md

View on GitHub
# Tailwind CSS Prefix Configuration (v4.2+)

**Feature**: Available since Nuxt UI v4.2.0
**Purpose**: Configure a prefix for all Tailwind utility classes to avoid conflicts with other CSS frameworks

---

## Overview

The `theme.prefix` option allows you to configure a prefix for all Tailwind CSS utility classes used by Nuxt UI components. This is essential when you need to use Nuxt UI alongside other CSS frameworks that might have conflicting class names.

**When to use**:
- Integrating Nuxt UI with legacy CSS frameworks
- Avoiding style conflicts in large applications
- Working with micro-frontends that share global styles
- Migrating incrementally from another UI framework

---

## Configuration

### Nuxt Application

**Step 1**: Configure the prefix in `nuxt.config.ts`

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'  // Use 'tw:' prefix for all utilities
    }
  }
})
```

**Step 2**: Add prefix to Tailwind CSS import

```css
/* app/assets/css/main.css */
@import "tailwindcss" prefix(tw);
@import "@nuxt/ui";
```

### Vue Application

**Step 1**: Configure the prefix in `vite.config.ts`

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

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        prefix: 'tw'
      }
    })
  ]
})
```

**Step 2**: Add prefix to Tailwind CSS import

```css
/* assets/main.css */
@import "tailwindcss" prefix(tw);
@import "@nuxt/ui";
```

---

## How It Works

### Automatic Class Prefixing

When you configure a prefix, Nuxt UI automatically prefixes **all utility classes** in component themes:

**Without prefix**:
```html
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>
```

**With prefix: `tw`**:
```html
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
```

### CSS Variables Remain Unprefixed

**Important**: CSS variables used by Nuxt UI components (like `--ui-primary`, `--ui-bg`, etc.) are **NOT** prefixed. Only utility classes are affected.

---

## Integration with @nuxt/fonts

If you're using the `@nuxt/fonts` module with a prefix, you'll need to enable `processCSSVariables`:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  },
  fonts: {
    processCSSVariables: true  // Required for prefix support
  }
})
```

**Why this is needed**: The `@nuxt/fonts` module needs to be aware of the prefix to correctly apply font utilities to Nuxt UI components.

**Reference**: [Nuxt Fonts - processCSSVariables](https://fonts.nuxt.com/get-started/configuration#processcssvariables)

---

## Before & After Examples

### Example 1: Button with Custom Styling

**Without prefix**:
```vue
<template>
  <UButton
    class="rounded-full bg-gradient-to-r from-blue-500 to-purple-500"
  >
    Gradient Button
  </UButton>
</template>
```

**With prefix: `tw`**:
```vue
<template>
  <UButton
    class="tw:rounded-full tw:bg-gradient-to-r tw:from-blue-500 tw:to-purple-500"
  >
    Gradient Button
  </UButton>
</template>
```

### Example 2: Card with Hover Effects

**Without prefix**:
```vue
<template>
  <UCard class="hover:shadow-lg transition-shadow duration-300">
    <h3 class="text-lg font-semibold">Card Title</h3>
    <p class="text-sm text-gray-600">Card description</p>
  </UCard>
</template>
```

**With prefix: `tw`**:
```vue
<template>
  <UCard class="tw:hover:shadow-lg tw:transition-shadow tw:duration-300">
    <h3 class="tw:text-lg tw:font-semibold">Card Title</h3>
    <p class="tw:text-sm tw:text-gray-600">Card description</p>
  </UCard>
</template>
```

### Example 3: Responsive Layout

**Without prefix**:
```vue
<template>
  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    <UCard v-for="item in items" :key="item.id">
      {{ item.title }}
    </UCard>
  </div>
</template>
```

**With prefix: `tw`**:
```vue
<template>
  <div class="tw:grid tw:grid-cols-1 md:tw:grid-cols-2 lg:tw:grid-cols-3 tw:gap-4">
    <UCard v-for="item in items" :key="item.id">
      {{ item.title }}
    </UCard>
  </div>
</template>
```

---

## Common Use Cases

### Use Case 1: Legacy Bootstrap Integration

When integrating Nuxt UI into an existing Bootstrap application:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    theme: {
      prefix: 'nu'  // "nuxt-ui" prefix to avoid Bootstrap conflicts
    }
  }
})
```

Now all Nuxt UI utilities use `nu:` prefix:
```html
<!-- Bootstrap classes (unprefixed) -->
<div class="container">
  <!-- Nuxt UI classes (prefixed) -->
  <UButton class="nu:mt-4 nu:px-4 nu:py-2">Submit</UButton>
</div>
```

### Use Case 2: Micro-Frontend Architecture

In a micro-frontend setup where multiple teams use different UI frameworks:

```ts
// Team A's Nuxt UI config
export default defineNuxtConfig({
  ui: {
    theme: {
      prefix: 'team-a'
    }
  }
})
```

### Use Case 3: Incremental Migration

When migrating from another framework (e.g., Element UI, Ant Design):

```ts
export default defineNuxtConfig({
  ui: {
    theme: {
      prefix: 'v2'  // New Nuxt UI components use v2: prefix
    }
  }
})
```

This allows gradual migration:
```vue
<template>
  <div>
    <!-- Old framework (unprefixed) -->
    <el-button type="primary">Old Button</el-button>

    <!-- New Nuxt UI (prefixed) -->
    <UButton class="v2:mt-4" color="primary">New Button</UButton>
  </div>
</template>
```

---

## Troubleshooting

### Components Not Styled

**Problem**: Nuxt UI components appear unstyled after adding prefix

**Solution**: Ensure both config and CSS import have matching prefix:

```ts
// ❌ INCORRECT: Config has prefix but CSS doesn't
// nuxt.config.ts
ui: { theme: { prefix: 'tw' } }

/* main.css - MISSING prefix! */
@import "tailwindcss";  // ❌ No prefix
@import "@nuxt/ui";
```

```ts
// ✅ CORRECT: Both config and CSS have prefix
// nuxt.config.ts
ui: { theme: { prefix: 'tw' } }

/* main.css - WITH prefix */
@import "tailwindcss" prefix(tw);  // ✅ Prefix matches
@import "@nuxt/ui";
```

### CSS Variables Not Working

**Problem**: Component themes using CSS variables aren't working

**Cause**: CSS variables are NOT prefixed, only utility classes

**Solution**: Don't prefix CSS variable references:

```vue
<template>
  <!-- ✅ CORRECT: Utilities prefixed, CSS vars unprefixed -->
  <div class="tw:bg-[var(--ui-primary)] tw:text-white">
    Content
  </div>

  <!-- ❌ INCORRECT: Trying to prefix CSS variables -->
  <div class="tw:bg-[var(--tw:ui-primary)]">
    Content
  </div>
</template>
```

### @nuxt/fonts Issues

**Problem**: Font utilities not working with prefix

**Solution**: Enable `processCSSVariables`:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    theme: {
      prefix: 'tw'
    }
  },
  fonts: {
    processCSSVariables: true  // ← Add this
  }
})
```

---

## Performance Impact

**Build Time**: Negligible impact (<1% increase)
**Runtime**: No impact - prefix is resolved at build time
**Bundle Size**: Slightly larger CSS file due to longer class names (~2-5% increase)

**Recommendation**: Only use prefix when necessary (conflict avoidance). If building a new application with Nuxt UI only, skip the prefix.

---

## Reference

- **Official Docs**: [Nuxt UI - theme.prefix](https://ui.nuxt.com/docs/getting-started/installation#theme-prefix)
- **Tailwind Prefix**: [Using the prefix option](https://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option)
- **Nuxt Fonts**: [processCSSVariables](https://fonts.nuxt.com/get-started/configuration#processcssvariables)
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