stack/packages/mosaic/framework/skills/vue-best-practices/reference/render-function-vnodes-must-be-unique.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
VNodes Must Be Unique in Render Functions	HIGH	Reusing vnode references causes rendering bugs and unexpected behavior	gotcha	vue3 render-function vnode composition-api

VNodes Must Be Unique in Render Functions

Impact: HIGH - Reusing the same vnode reference multiple times in a render function tree causes rendering bugs, where only one instance appears or updates behave unexpectedly.

Every vnode in a component's render tree must be unique. You cannot use the same vnode object multiple times. If you need to render the same element multiple times, create each vnode separately using a factory function or by calling h() in a loop.

Task Checklist

• Never store a vnode in a variable and use it multiple times in the same tree
• Use a factory function or .map() to create multiple similar vnodes
• Each h() call creates a new vnode, so call it for each instance needed
• Be especially careful when extracting vnode creation into helper functions

Incorrect:

import { h } from 'vue';

export default {
  setup() {
    return () => {
      // WRONG: Same vnode reference used twice
      const p = h('p', 'Hello');
      return h('div', [p, p]); // Bug! Duplicate vnode reference
    };
  },
};

import { h } from 'vue';

export default {
  setup() {
    return () => {
      // WRONG: Reusing vnode in different parts of tree
      const icon = h('span', { class: 'icon' }, '★');
      return h('div', [
        h('button', [icon, ' Save']), // Uses icon
        h('button', [icon, ' Delete']), // Reuses same icon - Bug!
      ]);
    };
  },
};

Correct:

import { h } from 'vue';

export default {
  setup() {
    return () => {
      // CORRECT: Create new vnode for each use
      return h('div', [h('p', 'Hello'), h('p', 'Hello')]);
    };
  },
};

import { h } from 'vue';

export default {
  setup() {
    return () => {
      // CORRECT: Factory function creates new vnode each time
      const createIcon = () => h('span', { class: 'icon' }, '★');
      return h('div', [
        h('button', [createIcon(), ' Save']),
        h('button', [createIcon(), ' Delete']),
      ]);
    };
  },
};

import { h } from 'vue';

export default {
  setup() {
    return () => {
      // CORRECT: Using map to create multiple vnodes
      return h(
        'div',
        Array.from({ length: 20 }).map(() => h('p', 'Hello')),
      );
    };
  },
};

import { h } from 'vue';

export default {
  setup() {
    const items = ['Apple', 'Banana', 'Cherry'];

    return () =>
      h(
        'ul',
        // CORRECT: Each iteration creates a new vnode
        items.map((item, index) => h('li', { key: index }, item)),
      );
  },
};

Why VNodes Must Be Unique

VNodes are lightweight JavaScript objects that Vue's virtual DOM algorithm uses for diffing and patching. When the same vnode reference appears multiple times:

• Vue cannot differentiate between the instances
• The diffing algorithm produces incorrect results
• Only one instance may render, or updates may corrupt the DOM

Each vnode maintains its own identity and position in the tree, which is essential for:

• Correct DOM patching during updates
• Proper lifecycle hook execution
• Accurate key-based reconciliation in lists

Reference

• Vue.js Render Functions - Vnodes Must Be Unique