1---
2title: Single-File Component Structure, Styling, and Template Patterns
3impact: MEDIUM
4impactDescription: Consistent SFC structure and styling choices improve maintainability, tooling support, and render performance
5type: best-practice
6tags: [vue3, sfc, scoped-css, styles, build-tools, performance, template, v-html, v-for, computed, v-if, v-show]
7---
8 
9# Single-File Component Structure, Styling, and Template Patterns
10 
11**Impact: MEDIUM** - Using SFCs with consistent structure and performant styling keeps components easier to maintain and avoids unnecessary render overhead.
12 
13## Task List
14 
15- Use `.vue` SFCs instead of separate `.js`/`.ts` and `.css` files for components
16- Colocate template, script, and styles in the same SFC by default
17- Use PascalCase for component names in templates and filenames
18- Prefer component-scoped styles
19- Prefer class selectors (not element selectors) in scoped CSS for performance
20- Access DOM / component refs with `useTemplateRef()` in Vue 3.5+
21- Use camelCase keys in `:style` bindings for consistency and IDE support
22- Use `v-for` and `v-if` correctly
23- Never use `v-html` with untrusted/user-provided content
24- Choose `v-if` vs `v-show` based on toggle frequency and initial render cost
25 
26## Colocate template, script, and styles
27 
28**BAD:**
29```
30components/
31├── UserCard.vue
32├── UserCard.js
33└── UserCard.css
34```
35 
36**GOOD:**
37```vue
38<!-- components/UserCard.vue -->
39<script setup>
40import { computed } from 'vue'
41 
42const props = defineProps({
43  user: { type: Object, required: true }
44})
45 
46const displayName = computed(() =>
47  `${props.user.firstName} ${props.user.lastName}`
48)
49</script>
50 
51<template>
52  <div class="user-card">
53    <h3 class="name">{{ displayName }}</h3>
54  </div>
55</template>
56 
57<style scoped>
58.user-card {
59  padding: 1rem;
60}
61 
62.name {
63  margin: 0;
64}
65</style>
66```
67 
68## Use PascalCase for component names
69 
70**BAD:**
71```vue
72<script setup>
73import userProfile from './user-profile.vue'
74</script>
75 
76<template>
77  <user-profile :user="currentUser" />
78</template>
79```
80 
81**GOOD:**
82```vue
83<script setup>
84import UserProfile from './UserProfile.vue'
85</script>
86 
87<template>
88  <UserProfile :user="currentUser" />
89</template>
90```
91 
92## Best practices for `<style>` block in SFCs
93 
94### Prefer component-scoped styles
95 
96- Use `<style scoped>` for styles that belong to a component.
97- Keep **global CSS** in a dedicated file (e.g. `src/assets/main.css`) for resets, typography, tokens, etc.
98- Use `:deep()` sparingly (edge cases only).
99 
100**BAD:**
101 
102```vue
103<style>
104/* ❌ leaks everywhere */
105button { border-radius: 999px; }
106</style>
107```
108 
109**GOOD:**
110 
111```vue
112<style scoped>
113.button { border-radius: 999px; }
114</style>
115```
116 
117**GOOD:**
118 
119```css
120/* src/assets/main.css */
121/* ✅ resets, tokens, typography, app-wide rules */
122:root { --radius: 999px; }
123```
124 
125### Use class selectors in scoped CSS
126 
127**BAD:**
128```vue
129<template>
130  <article>
131    <h1>{{ title }}</h1>
132    <p>{{ subtitle }}</p>
133  </article>
134</template>
135 
136<style scoped>
137article { max-width: 800px; }
138h1 { font-size: 2rem; }
139p { line-height: 1.6; }
140</style>
141```
142 
143**GOOD:**
144```vue
145<template>
146  <article class="article">
147    <h1 class="article-title">{{ title }}</h1>
148    <p class="article-subtitle">{{ subtitle }}</p>
149  </article>
150</template>
151 
152<style scoped>
153.article { max-width: 800px; }
154.article-title { font-size: 2rem; }
155.article-subtitle { line-height: 1.6; }
156</style>
157```
158 
159## Access DOM / component refs with `useTemplateRef()`
160 
161For Vue 3.5+: use `useTemplateRef()` to access template refs.
162 
163```vue
164<script setup lang="ts">
165import { onMounted, useTemplateRef } from 'vue'
166 
167const inputRef = useTemplateRef<HTMLInputElement>('input')
168 
169onMounted(() => {
170  inputRef.value?.focus()
171})
172</script>
173 
174<template>
175  <input ref="input" />
176</template>
177```
178 
179## Use camelCase in `:style` bindings
180 
181**BAD:**
182```vue
183<template>
184  <div :style="{ 'font-size': fontSize + 'px', 'background-color': bg }">
185    Content
186  </div>
187</template>
188```
189 
190**GOOD:**
191```vue
192<template>
193  <div :style="{ fontSize: fontSize + 'px', backgroundColor: bg }">
194    Content
195  </div>
196</template>
197```
198 
199## Use `v-for` and `v-if` correctly
200 
201### Always provide a stable `:key`
202 
203- Prefer primitive keys (`string | number`).
204- Avoid using objects as keys.
205 
206**GOOD:**
207 
208```vue
209<li v-for="item in items" :key="item.id">
210  <input v-model="item.text" />
211</li>
212```
213 
214### Avoid `v-if` and `v-for` on the same element
215 
216It leads to unclear intent and unnecessary work.
217([Reference](https://vuejs.org/guide/essentials/list.html#v-for-with-v-if))
218 
219**To filter items**
220**BAD:**
221 
222```vue
223<li v-for="user in users" v-if="user.active" :key="user.id">
224  {{ user.name }}
225</li>
226```
227 
228**GOOD:**
229 
230```vue
231<script setup lang="ts">
232import { computed } from 'vue'
233 
234const activeUsers = computed(() => users.value.filter(u => u.active))
235</script>
236 
237<template>
238  <li v-for="user in activeUsers" :key="user.id">
239    {{ user.name }}
240  </li>
241</template>
242```
243 
244**To conditionally show/hide the entire list**
245**GOOD:**
246 
247```vue
248<ul v-if="shouldShowUsers">
249  <li v-for="user in users" :key="user.id">
250    {{ user.name }}
251  </li>
252</ul>
253```
254 
255## Never render untrusted HTML with `v-html`
256 
257**BAD:**
258```vue
259<template>
260  <!-- DANGEROUS: untrusted input can inject scripts -->
261  <article v-html="userProvidedContent"></article>
262</template>
263```
264 
265**GOOD:**
266```vue
267<script setup>
268import { computed } from 'vue'
269import DOMPurify from 'dompurify'
270 
271const props = defineProps<{
272  trustedHtml?: string
273  plainText: string
274}>()
275 
276const safeHtml = computed(() => DOMPurify.sanitize(props.trustedHtml ?? ''))
277</script>
278 
279<template>
280  <!-- Preferred: escaped interpolation -->
281  <p>{{ props.plainText }}</p>
282 
283  <!-- Only for trusted/sanitized HTML -->
284  <article v-html="safeHtml"></article>
285</template>
286```
287 
288## Choose `v-if` vs `v-show` by toggle behavior
289 
290**BAD:**
291```vue
292<template>
293  <!-- Frequent toggles with v-if cause repeated mount/unmount -->
294  <ComplexPanel v-if="isPanelOpen" />
295 
296  <!-- Rarely shown content with v-show pays initial render cost -->
297  <AdminPanel v-show="isAdmin" />
298</template>
299```
300 
301**GOOD:**
302```vue
303<template>
304  <!-- Frequent toggles: keep in DOM, toggle display -->
305  <ComplexPanel v-show="isPanelOpen" />
306 
307  <!-- Rare condition: lazy render only when true -->
308  <AdminPanel v-if="isAdmin" />
309</template>
310```
311