From 34aae00a21e7a9f73d72e74808be6a88d4bbdde4 Mon Sep 17 00:00:00 2001
From: Mat4m0 <matthias.amon@me.com>
Date: Mon, 8 Jun 2026 16:17:11 +0200
Subject: [PATCH 1/2] fix: provide stable reka ids from app

---
 src/runtime/components/App.vue | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/runtime/components/App.vue b/src/runtime/components/App.vue
index 91c7b88e0a..73a1a1e4d8 100644
--- a/src/runtime/components/App.vue
+++ b/src/runtime/components/App.vue
@@ -21,7 +21,7 @@ export default {
 </script>
 
 <script setup lang="ts" generic="T extends Messages">
-import { toRef, useId, provide } from 'vue'
+import { toRef, provide } from 'vue'
 import { ConfigProvider, TooltipProvider, useForwardProps } from 'reka-ui'
 import { reactivePick } from '@vueuse/core'
 import { localeContextInjectionKey } from '../composables/useLocale'
@@ -38,6 +38,12 @@ const configProviderProps = useForwardProps(reactivePick(props, 'scrollBody'))
 const tooltipProps = toRef(() => props.tooltip)
 const toasterProps = toRef(() => props.toaster)
 
+// Vue's `useId` includes the app `idPrefix`, which can differ between Nuxt prerender
+// SSR and client hydration. Reka needs the provider to replay the same sequence on
+// both sides, so keep this generator scoped to the `UApp` render instance.
+let id = 0
+const useRekaId = () => `nuxt-ui-${++id}`
+
 const locale = toRef(() => props.locale)
 provide(localeContextInjectionKey, locale)
 
@@ -46,7 +52,7 @@ provide(portalTargetInjectionKey, portal)
 </script>
 
 <template>
-  <ConfigProvider :use-id="() => (useId() as string)" :dir="props.dir || locale?.dir" :locale="locale?.code" v-bind="configProviderProps">
+  <ConfigProvider :use-id="useRekaId" :dir="props.dir || locale?.dir" :locale="locale?.code" v-bind="configProviderProps">
     <TooltipProvider v-bind="tooltipProps">
       <UToaster v-if="toaster !== null" v-bind="toasterProps">
         <slot />

From 13f2767c7f81db49b212d4972ac74a7865ee75f5 Mon Sep 17 00:00:00 2001
From: Benjamin Canac <canacb1@gmail.com>
Date: Fri, 12 Jun 2026 15:30:28 +0200
Subject: [PATCH 2/2] feat(App): add `useId` prop to customize Reka UI id
 generation

---
 docs/content/docs/2.components/app.md | 23 +++++++++++++++++++
 src/runtime/components/App.vue        | 15 ++++++-------
 test/components/App.spec.ts           | 32 +++++++++++++++++++++++++++
 3 files changed, 62 insertions(+), 8 deletions(-)
 create mode 100644 test/components/App.spec.ts

diff --git a/docs/content/docs/2.components/app.md b/docs/content/docs/2.components/app.md
index e6b0c458d5..ed156bb07d 100644
--- a/docs/content/docs/2.components/app.md
+++ b/docs/content/docs/2.components/app.md
@@ -40,6 +40,29 @@ Learn how to use the `locale` prop to change the locale of your app. This also c
 :::
 ::
 
+### Stable IDs
+
+Reka UI primitives rely on Vue's [useId](https://vuejs.org/api/composition-api-helpers.html#useid) to generate the `id` attributes used for accessibility. A known upstream issue ([vuejs/core#12591](https://github.com/vuejs/core/issues/12591)) can make these ids differ between the server and the client in some Nuxt apps, causing hydration mismatches on components like Accordion or Tabs.
+
+You can use the `useId` prop to provide your own generator as a workaround:
+
+```vue [app.vue]
+<script setup lang="ts">
+let count = 0
+const generateId = () => `app-${++count}`
+</script>
+
+<template>
+  <UApp :use-id="generateId">
+    <NuxtPage />
+  </UApp>
+</template>
+```
+
+::warning
+A counter like this is only hydration safe when Reka UI primitives mount in the same order on the server and the client, which is not guaranteed when several lazy or data fetching components render them. Keep the default unless you actually face these mismatches.
+::
+
 ## API
 
 ### Props
diff --git a/src/runtime/components/App.vue b/src/runtime/components/App.vue
index 73a1a1e4d8..1ce22c34f5 100644
--- a/src/runtime/components/App.vue
+++ b/src/runtime/components/App.vue
@@ -9,6 +9,11 @@ export interface AppProps<T extends Messages = Messages> extends Omit<ConfigProv
   toaster?: ToasterProps | null
   locale?: Locale<T>
   portal?: boolean | string | HTMLElement
+  /**
+   * Provide a custom `id` generator for Reka UI primitives as a workaround when facing hydration mismatches.
+   * @defaultValue Vue's `useId`
+   */
+  useId?: () => string
 }
 
 export interface AppSlots {
@@ -21,7 +26,7 @@ export default {
 </script>
 
 <script setup lang="ts" generic="T extends Messages">
-import { toRef, provide } from 'vue'
+import { toRef, useId as vueUseId, provide } from 'vue'
 import { ConfigProvider, TooltipProvider, useForwardProps } from 'reka-ui'
 import { reactivePick } from '@vueuse/core'
 import { localeContextInjectionKey } from '../composables/useLocale'
@@ -38,12 +43,6 @@ const configProviderProps = useForwardProps(reactivePick(props, 'scrollBody'))
 const tooltipProps = toRef(() => props.tooltip)
 const toasterProps = toRef(() => props.toaster)
 
-// Vue's `useId` includes the app `idPrefix`, which can differ between Nuxt prerender
-// SSR and client hydration. Reka needs the provider to replay the same sequence on
-// both sides, so keep this generator scoped to the `UApp` render instance.
-let id = 0
-const useRekaId = () => `nuxt-ui-${++id}`
-
 const locale = toRef(() => props.locale)
 provide(localeContextInjectionKey, locale)
 
@@ -52,7 +51,7 @@ provide(portalTargetInjectionKey, portal)
 </script>
 
 <template>
-  <ConfigProvider :use-id="useRekaId" :dir="props.dir || locale?.dir" :locale="locale?.code" v-bind="configProviderProps">
+  <ConfigProvider :use-id="() => props.useId?.() ?? (vueUseId() as string)" :dir="props.dir || locale?.dir" :locale="locale?.code" v-bind="configProviderProps">
     <TooltipProvider v-bind="tooltipProps">
       <UToaster v-if="toaster !== null" v-bind="toasterProps">
         <slot />
diff --git a/test/components/App.spec.ts b/test/components/App.spec.ts
new file mode 100644
index 0000000000..abe1701451
--- /dev/null
+++ b/test/components/App.spec.ts
@@ -0,0 +1,32 @@
+import { defineComponent, h } from 'vue'
+import { describe, it, expect } from 'vitest'
+import { mountSuspended } from '@nuxt/test-utils/runtime'
+import { useId } from 'reka-ui'
+import App from '../../src/runtime/components/App.vue'
+
+const IdConsumer = defineComponent({
+  setup() {
+    const id = useId()
+    return () => h('div', { id, 'data-testid': 'consumer' })
+  }
+})
+
+describe('App', () => {
+  it('defaults to Vue useId for Reka UI primitives', async () => {
+    const wrapper = await mountSuspended(App, {
+      slots: { default: () => h(IdConsumer) }
+    })
+
+    expect(wrapper.find('[data-testid="consumer"]').attributes('id')).toMatch(/^reka-v-?\d/)
+  })
+
+  it('forwards the useId prop to Reka UI primitives', async () => {
+    let count = 0
+    const wrapper = await mountSuspended(App, {
+      props: { useId: () => `custom-${++count}` },
+      slots: { default: () => h(IdConsumer) }
+    })
+
+    expect(wrapper.find('[data-testid="consumer"]').attributes('id')).toBe('reka-custom-1')
+  })
+})