Working with VNodes in Vue.js 3

Anton Ioffe - January 2nd 2024 - 11 minutes read

As we delve into the intricacies of Vue.js 3, a seasoned developer understands that mastering the art of virtual node manipulation unlocks the full potential of this progressive framework. In this article, we will navigate the depths of VNodes—beyond mere definitions—into the practical wisdom of crafting sophisticated user interfaces. Prepare to elevate your Vue.js expertise as we explore the creation and optimization of VNodes, investigate their vital role in dynamic component systems, tackle advanced performance patterns, and distill the essence of best practices to avoid the subtle yet impactful pitfalls that could impede your application's efficiency and maintainability. Whether you're refining your skills or looking to push the envelope of what's possible, this journey through the versatile world of VNodes in Vue.js 3 is designed to reshape the way you think about and interact with your Vue applications.

VNodes Fundamentals in Vue.js 3

At their core, VNodes, or Virtual Nodes, represent elements and components within Vue.js's virtual DOM (VDOM). A VNode is fundamentally a JavaScript object that encapsulates information on what type of node it represents (such as a 'div' or Vue component), its properties (like id, class, or directly bound data), any children it may have (which are VNodes themselves), and other essential details like keys for maintaining state across re-renders. The virtual DOM is a lightweight clone of the real DOM, enabling Vue.js to perform complex updates efficiently.

The creation of VNodes is typically handled by the h() function, an alias for createVNode, provided by Vue.js. When working with Vue, developers mostly write templates that Vue compiles into VNodes under the hood. However, it's possible to bypass this abstraction and directly write render functions that return VNodes, offering more fine-grained control over the rendered output. The flexibility of render functions comes with the responsibility of managing reactivity and updates manually, which Vue handles automatically when templates are used.

In terms of the rendering process, it kicks off with Vue transforming templates into VNodes. During the initial rendering, Vue constructs a DOM tree from these VNodes in a phase called mounting. Subsequent reactive changes to the component's state trigger the creation of new VNodes that are compared to the previous ones—a process known as diffing or patching. Only the differences (patches) between the virtual trees are applied to the actual DOM, thus optimizing performance by minimizing direct DOM manipulations.

Understanding VNodes is particularly significant when it comes to advanced component construction and optimization. VNodes encapsulate the descriptions of both a Vue instance's template structure and its DOM manipulations. Developers proficient with VNodes can write more predictable and efficient code by aligning closely with Vue's reactivity system. This entails knowing when and how components will re-render and ensuring that such re-renders are as inexpensive as possible, especially for high-throughput or complex applications.

Lastly, comprehending VNodes and their lifecycle is pivotal to harnessing the full power of Vue.js, especially when working outside the realm of straightforward templating. This knowledge is vital for tasks like programmatically generating content, integrating with third-party libraries that manipulate the DOM directly, or constructing high-order components that serve as wrappers or proxies to other elements or components in the Vue application. The ability to mentally map the structure and behavior of VNodes to their rendered DOM counterparts is a mark of an adept Vue.js developer.

Practical VNode Manipulation

Manipulating VNodes in Vue.js 3 can be critical for creating dynamic and complex web applications. For instance, you may need to wrap a set of child elements in a new parent element without altering the original VNodes. To achieve this, clone the original children VNodes and pass them as children to a new VNode representing the wrapper element. Use the h function to create both parent and child VNodes. Note that cloning VNodes must be approached with caution due to potential performance implications; deep cloning can lead to increased memory usage and render time. For example:

const OriginalChild = {
  render() {
    // Returning a simple VNode representing a div
    return h('div', 'I am the original');

const WrappedParent = {
  render() {
    // Cloning VNodes by leveraging the render function
    const originalChildVNode = this.$slots.default()[0];
    // Wrapping the original child within a new parent VNode
    return h('div', { class: 'wrapper' }, [originalChildVNode]);

Another common scenario involves conditionally replacing elements within the render function. To handle this gracefully, create a factory-like pattern within the render function that decides which VNode to return based on certain conditions. This can be as simple as a ternary operation that chooses between two different h function calls. Here is how such a pattern might look:

const ConditionalRenderingComponent = {
  props: ['isSpecial'],
  render() {
    // Deciding between two types of content based on a prop
    return this.isSpecial
      ? h('div', { class: 'special' }, 'Special Content')
      : h('div', 'Regular Content');

Moreover, developers often need to insert additional data into VNodes, such as attributes, props, or event listeners. This can be done by taking advantage of the second parameter of the h function, which expects a properties object. Constructing this object with the necessary modifications before passing it into the h function allows you to customize the resulting VNode without mutating the original VNode, thus preserving reusability and modularity. For example:

const EnhancedComponent = {
  setup() {
    // Creating a VNode with added props and event listeners
    return () => h('div', {
      id: 'enhanced',
      class: 'stylish',
      // Attaching a click event listener
      onClick: () => console.log('Clicked!')
    }, 'Click me');

However, manipulating VNodes comes with potential pitfalls. One must consider the impact on the Vue reactivity system, as improperly cloned or modified VNodes can lead to stale or inconsistent UI states. To avoid such issues, ensure that the newly created VNodes remain reactive by properly binding dynamic data with Vue's reactivity system. This can be demonstrated by the following example, where we maintain reactivity through the use of a computed property:

const ReactiveComponent = {
  props: ['message'],
  computed: {
    // Defining a computed property for reactive content
    reactiveMessage() {
      return `Reactive says: ${this.message}`;
  render() {
    // Using computed property in render function to maintain reactivity
    return h('div', this.reactiveMessage());

Lastly, take into account that Vue.js 3 employs a variety of optimizations under the hood when dealing with VNodes. For example, static VNode trees are lifted out and reused across renders to enhance performance. When manually manipulating VNodes, one must ensure these optimizations are not inadvertently negated. Here's how you might structure static VNode content:

// Defining a static VNode outside the component's reactive scope
const staticVNode = h('div', { class: 'static-content' }, 'This is static.');

const RenderWithStaticOptimization = {
  data() {
    return { dynamicContent: 'I change!' };
  render() {
    // Rendering a combination of static and dynamic content
    return h('div', [
      h('div', this.dynamicContent)

In this example, the static VNode remains outside any reactive code paths, ensuring that it is not unnecessarily regenerated on each render call. This highlights the importance of structuring code to leverage Vue's performance optimizations while customizing VNode behavior.

Component Dynamics and VNodes

Managing component dynamics efficiently often requires a deeper understanding of the interplay between VNodes and Vue’s component system. For stateful components, each instance maintains its own state and VNode tree. As the state changes, Vue intelligently updates the component's VNode tree and patches the real DOM accordingly. Developers can capitalize on this behavior to build highly dynamic, stateful components, but they should be cognizant of the resultant complexity. Typing these components in TypeScript adds an extra layer of robustness, ensuring the VNodes produced align with expectations. Here is a TypeScript code sample for typing a functional component that returns a VNode:

import { FunctionalComponent, h } from 'vue';

interface Props {
  message: string;

const DynamicMessage: FunctionalComponent<Props> = (props, { slots }) => {
  return h('div', [
    h('p', props.message),
    slots.default && slots.default()

DynamicMessage.props = ['message'];

Functional components in Vue, which are stateless and instance-less, prioritize performance and simplicity in their design. Leveraging VNodes in functional components can extend their capabilities without introducing the overhead of a stateful component. Moreover, since they are merely functions that return VNodes, incorporating TypeScript becomes a straightforward process, as demonstrated in the previous example.

The modularity trade-off becomes evident when you start working directly with VNodes for composing your components. While render functions provide closer control over the VNodes, they stray from the declarative nature of Vue's template syntax. This might lead to reduced readability for some developers, particularly those who are more comfortable with the HTML-like structure of templates. Nevertheless, in complex scenarios where fine-grained control is necessary, such explicit VNode manipulation may become indispensable:

const myDynamicComponent = {
  data() {
    return {
      isActive: true
  render() {
    const buttonVNode = this.isActive
      ? h('button', { class: 'active' }, 'Active')
      : h('button', { class: 'inactive' }, 'Inactive');

    return h('div', [buttonVNode]);

In considering reusability, direct use of VNodes can be both a boon and a bane. While they allow for the creation of high-order components that accept and operate on a variety of child VNodes, the approach can also introduce challenges in maintaining clear and self-explanatory components. It is vital for developers to balance the abstraction VNodes offer with the need for components to remain as self-documenting as possible.

Moreover, developers should be vigilant when dealing with slots and VNodes. Modifying VNodes passed to slots in child components might be ineffective due to Vue's diffing algorithm, especially when normal slots, created in the parent’s scope, are involved. This limitation prompts a question: how should one structure a component that needs to modify VNodes received from slots while ensuring reactive updates? The answer lies in using scoped slots whenever possible, as scoped slots provide a fresh set of VNodes from the parent's render function, granting more predictable reactivity and control:

const SlotWrapperComponent = {
  props: ['wrapperClass'],
  render() {
    return h('div', { class: this.wrapperClass }, this.$slots.default());

In essence, VNodes are an incredibly powerful tool in Vue.js 3, offering developers the ability to orchestrate dynamic components with precision. Finding the right balance between direct VNode manipulation and Vue's declarative template system is a nuanced decision that revolves around the specific needs of your application, performance considerations, and team preferences. How might one approach building a library of reusable components that harness VNodes for extensibility while remaining developer-friendly and adherent to Vue's reactive principles?

Advanced Patterns and Performance Optimization

When aiming to boost your Vue.js application's performance, understanding and leveraging advanced patterns like Static Hoisting is crucial. This technique involves identifying parts of the DOM that are invariant—those which do not change across renders—and hoisting them out of the render function. In practice, this looks like extracting these static elements into constants, such that Vue does not have to recreate them on each update; instead, they are instantiated once and cloned efficiently when needed. This approach reduces the workload on the patching process, as the virtual DOM can skip these nodes entirely, leading to faster updates and less memory consumption.

const staticNode = Vue.h('p', 'This is static')
function render(dynamicContent){
    return Vue.h('div', [
        dynamicContent ? Vue.h('span', 'Dynamic Content') : ''

Patch Flags offer another significant optimization for performance-tuning your Vue.js application. By providing signals to the Vue compiler about which types of changes can occur to a given element, these flags limit the scope of the diffing process during updates. For instance, flags can denote if an element's children, text content, or attribute bindings are dynamic. This granular control means Vue will only check relevant properties when patching the DOM, reducing the amount of unnecessary comparisons and speeding up the rendering process.

import { h } from 'vue';
function render(){
    return h('div', { 'class': 'container' }, [
        h('p', this.dynamicText),
        this.condition ? h('span', 'Conditionally rendered') : null

In cases with numerous nodes at the same nesting level, Tree Flattening can be a powerful pattern. By taking nested arrays of VNodes and flattening them into a single array, Vue can reduce the depth of traversal required to patch the tree. This can have a marked impact on performance, especially for large applications with deeply nested components. It's vital, however, to ensure that keys are managed correctly to prevent the re-rendering of sibling nodes unnecessarily.

function render(){
    return Vue.h('ul', [ => Vue.h('li', item))])

While these techniques are potent, they should be used with discernment. Static Hoisting shines in scenarios where large chunks of static HTML are present, whereas Patch Flags become effective in dynamic, fine-grained updates. Unnecessary optimization can lead to premature complexity and must be weighed against the specific performance pain points of your application. Similarly, Tree Flattening should be informed by the component's structural complexity. A developer should ask: Is my render function performance truly bounded by virtual DOM patching? If not, other optimizations may take precedence.

Lastly, be wary of the allure of over-optimization. Techniques like Static Hoisting and Patch Flags can provide tangible gains, but these should be applied strategically and only after identifying bottlenecks through profiling. A thoughtful approach, applying the right optimization at the right place, pays dividends in both performance and maintainability. How can you balance the need for lightning-fast rendering with the demands of a clean and maintainable codebase?

Common Pitfalls and Best Practices with VNodes

One common pitfall when working with VNodes in Vue.js 3 is the misuse of keys. Providing a unique key for each VNode in a list is imperative, as it allows Vue to track individual nodes and thus perform efficient updates. However, developers sometimes make the mistake of using non-unique or unstable keys, such as indexes, that can lead to unnecessary re-renders and performance issues.

// Common mistake - using index as key, which can lead to performance issues
  <div v-for="(item, index) in items" :key="index">
    {{ }}

To correct this, use a unique property of each item, such as an id, that is stable across re-renders.

// Correct approach - using a unique property as key
  <div v-for="item in items" :key="">
    {{ }}

Another issue arises when developers directly mutate a VNode's reactive properties. Directly mutating VNode properties breaks Vue’s reactivity principles since VNodes should be immutable.

// Incorrect: Directly mutating a VNode's reactive properties
const vnode = h('div', { class: 'foo' });
// The direct mutation is discouraged
vnode.props.class = 'bar';

A more appropriate approach involves creating a new VNode with the updated properties using Vue's h function.

// Correct: Creating a new VNode with updated properties
const updatedVNode = h('div', { class: 'bar' });

Some developers mistakenly clone VNodes, which often results in duplicated memory usage and state. Cloning should be avoided unless absolutely necessary, with props or children being the preferred method for updating or transforming VNodes.

// Problematic: Unnecessary cloning of VNodes
const clonedVNode = vnode; // This should be avoided

When needed, a more performant approach is to use functional components or factory functions to create new VNodes.

// Better: Using factory functions for creating fresh VNodes
const createVNodeWithProps = props => h('div', props);

In conclusion, to maintain high-quality, performant Vue.js 3 codebases, keep in mind the following practices:

  • Always use stable and unique properties like an id for VNode keys to facilitate proper tracking and efficient updates.
  • Treat VNodes as immutable, avoiding direct mutations. Utilize Vue's h function or custom factory functions for generating new VNodes with the necessary updates.
  • Use Vue's reactivity system, such as computed properties and watchers, rather than manual reactive property mutations on VNodes.
  • Refrain from cloning VNodes unnecessarily to optimize performance and maintain clarity in your application’s data flow.
  • When working with slots, use scoped slots to maintain reactivity and avoid issues with parent-child update cycles.

By observing these guidelines, developers can prevent typical pitfalls and ensure the conservation of Vue's reactivity paradigm, leading to the development of high-performing and responsive web applications.


In this article about working with VNodes in Vue.js 3, the author explores the fundamentals of VNodes, practical manipulation techniques, component dynamics, advanced patterns for performance optimization, and common pitfalls to avoid. The article emphasizes the importance of understanding VNodes for creating sophisticated user interfaces and optimizing application efficiency. The challenging technical task for readers is to implement Static Hoisting and Patch Flags optimizations in their own Vue.js applications to improve rendering performance. By considering these techniques and best practices, developers can create high-performing and maintainable Vue.js applications.

Don't Get Left Behind:
The Top 5 Career-Ending Mistakes Software Developers Make
FREE Cheat Sheet for Software Developers