1# Vue Components
2 
3Patterns for Vue 3 components using Composition API with `<script setup>`.
4 
5## Quick Reference
6 
7| Pattern               | Syntax                                                          |
8| --------------------- | --------------------------------------------------------------- |
9| Props (destructured)  | `const { name = 'default' } = defineProps<{ name?: string }>()` |
10| Props (template-only) | `defineProps<{ name: string }>()`                               |
11| Emits                 | `const emit = defineEmits<{ click: [id: number] }>()`           |
12| Two-way binding       | `const model = defineModel<string>()`                           |
13| Slots shorthand       | `<template #header>` not `<template v-slot:header>`             |
14 
15## Naming
16 
17**Files:** PascalCase (`UserProfile.vue`) OR kebab-case (`user-profile.vue`) - be consistent
18 
19**Component names in code:** Always PascalCase
20 
21**Composition:** General → Specific: `SearchButtonClear.vue` not `ClearSearchButton.vue`
22 
23## Props
24 
25**Destructure with defaults (Vue 3.5+)** when used in script or need defaults:
26 
27```ts
28const { count = 0, message = 'Hello' } = defineProps<{
29  count?: number
30  message?: string
31  required: boolean
32}>()
33 
34// Use directly - maintains reactivity
35console.log(count + 1)
36 
37// ⚠️ When passing to watchers/functions, wrap in getter:
38watch(() => count, (newVal) => { ... }) // ✅ Correct
39watch(count, (newVal) => { ... })        // ❌ Won't work
40```
41 
42**Non-destructured** only if props ONLY used in template:
43 
44```ts
45defineProps<{ count: number }>()
46// Template: {{ count }}
47```
48 
49**Same-name shorthand (Vue 3.4+):** `:count` instead of `:count="count"`
50 
51```vue
52<MyComponent :count :user :items />
53<!-- Same as: :count="count" :user="user" :items="items" -->
54```
55 
56[Reactive destructuring docs](https://vuejs.org/guide/components/props#reactive-props-destructure)
57 
58## Emits
59 
60Type-safe event definitions:
61 
62```ts
63const emit = defineEmits<{
64  update: [id: number, value: string] // multiple args
65  close: [] // no args
66}>()
67 
68// Usage
69emit('update', 123, 'new value')
70emit('close')
71```
72 
73**Template syntax:** kebab-case (`@update-item`) vs camelCase in script (`updateItem`)
74 
75## Slots
76 
77**Always use shorthand:** `<template #header>` not `<template v-slot:header>`
78 
79**Always explicit `<template>` tags** for all slots
80 
81```vue
82<template>
83  <Card>
84    <template #header>
85      <h2>Title</h2>
86    </template>
87    <template #default>
88      Content
89    </template>
90  </Card>
91</template>
92```
93 
94## defineModel() - Two-Way Binding
95 
96Replaces manual `modelValue` prop + `update:modelValue` emit.
97 
98### Basic
99 
100```vue
101<script setup lang="ts">
102const title = defineModel<string>()
103</script>
104 
105<template>
106  <input v-model="title">
107</template>
108```
109 
110### With Options
111 
112```vue
113<script setup lang="ts">
114const [title, modifiers] = defineModel<string>({
115  default: 'default value',
116  required: true,
117  get: (value) => value.trim(),
118  set: (value) => {
119    if (modifiers.capitalize) {
120      return value.charAt(0).toUpperCase() + value.slice(1)
121    }
122    return value
123  },
124})
125</script>
126```
127 
128**⚠️ Warning:** When using `default` without parent providing a value, parent and child can de-sync (parent `undefined`, child has default). Always provide matching defaults in parent or make prop required.
129 
130**Prevent double-emit with `required: true`:**
131 
132```ts
133// ❌ Without required - emits twice (undefined then value)
134const model = defineModel<Item>()
135 
136// ✅ With required - single emit
137const model = defineModel<Item>({ required: true })
138```
139 
140Use `required: true` when the model should always have a value to avoid the double-emit issue during initialization.
141 
142### Multiple Models
143 
144Default assumes `modelValue` prop. For multiple bindings, use explicit names:
145 
146```vue
147<script setup lang="ts">
148const firstName = defineModel<string>('firstName')
149const age = defineModel<number>('age')
150</script>
151 
152<!-- Usage -->
153<UserForm v-model:first-name="user.firstName" v-model:age="user.age" />
154```
155 
156[v-model modifiers docs](https://vuejs.org/guide/components/v-model#handling-v-model-modifiers)
157 
158## Reusable Templates
159 
160For typed, scoped template snippets within a component:
161 
162```vue
163<script setup lang="ts">
164import { createReusableTemplate } from '@vueuse/core'
165 
166const [DefineItem, UseItem] = createReusableTemplate<{
167  item: SearchItem
168  icon: string
169  color?: 'red' | 'green' | 'blue'
170}>()
171</script>
172 
173<template>
174  <DefineItem v-slot="{ item, icon, color }">
175    <div :class="color">
176      <Icon :name="icon" />
177      {{ item.name }}
178    </div>
179  </DefineItem>
180 
181  <!-- Reuse multiple times -->
182  <UseItem v-for="item in items" :key="item.id" :item :icon="getIcon(item)" />
183</template>
184```
185 
186## Template Refs (Vue 3.5+)
187 
188Use `useTemplateRef()` for type-safe template references with IDE support:
189 
190```vue
191<script setup lang="ts">
192import { useTemplateRef, onMounted } from 'vue'
193 
194const input = useTemplateRef<HTMLInputElement>('my-input')
195 
196onMounted(() => {
197  input.value?.focus()
198})
199</script>
200 
201<template>
202  <input ref="my-input">
203</template>
204```
205 
206**Benefits over `ref()`:**
207 
208- Type-safe with generics
209- Better IDE autocomplete and refactoring
210- Explicit ref name as string literal
211 
212**Dynamic refs:**
213 
214```vue
215<script setup lang="ts">
216const items = ref(['a', 'b', 'c'])
217const itemRefs = useTemplateRef<HTMLElement>('item')
218 
219// Access refs after mount
220onMounted(() => {
221  console.log(itemRefs.value) // Array of elements
222})
223</script>
224 
225<template>
226  <div v-for="item in items" :key="item" ref="item">
227    {{ item }}
228  </div>
229</template>
230```
231 
232**Component refs with generics:**
233 
234For generic components, use `ComponentExposed` from `vue-component-type-helpers`:
235 
236```ts
237import type { ComponentExposed } from 'vue-component-type-helpers'
238import MyGenericComponent from './MyGenericComponent.vue'
239 
240// Get exposed methods/properties with correct generic types
241const compRef = useTemplateRef<ComponentExposed<typeof MyGenericComponent>>('comp')
242 
243onMounted(() => {
244  compRef.value?.someExposedMethod() // Typed!
245})
246```
247 
248Install: `pnpm add -D vue-component-type-helpers`
249 
250## SSR Hydration (Vue 3.5+)
251 
252**Suppress hydration mismatches** for values that differ between server/client:
253 
254```vue
255<template>
256  <!-- Client-side only values -->
257  <span data-allow-mismatch>{{ new Date().toLocaleString() }}</span>
258 
259  <!-- Specific mismatch types -->
260  <span data-allow-mismatch="text">{{ timestamp }}</span>
261  <span data-allow-mismatch="children">
262    <ClientOnly>...</ClientOnly>
263  </span>
264  <span data-allow-mismatch="style">...</span>
265  <span data-allow-mismatch="class">...</span>
266  <span data-allow-mismatch="attribute">...</span>
267</template>
268```
269 
270**Generate SSR-stable IDs:**
271 
272```vue
273<script setup lang="ts">
274import { useId } from 'vue'
275 
276const id = useId() // Stable across server/client renders
277</script>
278 
279<template>
280  <label :for="id">Name</label>
281  <input :id="id">
282</template>
283```
284 
285## Deferred Teleport (Vue 3.5+)
286 
287Teleport to elements rendered later in the same cycle:
288 
289```vue
290<template>
291  <!-- This renders first -->
292  <Teleport defer to="#late-div">
293    <span>Deferred content</span>
294  </Teleport>
295 
296  <!-- This renders after, but Teleport waits -->
297  <div id="late-div"></div>
298</template>
299```
300 
301Without `defer`, teleport to `#late-div` would fail since it doesn't exist yet.
302 
303## Common Mistakes
304 
305**Using `const props =` with destructured values:**
306 
307```ts
308// ❌ Wrong
309const props = defineProps<{ count: number }>()
310const { count } = props // Loses reactivity
311```
312 
313**Forgetting TypeScript types:**
314 
315```ts
316// ❌ Wrong
317const emit = defineEmits(['update'])
318 
319// ✅ Correct
320const emit = defineEmits<{ update: [id: number] }>()
321```
322 
323**Components >300 lines:** Split into smaller components or extract logic to composables
324