1---
2title: Do Not Rely on Internal VNode Properties
3impact: MEDIUM
4impactDescription: Using undocumented vnode properties causes code to break on Vue updates
5type: gotcha
6tags: [vue3, render-function, vnode, internal-api]
7---
8 
9# Do Not Rely on Internal VNode Properties
10 
11**Impact: MEDIUM** - The `VNode` interface contains many internal properties used by Vue's rendering system. Relying on any properties other than the documented public ones will cause your code to break when Vue's internal implementation changes.
12 
13Only use the documented vnode properties: `type`, `props`, `children`, and `key`. All other properties are internal implementation details that may change without notice between Vue versions.
14 
15## Task Checklist
16 
17- [ ] Only access documented vnode properties: `type`, `props`, `children`, `key`
18- [ ] Never access properties like `el`, `component`, `shapeFlag`, `patchFlag`, etc.
19- [ ] If you need DOM element access, use template refs instead
20- [ ] Treat vnodes as opaque data structures for rendering, not inspection
21 
22**Incorrect:**
23```javascript
24import { h } from 'vue'
25 
26export default {
27  setup(props, { slots }) {
28    return () => {
29      const slotContent = slots.default?.()
30 
31      // WRONG: Accessing internal properties
32      if (slotContent?.[0]?.el) {
33        // el is an internal property
34        console.log(slotContent[0].el.tagName)
35      }
36 
37      // WRONG: Using shapeFlag internal property
38      if (slotContent?.[0]?.shapeFlag & 1) {
39        // This is internal implementation
40      }
41 
42      return h('div', slotContent)
43    }
44  }
45}
46```
47 
48```javascript
49// WRONG: Inspecting component instance via vnode
50const vnode = h(MyComponent)
51console.log(vnode.component) // Internal property
52console.log(vnode.appContext) // Internal property
53```
54 
55**Correct:**
56```javascript
57import { h } from 'vue'
58 
59export default {
60  setup(props, { slots }) {
61    return () => {
62      const slotContent = slots.default?.()
63 
64      // CORRECT: Only use documented properties
65      if (slotContent?.[0]) {
66        const vnode = slotContent[0]
67        console.log(vnode.type)     // Safe: element type or component
68        console.log(vnode.props)    // Safe: props object
69        console.log(vnode.children) // Safe: children
70        console.log(vnode.key)      // Safe: key prop
71      }
72 
73      return h('div', slotContent)
74    }
75  }
76}
77```
78 
79```javascript
80import { h, ref, onMounted } from 'vue'
81 
82export default {
83  setup() {
84    // CORRECT: Use template refs for DOM access
85    const divRef = ref(null)
86 
87    onMounted(() => {
88      // Safe way to access DOM element
89      console.log(divRef.value.tagName)
90    })
91 
92    return () => h('div', { ref: divRef }, 'Content')
93  }
94}
95```
96 
97## Documented VNode Properties
98 
99| Property | Type | Description |
100|----------|------|-------------|
101| `type` | `string \| Component` | Element tag name or component definition |
102| `props` | `object \| null` | Props passed to the vnode |
103| `children` | `any` | Child vnodes, text, or slots |
104| `key` | `string \| number \| null` | Key for list rendering |
105 
106## Safe VNode Inspection Patterns
107 
108```javascript
109import { h, isVNode } from 'vue'
110 
111export default {
112  setup(props, { slots }) {
113    return () => {
114      const children = slots.default?.() || []
115 
116      // Safe: Check if something is a vnode
117      children.forEach(child => {
118        if (isVNode(child)) {
119          // Safe: Check vnode type
120          if (typeof child.type === 'string') {
121            console.log('Element:', child.type)
122          } else if (typeof child.type === 'object') {
123            console.log('Component:', child.type.name)
124          }
125 
126          // Safe: Read props
127          if (child.props?.class) {
128            console.log('Has class:', child.props.class)
129          }
130        }
131      })
132 
133      return h('div', children)
134    }
135  }
136}
137```
138 
139## Why This Matters
140 
141Vue's internal vnode structure may change for:
142- Performance optimizations
143- New feature implementations
144- Bug fixes
145- Tree-shaking improvements
146 
147Code relying on internal properties will break silently or throw errors when upgrading Vue versions. The documented properties are part of Vue's public API and are guaranteed to remain stable.
148 
149## Reference
150- [Vue.js Render Function APIs](https://vuejs.org/api/render-function.html)
151- [Vue.js Render Functions - The Virtual DOM](https://vuejs.org/guide/extras/render-function.html#the-virtual-dom)
152