1---
2title: In-DOM Template Parsing Caveats
3impact: HIGH
4impactDescription: Browser HTML parsing before Vue compilation causes case sensitivity, self-closing tag, and element nesting issues
5type: gotcha
6tags: [vue3, templates, in-dom, html-parsing, kebab-case, self-closing-tags]
7---
8 
9# In-DOM Template Parsing Caveats
10 
11**Impact: HIGH** - When writing Vue templates directly in the DOM (not in `.vue` files), the browser's native HTML parser processes the template BEFORE Vue sees it. This causes three critical issues: case sensitivity problems, self-closing tag failures, and element placement restrictions.
12 
13These issues do NOT apply to Single-File Components (SFCs) or string templates where Vue's compiler handles parsing directly.
14 
15## Task Checklist
16 
17- [ ] Use kebab-case for component names in in-DOM templates
18- [ ] Use kebab-case for prop names in in-DOM templates
19- [ ] Use explicit closing tags (not self-closing) in in-DOM templates
20- [ ] Use `is="vue:component-name"` for components inside restricted elements
21- [ ] Prefer SFCs to avoid all in-DOM parsing issues
22 
23## Issue 1: Case Insensitivity
24 
25HTML is case-insensitive. The browser lowercases everything before Vue sees it.
26 
27**Incorrect (in-DOM template):**
28```html
29<!-- Browser converts to: <blogpost posttitle="hello"> -->
30<BlogPost postTitle="hello" @updatePost="onUpdate"></BlogPost>
31```
32 
33**Correct (in-DOM template):**
34```html
35<!-- Use kebab-case for everything -->
36<blog-post post-title="hello" @update-post="onUpdate"></blog-post>
37```
38 
39**In SFCs, PascalCase works fine:**
40```vue
41<!-- BlogPost.vue - PascalCase recommended -->
42<template>
43  <BlogPost postTitle="hello" @updatePost="onUpdate" />
44</template>
45```
46 
47## Issue 2: Self-Closing Tags Fail
48 
49HTML only allows self-closing syntax for void elements (`<input>`, `<img>`, etc.). For all others, the browser expects closing tags.
50 
51**Incorrect (in-DOM template):**
52```html
53<!-- Browser thinks the tag never closed, breaks nesting -->
54<my-component />
55<another-component />
56```
57 
58**Correct (in-DOM template):**
59```html
60<!-- Explicit closing tags required -->
61<my-component></my-component>
62<another-component></another-component>
63```
64 
65**In SFCs, self-closing works fine:**
66```vue
67<template>
68  <MyComponent />
69  <AnotherComponent />
70</template>
71```
72 
73## Issue 3: Element Placement Restrictions
74 
75Some HTML elements have strict rules about valid children. Invalid elements are hoisted out by the browser before Vue sees the template.
76 
77**Restricted parent elements:**
78- `<ul>`, `<ol>` - only allow `<li>`
79- `<table>` - only allows `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<caption>`, `<colgroup>`
80- `<tr>` - only allows `<td>`, `<th>`
81- `<select>` - only allows `<option>`, `<optgroup>`
82 
83**Incorrect (in-DOM template):**
84```html
85<!-- Browser hoists blog-post-row outside the table -->
86<table>
87  <blog-post-row v-for="post in posts" :post="post"></blog-post-row>
88</table>
89 
90<!-- Renders as: -->
91<blog-post-row></blog-post-row>
92<blog-post-row></blog-post-row>
93<table></table>
94```
95 
96**Correct (in-DOM template):**
97```html
98<!-- Use is="vue:component-name" on a valid native element -->
99<table>
100  <tr is="vue:blog-post-row" v-for="post in posts" :key="post.id" :post="post"></tr>
101</table>
102```
103 
104```html
105<ul>
106  <li is="vue:todo-item" v-for="todo in todos" :key="todo.id" :todo="todo"></li>
107</ul>
108```
109 
110**Important:** The `vue:` prefix is required! Without it, `is` is treated as a native customized built-in element attribute.
111 
112```html
113<!-- WRONG: Missing vue: prefix -->
114<tr is="blog-post-row"></tr>
115 
116<!-- CORRECT: With vue: prefix -->
117<tr is="vue:blog-post-row"></tr>
118```
119 
120## When Do These Apply?
121 
122| Template Type | Affected? | Example |
123|---------------|-----------|---------|
124| Single-File Component (`.vue`) | No | `<template>` section |
125| String template | No | `template: '<div>...</div>'` |
126| In-DOM template | **Yes** | `<div id="app">...</div>` |
127| `<script type="text/x-template">` | **Yes** | Browser parses the script content |
128 
129## Best Practice: Use SFCs
130 
131The simplest solution is to use Single-File Components (`.vue` files) which completely avoid in-DOM parsing issues:
132 
133```vue
134<!-- MyComponent.vue - All issues avoided -->
135<script setup>
136import BlogPost from './BlogPost.vue'
137</script>
138 
139<template>
140  <BlogPost postTitle="hello" @updatePost="onUpdate" />
141 
142  <table>
143    <BlogPostRow v-for="post in posts" :key="post.id" :post="post" />
144  </table>
145</template>
146```
147 
148## Reference
149- [Vue.js - In-DOM Template Parsing Caveats](https://vuejs.org/guide/essentials/component-basics.html#in-dom-template-parsing-caveats)
150