1---
2title: Do Not Use Generic Argument with reactive()
3impact: MEDIUM
4impactDescription: The generic argument type differs from the actual return type due to ref unwrapping, causing type mismatches
5type: gotcha
6tags: [vue3, typescript, reactive, ref-unwrapping, composition-api]
7---
8 
9# Do Not Use Generic Argument with reactive()
10 
11**Impact: MEDIUM** - It is NOT recommended to use the generic argument of `reactive()` because the returned type, which handles nested ref unwrapping, is different from the generic argument type. Use interface annotation on the variable instead.
12 
13## Task Checklist
14 
15- [ ] Use type annotation on the variable, not generic argument
16- [ ] Understand that `reactive()` unwraps nested refs
17- [ ] For generic composables, use `shallowRef` or explicit `Ref<T>` typing
18- [ ] Prefer `ref()` for simple values to avoid these issues
19 
20## The Problem
21 
22```vue
23<script setup lang="ts">
24import { reactive, ref } from 'vue'
25 
26interface Book {
27  title: string
28  year: number
29  author: Ref<string>  // Nested ref
30}
31 
32// WRONG: Generic argument doesn't account for ref unwrapping
33const book = reactive<Book>({
34  title: 'Vue 3 Guide',
35  year: 2024,
36  author: ref('John Doe')
37})
38 
39// TypeScript thinks book.author is Ref<string>
40// But at runtime, it's unwrapped to just string!
41book.author.value  // TypeScript: OK, Runtime: ERROR (author is a string, not a ref)
42</script>
43```
44 
45## The Solution: Interface Annotation
46 
47```vue
48<script setup lang="ts">
49import { reactive, ref } from 'vue'
50 
51interface Book {
52  title: string
53  year?: number
54}
55 
56// CORRECT: Annotate the variable, not the generic
57const book: Book = reactive({
58  title: 'Vue 3 Guide'
59})
60 
61book.title = 'New Title'  // TypeScript knows this is string
62book.year = 2024         // TypeScript knows this is number | undefined
63</script>
64```
65 
66## Why This Happens
67 
68When you use `reactive()`, Vue automatically unwraps any nested refs:
69 
70```typescript
71import { reactive, ref, Ref } from 'vue'
72 
73const name = ref('John')
74const state = reactive({
75  name: name  // This is a Ref<string>
76})
77 
78// At runtime, state.name is 'John' (string), NOT a Ref
79console.log(state.name)       // 'John' (not ref object)
80console.log(state.name.value) // Runtime error: .value doesn't exist
81 
82// The ACTUAL return type is different from what you'd expect
83// reactive<{ name: Ref<string> }>() does NOT return { name: Ref<string> }
84// It returns { name: string } due to automatic unwrapping
85```
86 
87## Correct Patterns
88 
89### Pattern 1: Simple Interface Annotation
90 
91```vue
92<script setup lang="ts">
93interface FormState {
94  name: string
95  email: string
96  age: number
97}
98 
99const form: FormState = reactive({
100  name: '',
101  email: '',
102  age: 0
103})
104</script>
105```
106 
107### Pattern 2: Partial for Optional Fields
108 
109```vue
110<script setup lang="ts">
111interface User {
112  id: string
113  name: string
114  email: string
115}
116 
117// Start with partial data
118const user: Partial<User> = reactive({})
119 
120// Fill in later
121user.id = '123'
122user.name = 'John'
123</script>
124```
125 
126### Pattern 3: Use ref() Instead
127 
128For simpler cases, prefer `ref()` which has more predictable typing:
129 
130```vue
131<script setup lang="ts">
132interface User {
133  id: string
134  name: string
135}
136 
137// ref() works well with generics
138const user = ref<User>({
139  id: '1',
140  name: 'John'
141})
142 
143// Access with .value - clear and predictable
144user.value.name = 'Jane'
145</script>
146```
147 
148## Generic Composables: Use Ref<T> or shallowRef
149 
150When working with generic type parameters in composables:
151 
152```typescript
153// PROBLEM: Generic T with ref() causes UnwrapRef issues
154function useBroken<T>(initial: T) {
155  const state = ref(initial)  // Type becomes Ref<UnwrapRef<T>>
156  state.value = initial       // Error: T is not assignable to UnwrapRef<T>
157  return state
158}
159 
160// SOLUTION 1: Use explicit Ref<T> type
161function useFixed1<T>(initial: T) {
162  const state: Ref<T> = ref(initial) as Ref<T>
163  return state
164}
165 
166// SOLUTION 2: Use shallowRef (no unwrapping)
167function useFixed2<T>(initial: T) {
168  const state = shallowRef(initial)  // Properly typed as ShallowRef<T>
169  return state
170}
171```
172 
173## When Generic Argument IS Safe
174 
175For simple non-ref values without nested reactivity, the generic is safe:
176 
177```typescript
178// Safe: no nested refs
179const state = reactive<{ count: number; name: string }>({
180  count: 0,
181  name: ''
182})
183 
184// Also safe: explicit simple types
185const list = reactive<string[]>([])
186const map = reactive<Map<string, number>>(new Map())
187```
188 
189The issue only arises when:
1901. You have nested Ref types in your interface
1912. You're using generic type parameters that might contain refs
192 
193## Reference
194- [Vue.js TypeScript with Composition API - Typing reactive()](https://vuejs.org/guide/typescript/composition-api.html#typing-reactive)
195- [GitHub Issue: ref with generic type](https://github.com/vuejs/core/discussions/9564)
196- [Vue TypeScript Caveats Gist](https://gist.github.com/LinusBorg/e041ff635994b50b7cec9383c3a067f1)
197