Render Function API

Overview

This change will not affect <template> users.

Here is a quick summary of what has changed:

  • h is now globally imported instead of passed to render functions as an arguments
  • render function arguments changed to be more consistent between stateful and functional components
  • VNodes now have a flat props structure

For more information, read on!

Render Function Argument

2.x Syntax

In 2.x, the render function would automatically receive the h function (which is a conventional alias for createElement) as an argument:

  1. // Vue 2 Render Function Example
  2. export default {
  3.   render(h) {
  4.     return h('div')
  5.   }
  6. }

3.x Syntax

In 3.x, h is now globally imported instead of being automatically passed as an argument.

  1. // Vue 3 Render Function Example
  2. import { h } from 'vue'
  4. export default {
  5.   render() {
  6.     return h('div')
  7.   }
  8. }

Render Function Signature Change

2.x Syntax

In 2.x, the render function automatically received arguments such as h.

  1. // Vue 2 Render Function Example
  2. export default {
  3.   render(h) {
  4.     return h('div')
  5.   }
  6. }

3.x Syntax

In 3.x, since the render function no longer receives any arguments, it will primarily be used inside of the setup() function. This has the added benefit of gaining access to reactive state and functions declared in scope, as well as the arguments passed to setup().

  1. import { h, reactive } from 'vue'
  3. export default {
  4.   setup(props, { slots, attrs, emit }) {
  5.     const state = reactive({
  6.       count: 0
  7.     })
  9.     function increment() {
  10.       state.count++
  11.     }
  13.     // return the render function
  14.     return () =>
  15.       h(
  16.         'div',
  17.         {
  18.           onClick: increment
  19.         },
  20.         state.count
  21.       )
  22.   }
  23. }

For more information on how setup() works, see our Composition API Guide.

VNode Props Format

2.x Syntax

In 2.x, domProps contained a nested list within the VNode props:

  1. // 2.x
  2. {
  3.   class: ['button', 'is-outlined'],
  4.   style: { color: '#34495E' },
  5.   attrs: { id: 'submit' },
  6.   domProps: { innerHTML: '' },
  7.   on: { click: submitForm },
  8.   key: 'submit-button'
  9. }

3.x Syntax

In 3.x, the entire VNode props structure is flattened. Using the example from above, here is what it would look like now.

  1. // 3.x Syntax
  2. {
  3.   class: ['button', 'is-outlined'],
  4.   style: { color: '#34495E' },
  5.   id: 'submit',
  6.   innerHTML: '',
  7.   onClick: submitForm,
  8.   key: 'submit-button'
  9. }

Migration Strategy

Library Authors

h being globally imported means that any library that contains Vue components will include import { h } from 'vue' somewhere. As a result, this creates a bit of overhead since it requires library authors to properly configure the externalization of Vue in their build setup:

  • Vue should not be bundled into the library
  • For module builds, the import should be left alone and be handled by the end user bundler
  • For UMD / browser builds, it should try the global Vue.h first and fallback to require calls

Next Steps

See Render Function Guide for more detailed documentation!