Merge branch 'v4' into feat/wheel-picker

Author: husamMousa

.github/contributing/documentation.md

@@ -127,6 +127,14 @@ links:
 ---
 ```
 
+Optional `keywords` feed the docs search and the MCP `search-components` tool. Use alternate names from other ecosystems, not words already in the title or description:
+
+```yaml
+keywords:
+  - segmented control
+  - button group
+```
+
 For Reka UI based components, add the Reka UI link:
 
 ```yaml

docs/app/app.vue

@@ -17,6 +17,7 @@ useHead({
 if (import.meta.server) {
   useSeoMeta({
     ogSiteName: 'Nuxt UI',
+    ogType: 'website',
     twitterCard: 'summary_large_image'
   })
 

docs/app/pages/index.vue

@@ -164,6 +164,10 @@ useIntersectionObserver(contributorsRef, ([entry]) => {
     <USeparator />
 
     <UPageSection :ui="{ container: 'lg:py-16' }" class="bg-elevated/25">
+      <h2 class="sr-only">
+        Features
+      </h2>
+
       <ul class="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3 lg:gap-8 xl:gap-y-10">
         <Motion
           v-for="(feature, index) in page?.features"
@@ -193,10 +197,10 @@ useIntersectionObserver(contributorsRef, ([entry]) => {
             <UIcon :name="feature.icon" class="size-5 shrink-0" />
           </div>
           <div class="flex flex-col">
-            <h2 class="font-medium text-highlighted inline-flex items-center gap-x-1">
+            <h3 class="font-medium text-highlighted inline-flex items-center gap-x-1">
               {{ feature.title }}
               <UIcon v-if="feature.to" :name="appConfig.ui.icons.arrowRight" class="size-4 shrink-0 opacity-0 group-hover:opacity-100 transition-all duration-200 -translate-x-1 group-hover:translate-x-0" />
-            </h2>
+            </h3>
             <p class="text-sm text-muted">
               {{ feature.description }}
             </p>

docs/content/blog/how-to-build-an-ai-chat.md

@@ -36,7 +36,7 @@ Check out the [`Nuxt`](https://github.com/nuxt-ui-templates/chat) and [`Vue`](ht
 
 Before we start, make sure you have:
 
-- Node.js 20+ installed
+- Node.js 22.19+ or 24.11+ installed
 - A [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) API key (provides access to multiple AI providers through a single endpoint)
 
 ## Project setup
@@ -191,7 +191,7 @@ This section covers integrating AI on the server. The following API endpoints ha
 
 ### Creating a chat
 
-First, create the endpoint that initializes a new chat and saves the first message to the database. This uses the [`UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/ui-message) type from the AI SDK:
+First, create the endpoint that initializes a new chat and saves the first message to the database. This uses the [`UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message) type from the AI SDK:
 
 ::code-tree-intersection
 ```ts [server/api/chats.post.ts]
@@ -404,7 +404,7 @@ export default defineEventHandler(async (event) => {
 ```
 ::
 
-## Wire up the UI
+## Wiring up the UI
 
 Nuxt UI provides purpose-built components for AI chat interfaces: [`UChatPrompt`](/docs/components/chat-prompt) for the input area and [`UChatMessages`](/docs/components/chat-messages) for displaying the conversation.
 
@@ -509,7 +509,7 @@ html.dark .shiki span {
 
 ## Creating the chat page
 
-The chat page is where the actual conversation happens. It integrates the AI SDK's [`Chat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/chat) class and [`DefaultChatTransport`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/default-chat-transport) for real-time streaming.
+The chat page is where the actual conversation happens. It integrates the AI SDK's [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) composable and [`DefaultChatTransport`](https://ai-sdk.dev/docs/ai-sdk-ui/transport#default-transport) for real-time streaming.
 
 ::code-tree-intersection
 :::code-collapse
@@ -532,7 +532,7 @@ if (!chatData.value) {
 
 const input = ref('')
 
-// Initialize the Chat class from AI SDK
+// Initialize the useChat composable from AI SDK
 const { messages, status, error, sendMessage, regenerate, stop } = useChat({
   id: chatData.value.id,
   messages: chatData.value.messages,
@@ -632,7 +632,7 @@ onMounted(() => {
 
 Here's a breakdown of the key parts:
 
-**The Chat Class**
+**The `useChat` composable**
 
 The [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) composable from `@ai-sdk/vue` manages the entire conversation state. It handles:
 - Message history with `messages`
@@ -641,7 +641,7 @@ The [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) composable
 - Stopping generation with `stop()`
 - Regenerating responses with `regenerate()`
 
-The `onData` callback receives [custom data events](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data) from the server (like `data-chat-title`), allowing you to react to server-side events during streaming.
+The `onData` callback receives [custom data events](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data) from the server (like `data-chat-title`), so you can react to server-side events during streaming.
 
 **UChatMessages Component**
 
@@ -810,7 +810,7 @@ if (!chatData.value) {
 
 const input = ref('')
 
-// Initialize the Chat class from AI SDK
+// Initialize the useChat composable from AI SDK
 const { messages, status, error, sendMessage, regenerate, stop } = useChat({
   id: chatData.value.id,
   messages: chatData.value.messages,
@@ -1141,7 +1141,9 @@ Then, in the Vercel dashboard:
 - Enable **AI Gateway** and add credits so requests can be processed.
 - Add a **Turso** database from the Vercel Marketplace and connect it to your project (it will provision the database and add the required environment variables automatically).
 
-> Note: On Vercel, you **don’t need to manually add `AI_GATEWAY_API_KEY`** — Vercel handles the gateway configuration for deployments. Keep using `.env` locally for development.
+::note
+On Vercel you don't need to manually add `AI_GATEWAY_API_KEY`. Vercel handles the gateway configuration for deployments. Keep using `.env` locally for development.
+::
 
 ::note{to="https://vercel.com/docs/ai-gateway" target="_blank"}
 Learn more about setting up AI Gateway in the **Vercel AI Gateway documentation**.
@@ -1161,7 +1163,7 @@ The combination of Nuxt's full-stack capabilities, Nuxt UI's purpose-built chat
 
 **Resources:**
 
-- [Nuxt UI Chat Components](https://ui.nuxt.com/components/chat)
+- [Nuxt UI Chat Components](https://ui.nuxt.com/docs/components/chat)
 - [NuxtHub Database](https://hub.nuxt.com/docs/features/database)
 - [AI SDK Documentation](https://ai-sdk.dev)
 - [AI Gateway Documentation](https://vercel.com/docs/ai-gateway)

docs/content/community.yml

@@ -26,7 +26,7 @@ items:
     to: 'https://www.raycast.com/HugoRCD/nuxt'
     target: '_blank'
     user:
-      name: 'HugoRDC'
+      name: 'HugoRCD'
       to: 'https://github.com/HugoRCD'
       target: '_blank'
       avatar:

docs/content/docs/1.getting-started/1.index.md

@@ -58,6 +58,8 @@ If you are migrating from v2, you can read more in this **migration guide**.
 
 ## Core technologies
 
+Nuxt UI is built on three foundations: Reka UI for behavior and accessibility, Tailwind CSS for styling, and Tailwind Variants for composing variants.
+
 ### Reka UI
 
 Nuxt UI is built on top of [Reka UI](https://reka-ui.com/) as a foundation for the components:
@@ -88,13 +90,25 @@ Nuxt UI takes advantage of [Tailwind Variants](https://www.tailwind-variants.org
 
 ### Ecosystem integration
 
-Nuxt UI is SSR compatible and integrates seamlessly with the Nuxt ecosystem (these features also work in Vue with additional configuration):
+Nuxt UI is SSR compatible and integrates seamlessly with the ecosystem:
 
-- [**Icons**](/docs/getting-started/integrations/icons): Access 200,000+ icons from Iconify
+::framework-only
+#nuxt
+:::div
+- [**Icons**](/docs/getting-started/integrations/icons/nuxt): Access 200,000+ icons from Iconify
 - [**Fonts**](/docs/getting-started/integrations/fonts): Plug-and-play web font optimization and configuration
-- [**Color Mode**](/docs/getting-started/integrations/color-mode): Dark and Light mode with auto detection
-- [**i18n**](/docs/getting-started/integrations/i18n): Internationalize your components with 50+ languages
+- [**Color Mode**](/docs/getting-started/integrations/color-mode/nuxt): Dark and Light mode with auto detection
+- [**i18n**](/docs/getting-started/integrations/i18n/nuxt): Internationalize your components with 50+ languages
 - [**Content**](/docs/getting-started/integrations/content): Beautiful typography out of the box
+:::
+
+#vue
+:::div
+- [**Icons**](/docs/getting-started/integrations/icons/vue): Access 200,000+ icons from Iconify
+- [**Color Mode**](/docs/getting-started/integrations/color-mode/vue): Dark and Light mode with auto detection
+- [**i18n**](/docs/getting-started/integrations/i18n/vue): Internationalize your components with 50+ languages
+:::
+::
 
 ### Vue compatibility (Nuxt optional)
 

docs/content/docs/1.getting-started/2.installation/1.nuxt.md

@@ -104,7 +104,7 @@ It's recommended to install the [Tailwind CSS IntelliSense](https://marketplace.
 ```
 
 ::note{to="/docs/components/app"}
-The `App` component provides global configurations and is required for **Toast**, **Tooltip** components to work as well as **Programmatic Overlays**.
+The `App` component sets up global config and is required for **Toast**, **Tooltip** and **programmatic overlays**.
 ::
 
 ::
@@ -394,6 +394,8 @@ This strips **structural** classes too (positioning, transitions, flex/grid), no
 
 Use the `theme.defaultVariants` option to override the default `color` and `size` variants for components.
 
+Only defaults that are exactly `primary` or `md` are replaced, so Avatar keeps `color: 'neutral'` and Separator keeps `size: 'xs'`.
+
 - Default: `{ color: 'primary', size: 'md' }`{lang="ts-type"}
 
 ```ts [nuxt.config.ts] {4-11}
@@ -491,7 +493,7 @@ Use the [`prose`](#prose) option instead.
 
 ### `content`
 
-Use the `content` option to force the import of Nuxt UI `<Prose>` and `<UContent>` components even if `@nuxt/content` is not installed.
+Use the `content` option to force the import of the Nuxt UI prose and content components even if `@nuxt/content` is not installed.
 
 - Default: `false`{lang="ts-type"}
 

docs/content/docs/1.getting-started/2.installation/2.vue.md

@@ -140,7 +140,7 @@ These declaration files are only written when Vite runs. The default `create-vue
 ::
 
 ::tip
-Internally, Nuxt UI relies on custom alias to resolve the theme types. If you're using TypeScript, you should add an alias to your `tsconfig` to enable auto-completion in your `vite.config.ts`.
+Internally, Nuxt UI relies on custom aliases to resolve the theme types. If you're using TypeScript, add these aliases to your `tsconfig` files to enable auto-completion in your `vite.config.ts`.
 
 ```json [tsconfig.node.json]
 {
@@ -268,7 +268,7 @@ Import the CSS file in your entrypoint.
 
 :::code-group{sync="vite"}
 
-```ts [src/main.ts]{1}
+```ts [src/main.ts (Vite)]{1}
 import './assets/css/main.css'
 
 import { createApp } from 'vue'
@@ -560,7 +560,7 @@ export default defineConfig({
 
 ### `ui`
 
-Use the `ui` option to provide configuration for Nuxt UI.
+Use the `ui` option to provide configuration for Nuxt UI. This is the Vue equivalent of the `ui` key in Nuxt's `app.config.ts`.
 
 ```ts [vite.config.ts] {9-14}
 import { defineConfig } from 'vite'
@@ -582,6 +582,57 @@ export default defineConfig({
 })
 ```
 
+### `dts`
+
+Use the `dts` option to enable or disable the generation of declaration files for auto-imported components and composables.
+
+- Default: `true`{lang="ts-type"}
+
+```ts [vite.config.ts] {9}
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import ui from '@nuxt/ui/vite'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    ui({
+      dts: false
+    })
+  ]
+})
+```
+
+### `icon`
+
+Use the `icon` option to set default props for the [Icon](/docs/components/icon) component (`size`, `mode`, `customize`) and to configure build-time icon bundling through `clientBundle`. Bundling of Nuxt UI's own icons is enabled by default when their collection is installed. Set `clientBundle: false` to opt out.
+
+- Default: `{}`{lang="ts-type"}
+
+```ts [vite.config.ts] {9-14}
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import ui from '@nuxt/ui/vite'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    ui({
+      icon: {
+        mode: 'svg',
+        clientBundle: {
+          scan: true
+        }
+      }
+    })
+  ]
+})
+```
+
+::note{to="/docs/getting-started/integrations/icons/vue#collections"}
+Learn more about icon collections and client bundling in the **Icons** documentation.
+::
+
 ### `colorMode`
 
 Use the `colorMode` option to enable or disable the color mode integration from `@vueuse/core`.
@@ -692,6 +743,8 @@ This strips **structural** classes too (positioning, transitions, flex/grid), no
 
 Use the `theme.defaultVariants` option to override the default `color` and `size` variants for components.
 
+Only defaults that are exactly `primary` or `md` are replaced, so Avatar keeps `color: 'neutral'` and Separator keeps `size: 'xs'`.
+
 - Default: `{ color: 'primary', size: 'md' }`{lang="ts-type"}
 
 ```ts [vite.config.ts] {9-14}

docs/content/docs/1.getting-started/3.migration/1.v4.md

@@ -12,7 +12,7 @@ links:
 Nuxt UI v4 marks a major milestone: **Nuxt UI and Nuxt UI Pro are now unified into a single, fully open-source and free library**. You now have access to 125+ production-ready components, all available in the `@nuxt/ui` package.
 
 ::note
-Nuxt UI v4 requires **Nuxt 4** due to some dependencies. Make sure to upgrade to Nuxt 4 before migrating to Nuxt UI v4.
+Nuxt UI v4 requires **Nuxt 4.1 or later** due to some dependencies. Make sure to upgrade before migrating to Nuxt UI v4.
 ::
 
 This guide provides step-by-step instructions to migrate your application from v3 to v4.
@@ -387,7 +387,7 @@ export default defineNuxtConfig({
 ```
 ::
 
-2. The `useChat` composable API changed — `input` and `handleSubmit` were removed in favor of `sendMessage`, and `messages` is now a ref you set directly:
+2. The `useChat` composable API changed: `input` and `handleSubmit` were removed in favor of `sendMessage`, and `messages` is now a ref you set directly:
 
 ```diff
 <script setup lang="ts">

docs/content/docs/1.getting-started/3.migration/2.v3.md

@@ -735,6 +735,8 @@ const groups = [{
 
 ### Changed composables
 
+Some composables changed their signature or the names of their options:
+
 - The `useToast()` composable `timeout` prop has been renamed to `duration`:
 
 ```diff
@@ -807,7 +809,7 @@ import { ModalExampleComponent } from '#components'
 -   })
 - }
 + async function openModal() {
-+   const instance = modal.open(ModalExampleComponent, {
++   const instance = modal.open({
 +     count: count.value
 +   })
 +
@@ -822,6 +824,8 @@ import { ModalExampleComponent } from '#components'
 
 ### Changed form validation
 
+Form errors changed shape, so any code reading them needs updating:
+
 - The error object property for targeting form fields has been renamed from `path` to `name`:
 
 ```diff