Render Functions

Let’s dive into an example where a function would be practical. Say we want to generate anchored headings:

Anchored headings are used very frequently, we should create a component:

<anchored-heading :level="1">Hello world!</anchored-heading>

The component must generate a heading based on the level prop, and we quickly arrive at this:

const app = Vue.createApp({})
app.component('anchored-heading', {
  template: `
    <h1 v-if="level === 1">
      <slot></slot>
    </h1>
    <h2 v-else-if="level === 2">
      <slot></slot>
    </h2>
    <h3 v-else-if="level === 3">
      <slot></slot>
    </h3>
    <h4 v-else-if="level === 4">
      <slot></slot>
    </h4>
    <h5 v-else-if="level === 5">
      <slot></slot>
    </h5>
    <h6 v-else-if="level === 6">
      <slot></slot>
    </h6>
  `,
  props: {
    level: {
      type: Number,
      required: true
    }
  }
})

This template doesn’t feel great. It’s not only verbose, but we’re duplicating <slot></slot> for every heading level. And when we add the anchor element, we have to again duplicate it in every v-if/v-else-if branch.

While templates work great for most components, it’s clear that this isn’t one of them. So let’s try rewriting it with a render() function:

const app = Vue.createApp({})
app.component('anchored-heading', {
  render() {
    const { h } = Vue
    return h(
      'h' + this.level, // tag name
      {}, // props/attributes
      this.$slots.default() // array of children
    )
  },
  props: {
    level: {
      type: Number,
      required: true
    }
  }
})

The render() function implementation is much simpler, but also requires greater familiarity with Vue instance properties. In this case, you have to know that when you pass children without a v-slot directive into a component, like the Hello world! inside of anchored-heading, those children are stored on the component instance at $slots.default(). If you haven’t already, it’s recommended to read through the instance properties API before diving into render functions.

Before we dive into render functions, it’s important to know a little about how browsers work. Take this HTML for example:

<div>
  <h1>My title</h1>
  Some text content
</div>

When a browser reads this code, it builds a to help it keep track of everything.

The tree of DOM nodes for the HTML above looks like this:

Every element is a node. Every piece of text is a node. Even comments are nodes! Each node can have children (i.e. each node can contain other nodes).

<h1>{{ blogTitle }}</h1>

Or in a render function:

render() {
}

And in both cases, Vue automatically keeps the page updated, even when blogTitle changes.

The Virtual DOM tree

Vue keeps the page updated by building a virtual DOM to keep track of the changes it needs to make to the real DOM. Taking a closer look at this line:

return Vue.h('h1', {}, this.blogTitle)

What is the h() function returning? It’s not exactly a real DOM element. It returns a plain object which contains information describing to Vue what kind of node it should render on the page, including descriptions of any child nodes. We call this node description a “virtual node”, usually abbreviated to VNode. “Virtual DOM” is what we call the entire tree of VNodes, built by a tree of Vue components.

The h() function is a utility to create VNodes. It could perhaps more accurately be named createVNode(), but it’s called h() due to frequent use and for brevity. It accepts three arguments:

Complete Example

With this knowledge, we can now finish the component we started:

const app = Vue.createApp({})
/** Recursively get text from children nodes */
function getChildrenTextContent(children) {
  return children
    .map(node => {
      return typeof node.children === 'string'
        ? node.children
        : Array.isArray(node.children)
        : ''
    })
    .join('')
}
app.component('anchored-heading', {
  render() {
    // create kebab-case id from the text contents of the children
    const headingId = getChildrenTextContent(this.$slots.default())
      .toLowerCase()
      .replace(/\W+/g, '-') // replace non-word characters with dash
      .replace(/(^-|-$)/g, '') // remove leading and trailing dashes
    return Vue.h('h' + this.level, [
      Vue.h(
        'a',
        {
          name: headingId,
          href: '#' + headingId
        },
        this.$slots.default()
      )
    ])
  },
  props: {
    level: {
      type: Number,
      required: true
    }
  }
})

