From 275c2cdd85e9ced4e39c77f87741d32c8f08fe95 Mon Sep 17 00:00:00 2001
From: Ben Hong <ben@bencodezen.io>
Date: Tue, 8 Jul 2025 09:24:12 -0400
Subject: [PATCH] docs: add addendum on useId usage with computed

---
 src/api/composition-api-helpers.md | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/src/api/composition-api-helpers.md b/src/api/composition-api-helpers.md
index 3fe24aad64..789b0f7647 100644
--- a/src/api/composition-api-helpers.md
+++ b/src/api/composition-api-helpers.md
@@ -42,10 +42,11 @@ This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setu
     set?: (v: T) => any
   }
 
-  type ModelRef<T, M extends PropertyKey = string, G = T, S = T> = Ref<G, S> & [
-    ModelRef<T, M, G, S>,
-    Record<M, true | undefined>
-  ]
+  type ModelRef<T, M extends PropertyKey = string, G = T, S = T> = Ref<
+    G,
+    S
+  > &
+    [ModelRef<T, M, G, S>, Record<M, true | undefined>]
   ```
 
 - **Example**
@@ -132,3 +133,18 @@ Used to generate unique-per-application IDs for accessibility attributes or form
   IDs generated by `useId()` are also guaranteed to be stable across the server and client renders, so they can be used in SSR applications without leading to hydration mismatches.
 
   If you have more than one Vue application instance of the same page, you can avoid ID conflicts by giving each app an ID prefix via [`app.config.idPrefix`](/api/application#app-config-idprefix).
+
+  :::warning Caution
+  `useId()` should be not be called inside a `computed()` property as it may cause instance conflicts. Instead, declare the ID outside of `computed()` and reference it within the computed function.
+
+  ```vue
+  <script setup>
+  import { computed, useId } from 'vue'
+
+  const id = useId()
+
+  const ariaDescribedBy = computed(() => `${id}-description`)
+  </script>
+  ```
+
+  :::