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/COMMON_ERRORS_DETAILED.md

View on GitHub
# Nuxt UI v4 - Common Errors & Detailed Solutions

Complete troubleshooting guide for Nuxt UI v4 with 25 common errors and their solutions.

**Last Updated**: 2026-03-30

---

## Error Index

Jump to specific errors:
- [1. Missing UApp Wrapper](#1-missing-uapp-wrapper)
- [2. Module Not Registered](#2-module-not-registered)
- [3. CSS Import Order](#3-css-import-order)
- [4. useToast Not Imported](#4-usetoast-not-imported)
- [5. Toast Positioning Conflicts](#5-toast-positioning-conflicts)
- [6. CommandPalette Shortcuts Not Working](#6-commandpalette-shortcuts-not-working)
- [7. Carousel Not Displaying](#7-carousel-not-displaying)
- [8. Drawer Not Responsive](#8-drawer-not-responsive)
- [9. Modal vs Dialog Confusion](#9-modal-vs-dialog-confusion)
- [10. Popover Positioning Issues](#10-popover-positioning-issues)
- [11. Skeleton Dimensions Wrong](#11-skeleton-dimensions-wrong)
- [12. Card Slots Not Working](#12-card-slots-not-working)
- [13. Avatar Fallback Missing](#13-avatar-fallback-missing)
- [14. Badge Positioning Wrong](#14-badge-positioning-wrong)
- [15. Form Nested Prop Missing](#15-form-nested-prop-missing)
- [16. Table Pagination State](#16-table-pagination-state)
- [17. Color Mode Not Persisting](#17-color-mode-not-persisting)
- [18. TypeScript Types Not Generated](#18-typescript-types-not-generated)
- [19. Theme Variants Not Applying](#19-theme-variants-not-applying)
- [20. Responsive Patterns Broken](#20-responsive-patterns-broken)
- [21. Cannot read property 'focus' of undefined (v4.2+)](#21-cannot-read-property-focus-of-undefined-v42)
- [22. Missing tailwindcss Package](#22-missing-tailwindcss-package)
- [23. useChat Not Found (AI SDK v5)](#23-usechat-not-found-ai-sdk-v5)
- [24. Chat messages.content Not Working](#24-chat-messagescontent-not-working)
- [25. Form Nested Validation Not Inherited](#25-form-nested-validation-not-inherited)

---

## 1. Missing UApp Wrapper

**Error**: Components not rendering or styles missing

**Symptoms**:
- Nuxt UI components render without styles
- Dark mode not working
- Components appear as unstyled HTML
- Console errors about missing context

**Root Cause**: `<UApp>` provides the required Vue context for all Nuxt UI components, including color mode, toast container, and global styles.

**Solution**: Wrap your entire app with `<UApp>` in `app.vue`:

```vue
<!-- app.vue -->
<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>
```

**Why this works**: `<UApp>` initializes:
- Color mode provider (`useColorMode`)
- Toast notification container
- Global CSS variables
- Component context

---

## 2. Module Not Registered

**Error**: "Cannot find module @nuxt/ui" or components not recognized

**Symptoms**:
- TypeScript errors for component names
- Components don't render
- Module import errors in console
- Auto-imports not working

**Root Cause**: `@nuxt/ui` module not registered in Nuxt configuration.

**Solution**: Add module to `nuxt.config.ts`:

```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})
```

**Additional troubleshooting**:
```bash
# Verify installation
bun list | grep @nuxt/ui

# Reinstall if necessary
bun remove @nuxt/ui
bun add @nuxt/ui

# Clear .nuxt cache
rm -rf .nuxt
bunx nuxt prepare
```

---

## 3. CSS Import Order

**Error**: Styles not applying correctly, Tailwind classes overridden

**Symptoms**:
- Component styles look broken
- Tailwind utilities don't work
- Dark mode colors incorrect
- Custom theme not applying

**Root Cause**: Incorrect CSS import order causes Tailwind to override Nuxt UI styles.

**Solution**: Import Tailwind CSS before Nuxt UI in your global CSS file:

```vue
<!-- app.vue or layouts/default.vue -->
<style>
@import "tailwindcss";  /* First - base Tailwind */
@import "@nuxt/ui";     /* Second - Nuxt UI components */
</style>
```

**Why this matters**: Nuxt UI's component styles should override Tailwind's base styles to ensure proper theming.

---

## 4. useToast Not Imported

**Error**: "useToast is not defined" or "Cannot read property 'add' of undefined"

**Symptoms**:
- Runtime error when calling toast functions
- TypeScript error in IDE
- Toast notifications don't appear

**Root Cause**: `useToast` composable not imported (not auto-imported in some contexts).

**Solution**: Explicitly import or use auto-import:

```typescript
// Auto-import (recommended in components)
const { add } = useToast()

add({
  title: 'Success',
  description: 'Operation completed'
})

// Explicit import (needed in utils/stores)
import { useToast } from '#app'

const toast = useToast()
toast.add({ title: 'Message' })
```

---

## 5. Toast Positioning Conflicts

**Error**: Toasts appearing in wrong location or overlapping with other UI

**Symptoms**:
- Toasts appear in unexpected corner
- Multiple toasts stack incorrectly
- Toasts hidden behind other elements
- Z-index conflicts

**Root Cause**: Default toast position conflicts with app layout or not configured.

**Solution**: Configure position in `app.config.ts`:

```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    toast: {
      position: 'top-right', // Options: top-right, top-left, bottom-right, bottom-left, top-center, bottom-center
      container: 'fixed z-50 inset-0 pointer-events-none p-4',
      wrapper: 'w-full pointer-events-auto'
    }
  }
})
```

**Per-toast positioning**:
```typescript
const { add } = useToast()

add({
  title: 'Custom positioned',
  position: 'bottom-center' // Override global setting
})
```

---

## 6. CommandPalette Shortcuts Not Working

**Error**: Keyboard shortcuts (Cmd+K) not triggering CommandPalette

**Symptoms**:
- Keyboard shortcuts don't open palette
- Other shortcuts conflict
- Shortcuts work in some components but not others

**Root Cause**: Shortcuts not registered with `defineShortcuts` composable.

**Solution**: Use `defineShortcuts` composable:

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

defineShortcuts({
  'meta_k': {
    handler: () => {
      isOpen.value = !isOpen.value
    }
  },
  'ctrl_k': { // Alternative for non-Mac
    handler: () => {
      isOpen.value = !isOpen.value
    }
  }
})
</script>

<template>
  <UCommandPalette v-model="isOpen" :groups="groups" />
</template>
```

**Global shortcuts** (in `app.vue`):
```typescript
defineShortcuts({
  'escape': () => closeAllModals(),
  'meta_/': () => openSearch()
})
```

---

## 7. Carousel Not Displaying

**Error**: Carousel components not working or slides not navigating

**Symptoms**:
- Carousel renders blank
- Slides don't transition
- Navigation arrows don't work
- Console error about Embla

**Root Cause**: Missing `embla-carousel-vue` peer dependency.

**Solution**: Install Embla Carousel:

```bash
bun add embla-carousel-vue
```

**Usage**:
```vue
<template>
  <UCarousel :items="slides" />
</template>

<script setup lang="ts">
const slides = [
  { id: 1, content: 'Slide 1' },
  { id: 2, content: 'Slide 2' },
  { id: 3, content: 'Slide 3' }
]
</script>
```

---

## 8. Drawer Not Responsive

**Error**: Drawer doesn't adapt to mobile screen sizes

**Symptoms**:
- Drawer too wide on mobile
- Drawer opens from wrong side
- Backdrop doesn't cover full screen on mobile

**Root Cause**: No responsive breakpoint handling for overlay components.

**Solution**: Use responsive patterns with `useMediaQuery`:

```vue
<template>
  <!-- Desktop: Modal, Mobile: Drawer -->
  <UModal v-if="!isMobile" v-model="isOpen">
    <UCard>
      <p>Desktop modal content</p>
    </UCard>
  </UModal>

  <UDrawer v-else v-model="isOpen" side="right">
    <UCard>
      <p>Mobile drawer content</p>
    </UCard>
  </UDrawer>
</template>

<script setup lang="ts">
const isOpen = ref(false)
const isMobile = useMediaQuery('(max-width: 768px)')
</script>
```

**Alternative: Sheet for mobile-first**:
```vue
<USheet v-model="isOpen">
  <!-- Automatically becomes bottom sheet on mobile -->
</USheet>
```

---

## 9. Modal vs Dialog Confusion

**Error**: Using wrong overlay component for the use case

**Symptoms**:
- Overlay doesn't behave as expected
- Too much or too little functionality
- Accessibility issues

**Root Cause**: Not understanding component purposes.

**Decision Guide**:

| Component | Use Case | Features |
|-----------|----------|----------|
| **Modal** | Full-featured overlays, forms, content | Backdrop, keyboard nav, header/footer slots |
| **Dialog** | Confirmation prompts, alerts | Simple yes/no, auto-focus confirm button |
| **Drawer** | Side panels, filters, navigation | Slides from edge, mobile-friendly |
| **Popover** | Contextual info, tooltips with interaction | Positioned relative to trigger, auto-dismiss |
| **Sheet** | Bottom drawers, mobile actions | Bottom slide-up, iOS-style |
| **Tooltip** | Hover-only info | No interaction, auto-hide on unhover |

**Examples**:

```vue
<!-- ✓ Modal: Complex form -->
<UModal v-model="showEditForm">
  <UForm @submit="onSubmit">
    <UFormGroup label="Name">
      <UInput v-model="name" />
    </UFormGroup>
  </UForm>
</UModal>

<!-- ✓ Dialog: Confirmation -->
<UDialog
  title="Delete item?"
  description="This action cannot be undone"
  :actions="[
    { label: 'Cancel', color: 'neutral' },
    { label: 'Delete', color: 'red', onClick: deleteItem }
  ]"
/>

<!-- ✓ Drawer: Filters -->
<UDrawer v-model="showFilters" side="right">
  <UCard>
    <template #header>Filters</template>
    <!-- Filter options -->
  </UCard>
</UDrawer>

<!-- ✓ Popover: Contextual actions -->
<UPopover>
  <UButton>Options</UButton>
  <template #panel>
    <div class="p-2">
      <UButton variant="ghost">Edit</UButton>
      <UButton variant="ghost">Delete</UButton>
    </div>
  </template>
</UPopover>
```

---

## 10. Popover Positioning Issues

**Error**: Popover appears in wrong position or gets cut off

**Symptoms**:
- Popover off-screen
- Popover covers trigger button
- Incorrect alignment

**Root Cause**: Default positioning doesn't account for viewport edges or scroll.

**Solution**: Configure placement and flip behavior:

```vue
<UPopover
  placement="bottom-start"
  :flip="true"
  :offset="8"
>
  <UButton>Trigger</UButton>
  <template #panel>
    <div class="p-4">Content</div>
  </template>
</UPopover>
```

**All placement options**:
- `top`, `top-start`, `top-end`
- `bottom`, `bottom-start`, `bottom-end`
- `left`, `left-start`, `left-end`
- `right`, `right-start`, `right-end`

**Auto-flip** (default `true`): Automatically flips to opposite side if no space

---

## 11. Skeleton Dimensions Wrong

**Error**: Skeleton loader doesn't match actual content dimensions

**Symptoms**:
- Layout shift when content loads
- Skeleton too small or too large
- Poor loading UX

**Root Cause**: Skeleton dimensions don't match real content.

**Solution**: Match exact dimensions of actual elements:

```vue
<template>
  <!-- Loading state -->
  <div v-if="loading">
    <USkeleton class="h-12 w-64 mb-4" /> <!-- Matches heading -->
    <USkeleton class="h-4 w-full mb-2" /> <!-- Matches paragraph -->
    <USkeleton class="h-4 w-3/4" /> <!-- Matches paragraph -->
  </div>

  <!-- Actual content -->
  <div v-else>
    <h1 class="h-12 w-64 mb-4">{{ title }}</h1>
    <p class="h-4 w-full mb-2">{{ paragraph1 }}</p>
    <p class="h-4 w-3/4">{{ paragraph2 }}</p>
  </div>
</template>
```

**Card skeleton example**:
```vue
<UCard v-if="loading">
  <USkeleton class="h-40 w-full mb-4" /> <!-- Image -->
  <USkeleton class="h-6 w-3/4 mb-2" /> <!-- Title -->
  <USkeleton class="h-4 w-full" /> <!-- Description -->
</UCard>
```

---

## 12. Card Slots Not Working

**Error**: Card header/footer not rendering

**Symptoms**:
- Header or footer content missing
- Slots don't appear
- Layout broken

**Root Cause**: Incorrect slot syntax or slot names.

**Solution**: Use proper named slot syntax:

```vue
<UCard>
  <template #header>
    <div class="flex items-center justify-between">
      <h3>Card Header</h3>
      <UButton size="xs">Action</UButton>
    </div>
  </template>

  <!-- Default slot: card body -->
  <p>This is the main card content</p>

  <template #footer>
    <div class="flex gap-2">
      <UButton>Cancel</UButton>
      <UButton color="primary">Save</UButton>
    </div>
  </template>
</UCard>
```

**Available slots**:
- `header`: Top section
- `default`: Main content (unnamed slot)
- `footer`: Bottom section

---

## 13. Avatar Fallback Missing

**Error**: Broken image icon when avatar image fails to load

**Symptoms**:
- Broken image placeholder
- No fallback text
- Poor UX for missing avatars

**Root Cause**: No `alt` text provided for fallback initials.

**Solution**: Add `alt` text (generates initials automatically):

```vue
<!-- ✓ With fallback -->
<UAvatar
  src="/nonexistent.jpg"
  alt="John Doe"
/>
<!-- Shows "JD" if image fails -->

<!-- ✗ Without fallback -->
<UAvatar src="/nonexistent.jpg" />
<!-- Shows broken image icon -->
```

**Avatar with explicit initials**:
```vue
<UAvatar :text="getUserInitials(user.name)" />
```

**Avatar groups**:
```vue
<UAvatarGroup :max="3">
  <UAvatar v-for="user in users" :key="user.id" :alt="user.name" />
</UAvatarGroup>
```

---

## 14. Badge Positioning Wrong

**Error**: Badge not positioned correctly on buttons/avatars

**Symptoms**:
- Badge inside element instead of overlaid
- Badge not in corner
- Badge positioning breaks on resize

**Root Cause**: Missing `relative` positioning on parent element.

**Solution**: Use `relative` positioning on parent:

```vue
<!-- Notification badge on button -->
<div class="relative">
  <UButton>Messages</UButton>
  <UBadge class="absolute -top-2 -right-2" color="red">5</UBadge>
</div>

<!-- Status badge on avatar -->
<div class="relative">
  <UAvatar src="/avatar.jpg" alt="User" />
  <UBadge class="absolute bottom-0 right-0" color="green" />
</div>
```

**Using `position` prop** (Nuxt UI v4+):
```vue
<UBadge position="top-right" color="red">New</UBadge>
```

---

## 15. Form Nested Prop Missing

**Error**: Nested form validation fails or doesn't trigger

**Symptoms**:
- Inner form validation not working
- Submit button doesn't respect nested validation
- Console errors about duplicate form context

**Root Cause**: Missing `nested` prop on inner `<UForm>`.

**Solution**: Add `nested` prop to inner forms:

```vue
<UForm :state="outerState" @submit="onSubmit">
  <UFormGroup label="Parent Field">
    <UInput v-model="outerState.parentField" />
  </UFormGroup>

  <!-- Nested form -->
  <UForm :state="innerState" nested>
    <UFormGroup label="Child Field">
      <UInput v-model="innerState.childField" />
    </UFormGroup>
  </UForm>

  <UButton type="submit">Submit All</UButton>
</UForm>
```

**Why this works**: The `nested` prop prevents the inner form from creating its own submit context.

---

## 16. Table Pagination State

**Error**: Pagination controls not updating when page changes

**Symptoms**:
- Page number doesn't update
- Can't navigate between pages
- `page` prop not reactive

**Root Cause**: Not using `v-model` for pagination state.

**Solution**: Use `v-model` for reactive pagination:

```vue
<template>
  <UTable
    v-model:page="page"
    v-model:page-count="pageCount"
    :rows="paginatedRows"
    :columns="columns"
  >
    <template #pagination>
      <UPagination
        v-model="page"
        :page-count="pageCount"
        :total="totalRows"
      />
    </template>
  </UTable>
</template>

<script setup lang="ts">
const page = ref(1)
const pageSize = 10
const totalRows = computed(() => allRows.value.length)
const pageCount = computed(() => Math.ceil(totalRows.value / pageSize))

const paginatedRows = computed(() => {
  const start = (page.value - 1) * pageSize
  return allRows.value.slice(start, start + pageSize)
})
</script>
```

---

## 17. Color Mode Not Persisting

**Error**: Dark mode setting resets on page reload

**Symptoms**:
- User's color preference forgotten
- Always starts in light mode
- Toggle doesn't save

**Root Cause**: This is actually NOT an error - color mode auto-persists by default.

**How it works**:
```typescript
const colorMode = useColorMode()

// Automatically persisted to localStorage
colorMode.value = 'dark'

// Preference key: 'nuxt-color-mode'
```

**If persistence isn't working**, check:
1. localStorage is enabled (not in incognito mode)
2. Not overriding with `preference: 'system'`
3. Browser allows localStorage

**Force system preference**:
```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    colorMode: {
      preference: 'system' // Always use system preference
    }
  }
})
```

---

## 18. TypeScript Types Not Generated

**Error**: TypeScript errors for component types or auto-imports

**Symptoms**:
- Red squiggles in IDE
- "Cannot find name 'UButton'"
- Auto-imports not working
- `.nuxt/` directory missing types

**Root Cause**: Types not generated or stale.

**Solution**: Run type generation:

```bash
# Generate types
bunx nuxt prepare

# Or run dev (auto-generates types)
bunx nuxt dev
```

**Persistent issues**:
```bash
# Clear cache and regenerate
rm -rf .nuxt
bunx nuxt prepare

# Check tsconfig.json extends
{
  "extends": "./.nuxt/tsconfig.json"
}
```

**Add to `.gitignore`**:
```
.nuxt/
```

---

## 19. Theme Variants Not Applying

**Error**: Custom theme configuration not working

**Symptoms**:
- `ui` prop changes ignored
- Global theme not applied
- Component still uses default theme

**Root Cause**: Incorrect customization order or syntax.

**Customization hierarchy** (lowest to highest priority):
1. Global theme (`app.config.ts`)
2. Component `ui` prop
3. Tailwind classes

**Solution**: Check customization order:

```vue
<template>
  <!-- Method 1: Global theme (lowest priority) -->
  <!-- See app.config.ts -->

  <!-- Method 2: ui prop (medium priority) -->
  <UButton
    :ui="{
      base: 'font-bold',
      variant: {
        solid: 'bg-custom-500'
      }
    }"
  >
    Custom Button
  </UButton>

  <!-- Method 3: class (highest priority) -->
  <UButton class="!bg-red-500 !text-white">
    Override All
  </UButton>
</template>
```

**Global theme** (`app.config.ts`):
```typescript
export default defineAppConfig({
  ui: {
    button: {
      base: 'font-semibold',
      variant: {
        solid: 'bg-primary-600 hover:bg-primary-700'
      }
    }
  }
})
```

---

## 20. Responsive Patterns Broken

**Error**: Mobile layouts not working as expected

**Symptoms**:
- Grid doesn't stack on mobile
- Text too small on mobile
- Buttons too close together
- Horizontal scroll on mobile

**Root Cause**: Not using Tailwind responsive utilities.

**Solution**: Use responsive breakpoint prefixes:

```vue
<template>
  <!-- Responsive grid: 1 col mobile, 2 tablet, 3 desktop -->
  <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>

  <!-- Responsive text sizes -->
  <h1 class="text-2xl md:text-3xl lg:text-4xl">
    Responsive Heading
  </h1>

  <!-- Responsive spacing -->
  <div class="p-4 md:p-6 lg:p-8">
    Content with responsive padding
  </div>

  <!-- Responsive flex direction -->
  <div class="flex flex-col md:flex-row gap-4">
    <UButton>Action 1</UButton>
    <UButton>Action 2</UButton>
  </div>
</template>
```

**Tailwind breakpoints**:
- `sm`: 640px
- `md`: 768px
- `lg`: 1024px
- `xl`: 1280px
- `2xl`: 1536px

**Mobile-first approach**: Always style mobile first, then add `md:`, `lg:` overrides.

---

## 21. Cannot read property 'focus' of undefined (v4.2+)

**Error**: `TypeError: Cannot read properties of undefined (reading 'focus')` or `inputRef.value.$el is undefined`

**Symptoms**:
- Template refs not working after upgrading to v4.2.0+
- `.$el` accessor returns undefined
- TypeScript errors on component refs
- Focus/scroll operations failing

**Root Cause**: Breaking change in v4.2.0 - InputMenu, InputNumber, and SelectMenu now expose HTML elements directly instead of component instances.

**Affected Components**:
- `UInputMenu`
- `UInputNumber`
- `USelectMenu`

**Solution**: Remove the `.$el` accessor and use direct element access:

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

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

onMounted(() => {
  // Old way - component instance
  inputRef.value.$el.focus()  // ❌ Breaks in v4.2+
})
</script>
```

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

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

onMounted(() => {
  // New way - direct element access
  inputRef.value?.focus()  // ✅ Works in v4.2+
})
</script>
```

**Migration steps**:
1. Search codebase for `.$el` usage on InputMenu, InputNumber, SelectMenu
2. Remove all `.$el` accessors
3. Update TypeScript types from component refs to `HTMLElement`
4. Test all imperative DOM operations (focus, scroll, etc.)

**Complete migration example**:
```vue
<template>
  <div class="space-y-4">
    <UInputMenu ref="menuRef" />
    <UInputNumber ref="numberRef" />
    <USelectMenu ref="selectRef" />
    <UButton @click="focusAll">Focus All</UButton>
  </div>
</template>

<script setup lang="ts">
// ✅ Correct types for v4.2+
const menuRef = ref<HTMLElement>()
const numberRef = ref<HTMLElement>()
const selectRef = ref<HTMLElement>()

function focusAll() {
  // ✅ Direct element access
  menuRef.value?.focus()
  numberRef.value?.focus()
  selectRef.value?.focus()

  // ✅ Scrolling also works
  menuRef.value?.scrollIntoView({ behavior: 'smooth' })
}
</script>
```

**Why this change?**: Consistency with other Nuxt UI components and HTML standards. Most components already exposed HTML elements directly.

**See also**: `nuxt-v4-features.md` for complete v4.2.x migration guide

---

## 22. Missing tailwindcss Package

**Error**: "Cannot find module tailwindcss" or styles not building

**Symptoms**:
- Build errors about missing tailwindcss
- `@import "tailwindcss"` fails
- CSS not compiling

**Root Cause**: Nuxt UI v4.6+ requires `tailwindcss` as an explicit peer dependency.

**Solution**: Install both packages:

```bash
bun add @nuxt/ui tailwindcss
```

**Why**: Earlier versions auto-installed tailwindcss. v4.6+ requires explicit installation for better dependency management.

---

## 23. useChat Not Found (AI SDK v5)

**Error**: `useChat is not exported from '@ai-sdk/vue'`

**Symptoms**:
- Import error for `useChat`
- Chat state not reactive
- TypeScript error on composable

**Root Cause**: AI SDK v5 replaced `useChat` with the `Chat` class.

**Before (v4)** ❌:
```ts
import { useChat } from '@ai-sdk/vue'
const { messages, input, handleSubmit, status } = useChat()
```

**After (v5)** ✅:
```ts
import { Chat } from '@ai-sdk/vue'
const chat = new Chat({
  onError(error) { console.error(error) }
})
// chat.messages, chat.status, chat.sendMessage()
```

---

## 24. Chat messages.content Not Working

**Error**: Chat messages display empty or `[object Object]`

**Symptoms**:
- `message.content` is undefined
- Messages show as blank
- Tool calls and reasoning not rendering

**Root Cause**: AI SDK v5 uses `message.parts` instead of `message.content`.

**Before** ❌:
```vue
<template #content="{ message }">
  {{ message.content }}
</template>
```

**After** ✅:
```vue
<script setup lang="ts">
import { isTextUIPart, isReasoningUIPart, isToolUIPart, getToolName } from 'ai'
import { isReasoningStreaming, isToolStreaming } from '@nuxt/ui/utils/ai'
</script>

<template #content="{ message }">
  <template v-for="(part, index) in message.parts" :key="`${message.id}-${part.type}-${index}`">
    <UChatReasoning v-if="isReasoningUIPart(part)" :text="part.text" :streaming="isReasoningStreaming(message, index, chat)" />
    <UChatTool v-else-if="isToolUIPart(part)" :text="getToolName(part)" :streaming="isToolStreaming(part)" />
    <template v-else-if="isTextUIPart(part)">
      <MDC v-if="message.role === 'assistant'" :value="part.text" />
      <p v-else class="whitespace-pre-wrap">{{ part.text }}</p>
    </template>
  </template>
</template>
```

---

## 25. Form Nested Validation Not Inherited

**Error**: Nested form validation not triggering or state not syncing with parent

**Symptoms**:
- Child form doesn't validate when parent submits
- Nested field errors don't display
- Parent form doesn't see child form state

**Root Cause**: v4 requires explicit `nested` prop AND `name` prop on child forms.

**Solution**:

```vue
<UForm :state="state" :schema="schema" @submit="onSubmit">
  <UFormField label="Customer" name="customer">
    <UInput v-model="state.customer" />
  </UFormField>

  <div v-for="(item, index) in state.items" :key="index">
    <UForm
      :name="`items.${index}`"
      :schema="itemSchema"
      nested
    >
      <UFormField name="description">
        <UInput v-model="item.description" />
      </UFormField>
    </UForm>
  </div>
</UForm>
```

**Key changes from v3**:
- `nested` prop is now required (not automatic)
- `name` prop on child form matches parent field path (e.g., `items.0`)
- Schema transformations only apply to submit data, not internal state

---

**See also:**
- `ai-sdk-v5-integration.md` for complete AI SDK migration guide
- `chat-components.md` for chat component reference
- `nuxt-v4-features.md` for v4 migration features
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