All VNodes in the component tree must be unique. That means the following render function is invalid:

render() {
  const myParagraphVNode = Vue.h('p', 'hi')
  return Vue.h('div', [
    // Yikes - duplicate VNodes!
    myParagraphVNode, myParagraphVNode
  ])
}

If you really want to duplicate the same element/component many times, you can do so with a factory function. For example, the following render function is a perfectly valid way of rendering 20 identical paragraphs:

render() {
  return Vue.h('div',
    Array.apply(null, { length: 20 }).map(() => {
      return Vue.h('p', 'hi')
    })
  )
}

Replacing Template Features with Plain JavaScript

Wherever something can be easily accomplished in plain JavaScript, Vue render functions do not provide a proprietary alternative. For example, in a template using v-if and v-for:

<ul v-if="items.length">
  <li v-for="item in items">{{ item.name }}</li>
</ul>
<p v-else>No items found.</p>

This could be rewritten with JavaScript’s if/else and map() in a render function:

props: ['items'],
render() {
  if (this.items.length) {
    return Vue.h('ul', this.items.map((item) => {
      return Vue.h('li', item.name)
    }))
  } else {
    return Vue.h('p', 'No items found.')
  }

The v-model directive is expanded to modelValue and onUpdate:modelValue props during template compilation—we will have to provide these props ourselves:

props: ['modelValue'],
render() {
  return Vue.h('input', {
    modelValue: this.modelValue,
    'onUpdate:modelValue': value => this.$emit('onUpdate:modelValue', value)
  })
}

render() {
  return Vue.h('div', {
    onClick: $event => console.log('clicked', $event.target)
  })
}

Event Modifiers

For the .passive, , and .once event modifiers, Vue offers object syntax of the handler:

For example:

For all other event and key modifiers, no special API is necessary, because we can use event methods in the handler:

Here’s an example with all of these modifiers used together:

render() {
  return Vue.h('input', {
    onKeyUp: event => {
      // Abort if the element emitting the event is not
      // the element the event is bound to
      if (event.target !== event.currentTarget) return
      // Abort if the key that went up is not the enter
      // key (13) and the shift key was not held down
      // at the same time
      if (!event.shiftKey || event.keyCode !== 13) return
      // Stop event propagation
      event.stopPropagation()
      // Prevent the default keyup handler for this element
      event.preventDefault()
      // ...
    }
  })
}

You can access slot contents as Arrays of VNodes from this.$slots:

render() {
  // `<div><slot></slot></div>`
  return Vue.h('div', {}, this.$slots.default())
}

props: ['message'],
render() {
  // `<div><slot :text="message"></slot></div>`
  return Vue.h('div', {}, this.$slots.default({
    text: this.message
  }))
}

To pass slots to a child component using render functions:

render() {
  // `<div><child v-slot="props"><span>{{ props.text }}</span></child></div>`
  return Vue.('div', [
    Vue.('child', {}, {
      // pass `slots` as the children object
      // in the form of { name: props => VNode | Array<VNode> }
      default: (props) => Vue.h('span', props.text)
    })
  ])
}

If we’re writing a lot of render functions, it might feel painful to write something like this:

Vue.h(
  'anchored-heading',
  {
    level: 1
  },
  [Vue.h('span', 'Hello'), ' world!']
)

Especially when the template version is so concise in comparison:

<anchored-heading :level="1"> <span>Hello</span> world! </anchored-heading>

That’s why there’s a to use JSX with Vue, getting us back to a syntax that’s closer to templates:

import AnchoredHeading from './AnchoredHeading.vue'
new Vue({
  el: '#demo',
  render() {
    return (
      <AnchoredHeading level={1}>
        <span>Hello</span> world!
      </AnchoredHeading>
    )
  }

For more on how JSX maps to JavaScript, see the usage docs.

Template Compilation

You may be interested to know that Vue’s templates actually compile to render functions. This is an implementation detail you usually don’t need to know about, but if you’d like to see how specific template features are compiled, you may find it interesting. Below is a little demo using Vue.compile to live-compile a template string: