1---
2title: Wrap Mutable Default Values in Factory Functions
3impact: HIGH
4impactDescription: Without factory functions, all component instances share the same mutable reference causing cross-contamination bugs
5type: gotcha
6tags: [vue3, typescript, props, withDefaults, mutable-types]
7---
8 
9# Wrap Mutable Default Values in Factory Functions
10 
11**Impact: HIGH** - When using `withDefaults()` with type-based props declaration, default values for mutable types (arrays and objects) MUST be wrapped in factory functions. Without this, all component instances share the same reference, causing bugs where modifying the prop in one instance affects all others.
12 
13## Task Checklist
14 
15- [ ] Always wrap array defaults in factory functions: `() => []`
16- [ ] Always wrap object defaults in factory functions: `() => ({})`
17- [ ] Primitive types (string, number, boolean) do NOT need factory functions
18- [ ] Review existing components for this pattern
19 
20## The Problem: Shared Mutable References
21 
22**WRONG - Shared reference across instances:**
23```vue
24<script setup lang="ts">
25interface Props {
26  items?: string[]
27  config?: { theme: string }
28}
29 
30const props = withDefaults(defineProps<Props>(), {
31  items: ['default'],           // WRONG! All instances share this array
32  config: { theme: 'light' }    // WRONG! All instances share this object
33})
34</script>
35```
36 
37When you have multiple instances of this component:
38```vue
39<template>
40  <!-- Both share the SAME items array! -->
41  <MyComponent ref="comp1" />
42  <MyComponent ref="comp2" />
43</template>
44 
45<script setup>
46// If comp1 modifies its items, comp2's items change too!
47comp1.value.items.push('new item')  // comp2 also has 'new item' now
48</script>
49```
50 
51## The Solution: Factory Functions
52 
53**CORRECT - Unique instance per component:**
54```vue
55<script setup lang="ts">
56interface Props {
57  items?: string[]
58  config?: { theme: string }
59  nested?: { data: { values: number[] } }
60}
61 
62const props = withDefaults(defineProps<Props>(), {
63  items: () => ['default'],                      // Factory function!
64  config: () => ({ theme: 'light' }),            // Factory function!
65  nested: () => ({ data: { values: [] } })       // Factory function!
66})
67</script>
68```
69 
70## When Factory Functions Are Required
71 
72| Type | Factory Required | Example Default |
73|------|-----------------|-----------------|
74| `string` | No | `'hello'` |
75| `number` | No | `42` |
76| `boolean` | No | `false` |
77| `string[]` | **Yes** | `() => []` |
78| `number[]` | **Yes** | `() => [1, 2, 3]` |
79| `object` | **Yes** | `() => ({})` |
80| `Map` | **Yes** | `() => new Map()` |
81| `Set` | **Yes** | `() => new Set()` |
82| `Date` | **Yes** | `() => new Date()` |
83 
84## Complete Example
85 
86```vue
87<script setup lang="ts">
88interface User {
89  id: string
90  name: string
91}
92 
93interface Props {
94  // Primitives - no factory needed
95  title?: string
96  count?: number
97  disabled?: boolean
98 
99  // Mutable types - factory required
100  items?: string[]
101  users?: User[]
102  metadata?: Record<string, unknown>
103  selectedIds?: Set<string>
104}
105 
106const props = withDefaults(defineProps<Props>(), {
107  // Primitives
108  title: 'Default Title',
109  count: 0,
110  disabled: false,
111 
112  // Mutable types with factory functions
113  items: () => [],
114  users: () => [],
115  metadata: () => ({}),
116  selectedIds: () => new Set()
117})
118</script>
119```
120 
121## Vue 3.5+ Reactive Props Destructure
122 
123Vue 3.5 introduces reactive props destructure, which handles this automatically:
124 
125```vue
126<script setup lang="ts">
127interface Props {
128  items?: string[]
129  config?: { theme: string }
130}
131 
132// Vue 3.5+ - defaults work correctly without explicit factory functions
133const {
134  items = ['default'],        // Each instance gets its own array
135  config = { theme: 'light' } // Each instance gets its own object
136} = defineProps<Props>()
137</script>
138```
139 
140Note: Under the hood, Vue 3.5 handles the instance isolation for you.
141 
142## Common Bug Pattern
143 
144This bug often appears in list/table components:
145 
146```vue
147<!-- ListItem.vue - BUGGY -->
148<script setup lang="ts">
149interface Props {
150  selectedRows?: number[]
151}
152 
153// All ListItems share the same selectedRows array!
154const props = withDefaults(defineProps<Props>(), {
155  selectedRows: []  // BUG: Missing factory function
156})
157</script>
158```
159 
160Users report: "Selecting a row in one table selects it in all tables!"
161 
162**Fix:**
163```typescript
164const props = withDefaults(defineProps<Props>(), {
165  selectedRows: () => []  // Now each instance has its own array
166})
167```
168 
169## Reference
170- [Vue.js TypeScript with Composition API - Default Props](https://vuejs.org/guide/typescript/composition-api.html#props-default-values)
171- [Vue RFC - Reactive Props Destructure](https://github.com/vuejs/rfcs/discussions/502)
172