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/nuxt-v4-features.md

View on GitHub
# Nuxt v4 Features & Integration

## Overview

This guide covers Nuxt v4-specific features and how they integrate with Nuxt UI v4.

## Key Nuxt v4 Features

### 1. **Improved Performance**
- Faster build times with optimized Vite integration
- Enhanced hot module replacement (HMR)
- Better tree-shaking for smaller bundles

### 2. **Enhanced Type Safety**
- Automatic type generation with `nuxt prepare`
- Better TypeScript inference
- Type-safe component props

### 3. **Module System Updates**
- Simplified module registration
- Better module compatibility
- Enhanced plugin system

## Nuxt UI v4 Integration

### Installation

```bash
npm install @nuxt/ui tailwindcss
```

### Configuration

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  compatibilityDate: '2024-11-01'
})
```

### nuxt.config.ts Options

```typescript
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    // Component prefix (default: 'U')
    prefix: 'U',

    // Enable @nuxt/fonts module (default: true)
    fonts: true,

    // Enable color mode (default: true)
    colorMode: true,

    // Force Prose components without @nuxt/content
    prose: false,

    // Force Prose + Content components without @nuxt/content
    content: false,

    // Theme configuration
    theme: {
      // Dynamic color aliases (default: primary, secondary, success, info, warning, error)
      colors: ['primary', 'secondary', 'success', 'info', 'warning', 'error'],

      // Enable transitions on components (default: true)
      transitions: true,

      // Default color/size variants for all components (v4.1+)
      defaultVariants: {
        color: 'primary',
        size: 'md'
      },

      // Tailwind CSS prefix for utility classes (v4.2+)
      // Must match: @import "tailwindcss" prefix(tw);
      prefix: 'tw'
    },

    // Experimental features
    experimental: {
      // Automatic component detection for tree-shaking (v4.1+)
      // true = auto-detect, or array of component names to include
      componentDetection: false
    }
  }
})
```

### CSS Setup

```css
/* assets/css/main.css */
@import "tailwindcss";
@import "@nuxt/ui";

/* Optional: Custom theme */
@theme {
  --font-sans: 'Public Sans', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

/* Optional: Custom colors (define all shades 50-950) */
@theme static {
  --color-brand-50: #fef2f2;
  /* ... */
  --color-brand-950: #450a0a;
}
```

### With Tailwind Prefix

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
```

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

This prefixes all utility classes in Nuxt UI components:
```html
<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">

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

> **Note**: If using `@nuxt/fonts`, enable `fonts.processCSSVariables: true`.

### Auto-imports

Nuxt v4 auto-imports all Nuxt UI components and composables:
- Components: `UButton`, `UCard`, `UInput`, etc.
- Composables: `useToast`, `useColorMode`, etc.

## Best Practices

1. **Use TypeScript**: Full type safety with Nuxt v4
2. **Run `nuxt prepare`**: Generate types before development
3. **Leverage Auto-imports**: No need to manually import components
4. **Use `UApp` Wrapper**: Required for Nuxt UI to work properly

---

## Migration to v4.2.x

### Overview

Nuxt UI v4.2.x introduces several new features and a few breaking changes. Most applications will upgrade smoothly, but you should be aware of the changes below.

### New Components (v4.6)

- **ChatReasoning** - Collapsible AI reasoning/thinking process
- **ChatTool** - Collapsible AI tool invocation status
- **ChatShimmer** - Text shimmer animation for streaming states
- **AuthForm** - Pre-built login/register/password reset form
- **PinInput** - OTP/pin code input
- **FileUpload** - File upload input

### Upgrade Checklist

**Affected Components**: InputMenu, InputNumber, SelectMenu

Template refs for these components now return HTML elements directly instead of component instances.

**Before (v4.0/v4.1)**:
```vue
<template>
  <UInputMenu ref="inputRef" />
</template>

<script setup lang="ts">
const inputRef = ref()

onMounted(() => {
  // Access via .$el
  inputRef.value.$el.focus()
})
</script>
```

**After (v4.2+)**:
```vue
<template>
  <UInputMenu ref="inputRef" />
</template>

<script setup lang="ts">
const inputRef = ref<HTMLElement>()

onMounted(() => {
  // Direct HTML element access
  inputRef.value?.focus()
})
</script>
```

**Migration Steps**:
1. Remove all `.$el` accessors from affected components
2. Update TypeScript types from component refs to `HTMLElement`
3. Test all imperative DOM operations (focus, scroll, etc.)

#### 2. Composable Imports (v4.2.0)

Composable imports no longer require the `.js` extension.

**Before**:
```typescript
import { useToast } from '#ui/composables/useToast.js'
import { useNotification } from '#ui/composables/useNotification.js'
```

**After**:
```typescript
import { useToast } from '#ui/composables/useToast'
import { useNotification } from '#ui/composables/useNotification'
```

**Migration Steps**:
1. Search for `from '#ui/composables/*.js'` in your codebase
2. Remove `.js` extensions
3. Auto-imports are still recommended (no explicit import needed)

#### 3. Vite Theme Templates (v4.2.0)

Theme files are now properly generated outside the `.nuxt/` directory when using Vite plugin.

**Impact**: Minimal - theme customizations in `app.config.ts` now work correctly with Vite
**Action Required**: None - automatic improvement

### New Features

#### Tailwind CSS Prefix Support (v4.2+)

Configure a prefix for all Tailwind utility classes to avoid conflicts.

**Configuration**:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
```

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

**See**: `tailwind-prefix-guide.md` for complete guide

#### Component Virtualization (v4.1+)

Enable virtualization for large lists (1000+ items).

**Usage**:
```vue
<template>
  <UTable
    :rows="largeDataset"
    virtualize
  />
</template>
```

**Supported**: CommandPalette, InputMenu, SelectMenu, Table, Tree

**See**: `performance-optimization.md` for details

#### Experimental Component Detection (v4.1+)

Automatically detect which components are used and generate only necessary CSS.

**Configuration**:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  ui: {
    experimental: {
      componentDetection: true
    }
  }
})
```

**Result**: 70%+ CSS bundle size reduction

**See**: `performance-optimization.md` for details

### Upgrade Checklist

- [ ] Install both packages: `bun add @nuxt/ui tailwindcss`
- [ ] Search for `.$el` in template refs (InputMenu, InputNumber, SelectMenu)
- [ ] Remove `.$el` accessors, use direct element access
- [ ] Update composable imports (remove `.js` extensions)
- [ ] Install `@internationalized/date` if using InputDate/InputTime
- [ ] If using AI SDK, update to v5: `Chat` class replaces `useChat`
- [ ] Update chat rendering to use `message.parts` instead of `message.content`
- [ ] Import AI helpers from `ai` and `@nuxt/ui/utils/ai`
- [ ] Add `nested` and `name` props to child UForm components
- [ ] Test all form validations
- [ ] Test all imperative DOM operations (focus, etc.)
- [ ] Consider enabling component detection for production
- [ ] Review new components: ChatReasoning, ChatTool, ChatShimmer, AuthForm

### Common Migration Errors

See `COMMON_ERRORS_DETAILED.md` for:
- "Cannot read property 'focus' of undefined" error
- Template ref TypeScript errors
- Composable import errors

### Resources

- **Official Changelog**: https://ui.nuxt.com/releases
- **Migration Guide**: https://ui.nuxt.com/docs/getting-started/migration/v4
- **Component Detection**: `performance-optimization.md`
- **Prefix Guide**: `tailwind-prefix-guide.md`
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