fix(useId): honor configured id source before vue useId (#2683)

Mat4m0 · web-flow · commit b2e781d8d3c9 · 2026-06-10T15:14:05.000+08:00
* fix: honor configured id source before vue useId

* chore(deps): pin @vue/server-renderer dependency

* chore(deps): update lockfile
diff --git a/docs/content/docs/utilities/config-provider.md b/docs/content/docs/utilities/config-provider.md
@@ -64,9 +64,11 @@ import { ConfigProvider } from 'reka-ui'
 </template>
 ```
 
-## Hydration issue (Vue < 3.5)
+## Hydration issue
 
-We expose a temporary workaround to allow current Nuxt (with version >3.10) project fix the current hydration issue by using [`useId`](https://nuxt.com/docs/api/composables/use-id) provided by Nuxt.
+`ConfigProvider` can accept a custom `useId` function for frameworks that need to provide their own SSR-stable ID source. Reka UI uses this function before Vue's native `useId`, so every primitive that generates accessibility IDs follows the same app-provided source.
+
+This is useful in Nuxt projects where prerendered HTML and client hydration can use different Vue app ID prefixes. Pass Nuxt's [`useId`](https://nuxt.com/docs/api/composables/use-id) through `ConfigProvider` so Reka-generated IDs stay stable across server and client rendering.
 
 > Inspired by [Headless UI](https://github.com/tailwindlabs/headlessui/pull/2959)
 
diff --git a/docs/content/docs/utilities/use-id.md b/docs/content/docs/utilities/use-id.md
@@ -15,6 +15,17 @@ description: Generate random id
 Generate random id
 </Description>
 
+## Source order
+
+`useId` resolves IDs in this order:
+
+1. Explicit ID passed to `useId(id)`.
+2. The `useId` function provided by `ConfigProvider`.
+3. Vue's native `useId` when available.
+4. Reka UI's fallback counter for older Vue versions.
+
+Use `ConfigProvider` when your framework provides its own SSR-stable ID source, such as Nuxt's `useId`.
+
 ## Usage
 
 ```ts
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -113,6 +113,7 @@
     "@types/node": "^24.0.13",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vitest/coverage-istanbul": "^3.2.6",
+    "@vue/server-renderer": "^3.5.17",
     "@vue/test-utils": "^2.4.11",
     "@vue/tsconfig": "^0.7.0",
     "jsdom": "^26.1.0",
diff --git a/packages/core/src/Accordion/Accordion.test.ts b/packages/core/src/Accordion/Accordion.test.ts
@@ -1,10 +1,80 @@
 import type { VueWrapper } from '@vue/test-utils'
 import { findByText, fireEvent } from '@testing-library/vue'
+import { renderToString } from '@vue/server-renderer'
 import { mount } from '@vue/test-utils'
-import { beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { axe } from 'vitest-axe'
+import { createSSRApp, defineComponent, h, nextTick } from 'vue'
+import { ConfigProvider } from '@/ConfigProvider'
+import {
+  AccordionContent,
+  AccordionHeader,
+  AccordionItem,
+  AccordionRoot,
+  AccordionTrigger,
+} from '.'
 import Accordion from './story/_Accordion.vue'
 
+const AccordionHydrationFixture = defineComponent({
+  setup() {
+    const items = ['One', 'Two']
+    let count = 0
+    const useId = () => `nuxt-${++count}`
+
+    return () =>
+      h(ConfigProvider, { useId }, () =>
+        h(
+          AccordionRoot,
+          { type: 'single', collapsible: true },
+          () => items.map(item =>
+            h(AccordionItem, { value: item }, () => [
+              h(AccordionHeader, () =>
+                h(AccordionTrigger, () => `Trigger ${item}`)),
+              h(AccordionContent, () => `Content ${item}`),
+            ]),
+          ),
+        ))
+  },
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('ssr hydration', () => {
+  it('uses ConfigProvider ids when Vue app id prefixes differ', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    // Nuxt prerender can produce a different Vue useId app prefix than the
+    // hydrating client. ConfigProvider's useId must remain the stable source.
+    const serverApp = createSSRApp(AccordionHydrationFixture)
+    serverApp.config.idPrefix = 'v-1'
+
+    const container = document.createElement('div')
+    container.innerHTML = await renderToString(serverApp)
+    document.body.innerHTML = ''
+    document.body.append(container)
+
+    expect(container.innerHTML).toContain('id="reka-accordion-trigger-nuxt-1"')
+    expect(container.innerHTML).toContain('id="reka-collapsible-content-nuxt-2"')
+    const triggerId = container.querySelector('button')?.id
+    const contentId = container.querySelector('[role="region"]')?.id
+
+    const clientApp = createSSRApp(AccordionHydrationFixture)
+    clientApp.config.idPrefix = 'v-0'
+    clientApp.mount(container)
+    await nextTick()
+
+    expect(container.querySelector('button')?.id).toBe(triggerId)
+    expect(container.querySelector('[role="region"]')?.id).toBe(contentId)
+
+    const warnings = warn.mock.calls.flat().join('\n')
+    expect(warnings).not.toContain('Hydration attribute mismatch')
+    expect(error.mock.calls.flat().join('\n')).not.toContain('Hydration completed but contains mismatches')
+  })
+})
+
 describe('given a single Accordion', () => {
   let wrapper: VueWrapper<InstanceType<typeof Accordion>>
   beforeEach(() => {
diff --git a/packages/core/src/ConfigProvider/ConfigProvider.test.ts b/packages/core/src/ConfigProvider/ConfigProvider.test.ts
@@ -2,8 +2,10 @@ import type { VueWrapper } from '@vue/test-utils'
 import type vueuse from '@vueuse/core'
 import { mount } from '@vue/test-utils'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { nextTick } from 'vue'
+import { defineComponent, h, nextTick } from 'vue'
+import { useId } from '@/shared'
 import ConfigProviderTest from './_ConfigProvider.vue'
+import ConfigProvider from './ConfigProvider.vue'
 
 vi.mock('@vueuse/core', async (importOriginal) => {
   const mod: typeof vueuse = await importOriginal()
@@ -84,3 +86,25 @@ describe('given a scrollBody ConfigProvider', async () => {
     expect(document.body.style.marginRight).toBe('20px')
   })
 })
+
+describe('given a useId ConfigProvider', () => {
+  it('uses the provided id generator before Vue useId', () => {
+    const IdConsumer = defineComponent({
+      setup() {
+        const id = useId(undefined, 'reka-test')
+        return () => h('div', { id })
+      },
+    })
+
+    const wrapper = mount(ConfigProvider, {
+      props: {
+        useId: () => 'provided-id',
+      },
+      slots: {
+        default: () => h(IdConsumer),
+      },
+    })
+
+    expect(wrapper.find('#reka-test-provided-id').exists()).toBe(true)
+  })
+})
diff --git a/packages/core/src/Tabs/Tabs.test.ts b/packages/core/src/Tabs/Tabs.test.ts
@@ -1,10 +1,69 @@
 import type { VueWrapper } from '@vue/test-utils'
+import { renderToString } from '@vue/server-renderer'
 import { flushPromises, mount } from '@vue/test-utils'
-import { beforeEach, describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { axe } from 'vitest-axe'
+import { createSSRApp, defineComponent, h, nextTick } from 'vue'
+import { ConfigProvider } from '@/ConfigProvider'
 import { TabsContent, TabsList, TabsRoot, TabsTrigger } from '.'
 import Tabs from './story/_Tabs.vue'
 
+const TabsHydrationFixture = defineComponent({
+  setup() {
+    let count = 0
+    const useId = () => `nuxt-${++count}`
+
+    return () =>
+      h(ConfigProvider, { useId }, () =>
+        h(TabsRoot, { defaultValue: 'account' }, () => [
+          h(TabsList, () => [
+            h(TabsTrigger, { value: 'account' }, () => 'Account'),
+            h(TabsTrigger, { value: 'password' }, () => 'Password'),
+          ]),
+          h(TabsContent, { value: 'account' }, () => 'Account content'),
+          h(TabsContent, { value: 'password' }, () => 'Password content'),
+        ]))
+  },
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('ssr hydration', () => {
+  it('uses ConfigProvider ids when Vue app id prefixes differ', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    // Tabs derives trigger/content IDs from one base ID, so this catches the
+    // shared source-order bug for components that build related IDs.
+    const serverApp = createSSRApp(TabsHydrationFixture)
+    serverApp.config.idPrefix = 'v-1'
+
+    const container = document.createElement('div')
+    container.innerHTML = await renderToString(serverApp)
+    document.body.innerHTML = ''
+    document.body.append(container)
+
+    expect(container.innerHTML).toContain('id="reka-tabs-nuxt-1-trigger-account"')
+    expect(container.innerHTML).toContain('id="reka-tabs-nuxt-1-content-account"')
+    const triggerId = container.querySelector('[role="tab"]')?.id
+    const contentId = container.querySelector('[role="tabpanel"]')?.id
+
+    const clientApp = createSSRApp(TabsHydrationFixture)
+    clientApp.config.idPrefix = 'v-0'
+    clientApp.mount(container)
+    await nextTick()
+
+    expect(container.querySelector('[role="tab"]')?.id).toBe(triggerId)
+    expect(container.querySelector('[role="tabpanel"]')?.id).toBe(contentId)
+
+    const warnings = warn.mock.calls.flat().join('\n')
+    expect(warnings).not.toContain('Hydration attribute mismatch')
+    expect(error.mock.calls.flat().join('\n')).not.toContain('Hydration completed but contains mismatches')
+  })
+})
+
 describe('given default Tabs', () => {
   let wrapper: VueWrapper<InstanceType<typeof Tabs>>
 
diff --git a/packages/core/src/shared/useId.ts b/packages/core/src/shared/useId.ts
@@ -5,24 +5,32 @@ import { injectConfigProviderContext } from '@/ConfigProvider/ConfigProvider.vue
 
 let count = 0
 /**
- * The `useId` function generates a unique identifier using a provided deterministic ID or a default
- * one prefixed with "reka-", or the provided one via `useId` props from `<ConfigProvider>`.
+ * The `useId` function generates a unique identifier using a provided deterministic ID,
+ * a configured `<ConfigProvider>` ID source, Vue's native `useId`, or a fallback counter.
  * @param {string | null | undefined} [deterministicId] - The `useId` function you provided takes an
  * optional parameter `deterministicId`, which can be a string, null, or undefined. If
  * `deterministicId` is provided, the function will return it. Otherwise, it will generate an id using
- * the `useId` function obtained
+ * the configured ID source.
  */
 export function useId(deterministicId?: string | null | undefined, prefix = 'reka') {
   if (deterministicId)
     return deterministicId
 
   let id: string
-  if ('useId' in vue) {
+  const configProviderContext = injectConfigProviderContext({ useId: undefined })
+
+  // Keep the app-provided ID source authoritative. Frameworks such as Nuxt can
+  // prerender with a different Vue app ID prefix than the hydrating client, so
+  // falling through to Vue's native useId would bypass the stable source that
+  // ConfigProvider was explicitly given.
+  if (configProviderContext.useId) {
+    id = configProviderContext.useId()
+  }
+  else if ('useId' in vue) {
     id = vue.useId?.()
   }
   else {
-    const configProviderContext = injectConfigProviderContext({ useId: undefined })
-    id = configProviderContext.useId?.() ?? `${++count}`
+    id = `${++count}`
   }
 
   return prefix ? `${prefix}-${id}` : id
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
