1---
2title: Component Data Flow Best Practices
3impact: HIGH
4impactDescription: Clear data flow between components prevents state bugs, stale UI, and brittle coupling
5type: best-practice
6tags: [vue3, props, emits, v-model, provide-inject, data-flow, typescript]
7---
8 
9# Component Data Flow Best Practices
10 
11**Impact: HIGH** - Vue components stay reliable when data flow is explicit: props go down, events go up, `v-model` handles two-way bindings, and provide/inject supports cross-tree dependencies. Blurring these boundaries leads to stale state, hidden coupling, and hard-to-debug UI.
12 
13The main principle of data flow in Vue.js is **Props Down / Events Up**. This is the most maintainable default, and one-way flow scales well.
14 
15## Task List
16 
17- Treat props as read-only inputs
18- Use props/emit for component communication; reserve refs for imperative actions
19- When refs are required for imperative APIs, type them with template refs
20- Emit events instead of mutating parent state directly
21- Use `defineModel` for v-model in modern Vue (3.4+)
22- Handle v-model modifiers deliberately in child components
23- Use symbols for provide/inject keys to avoid props drilling (over ~3 layers)
24- Keep mutations in the provider or expose explicit actions
25- In TypeScript projects, prefer type-based `defineProps`, `defineEmits`, and `InjectionKey`
26 
27## Props: One-Way Data Down
28 
29Props are inputs. Do not mutate them in the child.
30 
31**BAD:**
32```vue
33<script setup>
34const props = defineProps({ count: Number })
35 
36function increment() {
37  props.count++
38}
39</script>
40```
41 
42**GOOD:**
43 
44If state needs to change, emit an event, use `v-model` or create a local copy.
45 
46## Prefer props/emit over component refs
47 
48**BAD:**
49```vue
50<script setup>
51import { ref } from 'vue'
52import UserForm from './UserForm.vue'
53 
54const formRef = ref(null)
55 
56function submitForm() {
57  if (formRef.value.isValid) {
58    formRef.value.submit()
59  }
60}
61</script>
62 
63<template>
64  <UserForm ref="formRef" />
65  <button @click="submitForm">Submit</button>
66</template>
67```
68 
69**GOOD:**
70```vue
71<script setup>
72import UserForm from './UserForm.vue'
73 
74function handleSubmit(formData) {
75  api.submit(formData)
76}
77</script>
78 
79<template>
80  <UserForm @submit="handleSubmit" />
81</template>
82```
83 
84## Type component refs when imperative access is required
85 
86Prefer props/emits by default. When a parent must call an exposed child method, type the ref explicitly and expose only the intended API from the child with `defineExpose`.
87 
88**BAD:**
89```vue
90<script setup lang="ts">
91import { ref, onMounted } from 'vue'
92import DialogPanel from './DialogPanel.vue'
93 
94const panelRef = ref(null)
95 
96onMounted(() => {
97  panelRef.value.open()
98})
99</script>
100 
101<template>
102  <DialogPanel ref="panelRef" />
103</template>
104```
105 
106**GOOD:**
107```vue
108<!-- DialogPanel.vue -->
109<script setup lang="ts">
110function open() {}
111 
112defineExpose({ open })
113</script>
114```
115 
116```vue
117<!-- Parent.vue -->
118<script setup lang="ts">
119import { onMounted, useTemplateRef } from 'vue'
120import DialogPanel from './DialogPanel.vue'
121 
122// Vue 3.5+ with useTemplateRef
123const panelRef = useTemplateRef('panelRef')
124 
125// Before Vue 3.5 with manual typing and ref
126// const panelRef = ref<InstanceType<typeof DialogPanel> | null>(null)
127 
128onMounted(() => {
129  panelRef.value?.open()
130})
131</script>
132 
133<template>
134  <DialogPanel ref="panelRef" />
135</template>
136```
137 
138## Emits: Explicit Events Up
139 
140Component events do not bubble. If a parent needs to know about an event, re-emit it explicitly.
141 
142**BAD:**
143```vue
144<!-- Parent expects "saved" from grandchild, but it won't bubble -->
145<Child @saved="onSaved" />
146```
147 
148**GOOD:**
149```vue
150<!-- Child.vue -->
151<script setup>
152const emit = defineEmits(['saved'])
153 
154function onGrandchildSaved(payload) {
155  emit('saved', payload)
156}
157</script>
158 
159<template>
160  <Grandchild @saved="onGrandchildSaved" />
161</template>
162```
163 
164**Event naming:** use kebab-case in templates and camelCase in script:
165```vue
166<script setup>
167const emit = defineEmits(['updateUser'])
168</script>
169 
170<template>
171  <ProfileForm @update-user="emit('updateUser', $event)" />
172</template>
173```
174 
175## `v-model`: Predictable Two-Way Bindings
176 
177Use `defineModel` by default for component bindings and emit updates on input. Only use the `modelValue` + `update:modelValue` pattern if you are on Vue < 3.4.
178 
179**BAD:**
180```vue
181<script setup>
182const props = defineProps({ value: String })
183</script>
184 
185<template>
186  <input :value="props.value" @input="$emit('input', $event.target.value)" />
187</template>
188```
189 
190**GOOD (Vue 3.4+):**
191```vue
192<script setup>
193const model = defineModel({ type: String })
194</script>
195 
196<template>
197  <input v-model="model" />
198</template>
199```
200 
201**GOOD (Vue < 3.4):**
202```vue
203<script setup>
204const props = defineProps({ modelValue: String })
205const emit = defineEmits(['update:modelValue'])
206</script>
207 
208<template>
209  <input
210    :value="props.modelValue"
211    @input="emit('update:modelValue', $event.target.value)"
212  />
213</template>
214```
215 
216If you need the updated value immediately after a change, use the input event value or `nextTick` in the parent.
217 
218## Provide/Inject: Shared Context Without Prop Drilling
219 
220Use provide/inject for cross-tree state, but keep mutations centralized in the provider and expose explicit actions.
221 
222**BAD:**
223```vue
224// Provider.vue
225provide('theme', reactive({ dark: false }))
226 
227// Consumer.vue
228const theme = inject('theme')
229// Mutating shared state from any depth becomes hard to track
230theme.dark = true
231```
232 
233**GOOD:**
234```vue
235// Provider.vue
236const theme = reactive({ dark: false })
237const toggleTheme = () => { theme.dark = !theme.dark }
238 
239provide(themeKey, readonly(theme))
240provide(themeActionsKey, { toggleTheme })
241 
242// Consumer.vue
243const theme = inject(themeKey)
244const { toggleTheme } = inject(themeActionsKey)
245```
246 
247Use symbols for keys to avoid collisions in large apps:
248```ts
249export const themeKey = Symbol('theme')
250export const themeActionsKey = Symbol('theme-actions')
251```
252 
253## Use TypeScript Contracts for Public Component APIs
254 
255In TypeScript projects, type component boundaries directly with `defineProps`, `defineEmits`, and `InjectionKey` so invalid payloads and mismatched injections fail at compile time.
256 
257**BAD:**
258```vue
259<script setup lang="ts">
260import { inject } from 'vue'
261 
262const props = defineProps({
263  userId: String
264})
265 
266const emit = defineEmits(['save'])
267const settings = inject('settings')
268 
269// Payload shape is not checked here
270emit('save', 123)
271 
272// Key is string-based and not type-safe
273settings?.theme = 'dark'
274</script>
275```
276 
277**GOOD:**
278```vue
279<script setup lang="ts">
280import { inject, provide } from 'vue'
281import type { InjectionKey } from 'vue'
282 
283interface Props {
284  userId: string
285}
286 
287interface Emits {
288  save: [payload: { id: string; draft: boolean }]
289}
290 
291interface Settings {
292  theme: 'light' | 'dark'
293}
294 
295const settingsKey: InjectionKey<Settings> = Symbol('settings')
296 
297const props = defineProps<Props>()
298const emit = defineEmits<Emits>()
299 
300provide(settingsKey, { theme: 'light' })
301 
302const settings = inject(settingsKey)
303if (settings) {
304  emit('save', { id: props.userId, draft: false })
305}
306</script>
307```
308