Migration from Vue 1.x

Woah - this is a super long page! Does that mean 2.0 is completely different, I’ll have to learn the basics all over again, and migrating will be practically impossible?

I’m glad you asked! The answer is no. About 90% of the API is the same and the core concepts haven’t changed. It’s long because we like to offer very detailed explanations and include a lot of examples. Rest assured, this is not something you have to read from top to bottom!

Where should I start in a migration?

<p>foo</p>
<p>bar</p>

<div>
  <p>foo</p>
  <p>bar</p>
</div>

attached: function () {
  doSomething()
}

mounted: function () {
  this.$nextTick(function () {
    doSomething()
  })
}

detached: function () {
  doSomething()
}

destroyed: function () {
  this.$nextTick(function () {
    doSomething()
  })
}

mounted: function () {
  this.$nextTick(function () {
    // code that assumes this.$el is in-document
  })
}

<div v-for="item in items" track-by="id">

<div v-for="item in items" v-bind:key="item.id">

props: {
  username: {
    type: String,
    coerce: function (value) {
      return value
        .toLowerCase()
        .replace(/\s+/, '-')
    }
  }
}

props: {
  username: String,
},
computed: {
  normalizedUsername: function () {
    return this.username
      .toLowerCase()
      .replace(/\s+/, '-')
  }
}

Run the migration helper on your codebase to find examples of the coerce option.

twoWay Prop Option ^removed

Props are now always one-way down. To produce side effects in the parent scope, a component needs to explicitly emit an event instead of relying on implicit binding. For more information, see:

Upgrade Path

Run the migration helper on your codebase to find examples of the twoWay option.

.once and .sync Modifiers on v-bind ^removed

Props are now always one-way down. To produce side effects in the parent scope, a component needs to explicitly emit an event instead of relying on implicit binding. For more information, see:

Upgrade Path

Run the migration helper on your codebase to find examples of the .once and .sync modifiers.

Prop Mutation ^deprecated

Mutating a prop locally is now considered an anti-pattern, e.g. declaring a prop and then setting this.myProp = 'someOtherValue' in the component. Due to the new rendering mechanism, whenever the parent component re-renders, the child component’s local changes will be overwritten.

Props on a Root Instance ^replaced

On root Vue instances (i.e. instances created with new Vue({ ... }) ), you must use propsData instead of props .

Computed properties

cache: false ^deprecated

Caching invalidation of computed properties will be removed in future major versions of Vue. Replace any uncached computed properties with methods, which will have the same result.

template: '<p>message: {{ timeMessage }}</p>',
computed: {
  timeMessage: {
    cache: false,
    get: function () {
      return Date.now() + this.message
    }
  }
}

template: '<p>message: {{ getTimeMessage() }}</p>',
methods: {
  getTimeMessage: function () {
    return Date.now() + this.message
  }
}

Run the migration helper on your codebase to find examples of the cache: false option.

Built-In Directives

Truthiness/Falsiness with v-bind ^changed

When used with v-bind , the only falsy values are now: null , undefined , and false . This means 0 and empty strings will render as truthy. So for example, v-bind:draggable="''" will render as draggable="true" .

Listening for Native Events on Components with v-on ^changed

When used on a component, v-on now only listens to custom events $emit ted by that component. To listen for a native DOM event on the root element, you can use the .native modifier. For example:

<my-component v-on:click.native="doSomething"></my-component>

debounce Param Attribute for v-model ^removed

Debouncing is used to limit how often we execute Ajax requests and other expensive operations. Vue’s debounce attribute parameter for v-model made this easy for very simple cases, but it actually debounced state updates rather than the expensive operations themselves. It’s a subtle difference, but it comes with limitations as an application grows.

<!--
By using the debounce function from lodash or another dedicated
utility library, we know the specific debounce implementation we
use will be best-in-class - and we can use it ANYWHERE. Not only
in our template.
-->
<script src="https://cdn.jsdelivr.net/lodash/4.13.1/lodash.js"></script>
<div id="debounce-search-demo">
  <input v-model="searchQuery" placeholder="Type something">
  <strong>{{ searchIndicator }}</strong>
</div>

new Vue({
  el: '#debounce-search-demo',
  data: {
    searchQuery: '',
    searchQueryIsDirty: false,
    isCalculating: false
  },
  computed: {
    searchIndicator: function () {
      if (this.isCalculating) {
        return '⟳ Fetching new results'
      } else if (this.searchQueryIsDirty) {
        return '... Typing'
      } else {
        return '✓ Done'
      }
    }
  },
  watch: {
    searchQuery: function () {
      this.searchQueryIsDirty = true
      this.expensiveOperation()
    }
  },
  methods: {
    // This is where the debounce actually belongs.
    expensiveOperation: _.debounce(function () {
      this.isCalculating = true
      setTimeout(function () {
        this.isCalculating = false
        this.searchQueryIsDirty = false
      }.bind(this), 1000)
    }, 500)
  }
})

Run the migration helper on your codebase to find examples of the debounce attribute.

lazy or number Param Attributes for v-model ^replaced

The lazy and number param attributes are now modifiers, to make it more clear what That means instead of:

<input v-model="name" lazy>
<input v-model="age" type="number" number>

<input v-model.lazy="name">
<input v-model.number="age" type="number">

Run the migration helper on your codebase to find examples of the these param attributes.

value Attribute with v-model ^removed

v-model no longer cares about the initial value of an inline value attribute. For predictability, it will instead always treat the Vue instance data as the source of truth.

<input v-model="text" value="foo">

data: {
  text: 'bar'
}

<textarea v-model="text">
  hello world
</textarea>

v-model with v-for Iterated Primitive Values ^removed

Cases like this no longer work:

<input v-for="str in strings" v-model="str">

strings.map(function (str) {
  return createElement('input', ...)
})

<input v-for="obj in objects" v-model="obj.str">

v-bind:style with Object Syntax and !important ^removed

This will no longer work:

<p v-bind:style="{ color: myColor + ' !important' }">hello</p>

<p v-bind:style="'color: ' + myColor + ' !important'">hello</p>

Run the migration helper on your codebase to find examples of style bindings with !important in objects.

v-el and v-ref ^replaced

For simplicity, v-el and v-ref have been merged into the ref attribute, accessible on a component instance via $refs . That means v-el:my-element would become ref="myElement" and v-ref:my-component would become ref="myComponent" . When used on a normal element, the ref will be the DOM element, and when used on a component, the ref will be the component instance.

<p v-for="item in items" v-bind:ref="'item' + item.id"




    
></p>

<p v-for="item in items" ref="items"></p>

Run the migration helper on your codebase to find examples of v-el and v-ref .

v-else with v-show ^removed

v-else no longer works with v-show . Use v-if with a negation expression instead. For example, instead of:

<p v-if="foo">Foo</p>
<p v-else v-show="bar">Not foo, but bar</p>

<p v-if="foo">Foo</p>
<p v-if="!foo && bar">Not foo, but bar</p>

Run the migration helper on your codebase to find examples of the v-else with v-show .

Custom Directives ^simplified

Directives have a greatly reduced scope of responsibility: they are now only used for applying low-level direct DOM manipulations. In most cases, you should prefer using components as the main code-reuse abstraction.

Fortunately, since the new directives are much simpler, you can master them more easily. Read the new Custom Directives guide to learn more.

Upgrade Path

Run the migration helper on your codebase to find examples of defined directives. The helper will flag all of them, as it's likely in most cases that you'll want to refactor to a component.

Directive .literal Modifier ^removed

The .literal modifier has been removed, as the same can be easily achieved by providing a string literal as the value.

<p v-my-directive.literal="foo bar baz"></p>

<p v-my-directive="'foo bar baz'"></p>

Run the migration helper on your codebase to find examples of the `.literal` modifier on a directive.

Transitions

transition Attribute ^replaced

Vue’s transition system has changed quite drastically and now uses <transition> and <transition-group> wrapper elements, rather than the transition attribute. It’s recommended to read the new Transitions guide to learn more.

Upgrade Path

Run the migration helper on your codebase to find examples of the transition attribute.

Vue.transition for Reusable Transitions ^replaced

With the new transition system, you can now use components for reusable transitions .

Upgrade Path

Run the migration helper on your codebase to find examples of Vue.transition .

Transition stagger Attribute ^removed

If you need to stagger list transitions, you can control timing by setting and accessing a data-index (or similar attribute) on an element. See an example here .

Upgrade Path

Run the migration helper on your codebase to find examples of the transition attribute. During your update, you can transition (pun very much intended) to the new staggering strategy as well.

Events

events option ^removed

The events option has been removed. Event handlers should now be registered in the created hook instead. Check out the $dispatch and $broadcast migration guide for a detailed example.

Vue.directive('on').keyCodes ^replaced

The new, more concise way to configure keyCodes is through Vue.config.keyCodes . For example:

// enable v-on:keyup.f1
Vue.config.keyCodes.f1 = 112

Run the migration helper on your codebase to find examples of the the old keyCode configuration syntax.

$dispatch and $broadcast ^replaced

$dispatch and $broadcast have been removed in favor of more explicitly cross-component communication and more maintainable state management solutions, such as Vuex .

The problem is event flows that depend on a component’s tree structure can be hard to reason about and are very brittle when the tree becomes large. They don’t scale well and only set you up for pain later. $dispatch and $broadcast also do not solve communication between sibling components.

One of the most common uses for these methods is to communicate between a parent and its direct children. In these cases, you can actually listen to an $emit from a child with v-on . This allows you to keep the convenience of events with added explicitness.

However, when communicating between distant descendants/ancestors, $emit won’t help you. Instead, the simplest possible upgrade would be to use a centralized event hub. This has the added benefit of allowing you to communicate between components no matter where they are in the component tree - even between siblings! Because Vue instances implement an event emitter interface, you can actually use an empty Vue instance for this purpose.

For example, let’s say we have a todo app structured like this:

Todos
├─ NewTodoInput
└─ Todo
   └─ DeleteTodoButton

We could manage communication between components with this single event hub:

// This is the event hub we'll use in every
// component to communicate between them.
var eventHub = new Vue()

Then in our components, we can use $emit , $on , $off to emit events, listen for events, and clean up event listeners, respectively:

// NewTodoInput
// ...
methods: {
  addTodo: function () {
    eventHub.$emit('add-todo', { text: this.newTodoText })
    this.newTodoText = ''
  }
}

// DeleteTodoButton
// ...
methods: {
  deleteTodo: function (id) {
    eventHub.$emit('delete-todo', id)
  }
}

// Todos




    

// ...
created: function () {
  eventHub.$on('add-todo', this.addTodo)
  eventHub.$on('delete-todo', this.deleteTodo)
},
// It's good to clean up event listeners before
// a component is destroyed.
beforeDestroy: function () {
  eventHub.$off('add-todo', this.addTodo)
  eventHub.$off('delete-todo', this.deleteTodo)
},
methods: {
  addTodo: function (newTodo) {
    this.todos.push(newTodo)
  },
  deleteTodo: function (todoId) {
    this.todos = this.todos.filter(function (todo) {
      return todo.id !== todoId
    })
  }
}

This pattern can serve as a replacement for $dispatch and $broadcast in simple scenarios, but for more complex cases, it’s recommended to use a dedicated state management layer such as Vuex .

Upgrade Path

Run the migration helper on your codebase to find examples of $dispatch and $broadcast .

Filters

Filters Outside Text Interpolations ^removed

Filters can now only be used inside text interpolations ( {{ }} tags). In the past we’ve found using filters within directives such as v-model , v-on , etc led to more complexity than convenience. For list filtering on v-for , it’s also better to move that logic into JavaScript as computed properties, so that it can be reused throughout your component.

Replacing the debounce Filter

Instead of:

<input v-on:keyup="doStuff | debounce 500">

methods: {
  doStuff: function () {
    // ...
  }
}

Use lodash’s debounce (or possibly throttle ) to directly limit calling the expensive method. You can achieve the same as above like this:

<input v-on:keyup="doStuff">

methods: {
  doStuff: _.debounce(function () {
    // ...
  }, 500)
}

For more on the advantages of this strategy, see the example here with v-model .

Replacing the limitBy Filter

Instead of:

<p v-for="item in items | limitBy 10">{{ item }}</p>

Use JavaScript’s built-in .slice method in a computed property:

<p v-for="item in filteredItems">{{ item }}</p>

computed: {
  filteredItems: function () {
    return this.items.slice(0, 10)
  }
}

Replacing the filterBy Filter

Instead of:

<p v-for="user in users | filterBy searchQuery in 'name'">{{ user.name }}</p>

Use JavaScript’s built-in .filter method in a computed property:

<p v-for="user in filteredUsers">{{ user.name }}</p>

computed: {
  filteredUsers: function () {
    var self = this
    return self.users.filter(function (user) {
      return user.name.indexOf(self.searchQuery) !== -1
    })
  }
}

JavaScript’s native .filter can also manage much more complex filtering operations, because you have access to the full power of JavaScript within computed properties. For example, if you wanted to find all active users and case-insensitively match against both their name and email:

var self = this
self.users.filter(function (user) {
  var searchRegex = new RegExp(self.searchQuery, 'i')
  return user.isActive && (
    searchRegex.test(user.name) ||
    searchRegex.test(user.email)
  )
})

Replacing the orderBy Filter

Instead of:

<p v-for="user in users | orderBy 'name'">{{ user.name }}</p>

Use lodash’s orderBy (or possibly sortBy ) in a computed property:

<p v-for="user in orderedUsers">{{ user.name }}</p>

computed: {
  orderedUsers: function () {
    return _.orderBy(this.users, 'name')
  }
}

You can even order by multiple columns:

_.orderBy(this.users, ['name', 'last_login'], ['asc', 'desc'])

Upgrade Path

Run the migration helper on your codebase to find examples of filters being used inside directives. If you miss any, you should also see console errors .

Filter Argument Syntax ^changed

Filters’ syntax for arguments now better aligns with JavaScript function invocation. So instead of taking space-delimited arguments:

<p>{{ date | formatDate 'YY-MM-DD' timeZone }}</p>

<p>{{ date | formatDate('YY-MM-DD', timeZone) }}</p>

Run the migration helper on your codebase to find examples of the old filter syntax. If you miss any, you should also see console errors .

Built-In Text Filters ^removed

Although filters within text interpolations are still allowed, all of the filters have been removed. Instead, it’s recommended to use more specialized libraries for solving problems in each domain (e.g. date-fns to format dates and accounting for currencies).

For each of Vue’s built-in text filters, we go through how you can replace them below. The example code could exist in custom helper functions, methods, or computed properties.

Replacing the json Filter

You actually don’t need to for debugging anymore, as Vue will nicely format output for you automatically, whether it’s a string, number, array, or plain object. If you want the exact same functionality as JavaScript’s JSON.stringify though, then you can use that in a method or computed property.

Replacing the capitalize Filter

text[0].toUpperCase() + text.slice(1)

Replacing the uppercase Filter

text.toUpperCase()

Replacing the lowercase Filter

text.toLowerCase()

Replacing the pluralize Filter

The pluralize package on NPM serves this purpose nicely, but if you only want to pluralize a specific word or want to have special output for cases like 0 , then you can also easily define your own pluralize functions. For example:

function pluralizeKnife (count) {
  if (count === 0) {
    return 'no knives'
  } else if (count === 1) {
    return '1 knife'
  } else {
    return count + 'knives'
  }
}

Replacing the currency Filter

For a very naive implementation, you could do something like this:

'$' + price.toFixed(2)

In many cases though, you’ll still run into strange behavior (e.g. 0.035.toFixed(2) rounds up to 0.04 , but 0.045 rounds down to 0.04 ). To work around these issues, you can use the accounting library to more reliably format currencies.

Upgrade Path

Run the migration helper on your codebase to find examples of the obsolete text filters. If you miss any, you should also see console errors .

Two-Way Filters ^replaced

Some users have enjoyed using two-way filters with v-model to create interesting inputs with very little code. While seemingly simple however, two-way filters can also hide a great deal of complexity - and even encourage poor UX by delaying state updates. Instead, components wrapping an input are recommended as a more explicit and feature-rich way of creating custom inputs.

This allows us add behavior that a filter alone couldn’t encapsulate, such as selecting the content of an input on focus. Now the next step will be to extract the business logic from the filter. Below, we pull everything out into an external currencyValidator object :

This increased modularity not only makes it easier to migrate to Vue 2, but also allows currency parsing and formatting to be:

Having this validator extracted out, we’ve also more comfortably built it up into a more robust solution. The state quirks have been eliminated and it’s actually impossible for users to enter anything wrong, similar to what the browser’s native number input tries to do.

We’re still limited however, by filters and by Vue 1.0 in general, so let’s complete the upgrade to Vue 2.0:

You may notice that:

Upgrade Path

Run the migration helper on your codebase to find examples of filters used in directives like v-model . If you miss any, you should also see console errors .

Slots

Duplicate Slots ^removed

It is no longer supported to have <slot> s with the same name in the same template. When a slot is rendered it is “used up” and cannot be rendered elsewhere in the same render tree. If you must render the same content in multiple places, pass that content as a prop.

slot Attribute Styling ^removed

Content inserted via named <slot> no longer preserves the slot attribute. Use a wrapper element to style them, or for advanced use cases, modify the inserted content programmatically using render functions .

Upgrade Path

Run the migration helper on your codebase to find CSS selectors targeting named slots (e.g. [slot="my-slot-name"] ).

Special Attributes

keep-alive Attribute ^replaced

keep-alive is no longer a special attribute, but rather a wrapper component, similar to <transition> . For example:

<keep-alive>
  <component v-bind:is="view"></component>
</keep-alive>

<keep-alive>
  <todo-list v-if="todos.length > 0"></todo-list>
  <no-todos-gif v-else></no-todos-gif>
</keep-alive>

<transition>
  <keep-alive>
    <component v-bind:is="view"></component>
  </keep-alive>
</transition>

Run the migration helper on your codebase to find keep-alive attributes.

Interpolation

Interpolation within Attributes ^removed

Interpolation within attributes is no longer valid. For example:

<button




    
 class="btn btn-{{ size }}"></button>

<button v-bind:class="'btn btn-' + size"></button>

<button v-bind:class="buttonClasses"></button>

computed: {
  buttonClasses: function () {
    return 'btn btn-' + size
  }
}

Run the migration helper on your codebase to find examples of interpolation used within attributes.

HTML Interpolation ^removed

HTML interpolations ( {{{ foo }}} ) have been removed in favor of the v-html directive .

Upgrade Path

Run the migration helper on your codebase to find HTML interpolations.

One-Time Bindings ^replaced

One time bindings ( {{* foo }} ) have been replaced by the new v-once directive .

Upgrade Path

Run the migration helper on your codebase to find one-time bindings.

Reactivity

vm.$watch ^changed

Watchers created via vm.$watch are now fired before the associated component rerenders. This gives you the chance to further update state before the component rerender, thus avoiding unnecessary updates. For example, you can watch a component prop and update the component’s own data when the prop changes.

vm.$set ^changed

vm.$set is now an alias for Vue.set .

Upgrade Path

Run the migration helper on your codebase to find examples of the obsolete usage.

vm.$delete ^changed

vm.$delete is now an alias for Vue.delete .

Upgrade Path

Run the migration helper on your codebase to find examples of the obsolete usage.

Array.prototype.$set ^removed

Use Vue.set instead.

Run the migration helper on your codebase to find examples of .$set on an array. If you miss any, you should see console errors from the missing method.

Array.prototype.$remove ^removed

Use Array.prototype.splice instead. For example:

methods: {
  removeTodo: function (todo) {
    var index = this.todos.indexOf(todo)
    this.todos.splice(index, 1)
  }
}

methods: {
  removeTodo: function (index) {
    this.todos.splice(index, 1)
  }
}

Run the migration helper on your codebase to find examples of .$remove on an array. If you miss any, you should see console errors from the missing method.

Vue.set and Vue.delete on Vue instances ^removed

Vue.set and Vue.delete can no longer work on Vue instances. It is now mandatory to properly declare all top-level reactive properties in the data option. If you’d like to delete properties on a Vue instance or its $data , set it to null.

Run the migration helper on your codebase to find examples of Vue.set or Vue.delete on a Vue instance. If you miss any, they'll trigger console warnings .

Replacing vm.$data ^removed

It is now prohibited to replace a component instance’s root $data. This prevents some edge cases in the reactivity system and makes the component state more predictable (especially with type-checking systems).

Run the migration helper on your codebase to find examples of overwriting vm.$data . If you miss any, console warnings will be emitted.

vm.$get ^removed

Instead, retrieve reactive data directly.

Run the migration helper on your codebase to find examples of vm.$get . If you miss any, you'll see console errors .

DOM-Focused Instance Methods

vm.$appendTo ^removed

Use the native DOM API:

myElement.appendChild(vm.$el)

Run the migration helper on your codebase to find examples of vm.$appendTo . If you miss any, you'll see console errors .

vm.$before ^removed

Use the native DOM API:

myElement.parentNode.insertBefore(vm.$el, myElement)

Run the migration helper on your codebase to find examples of vm.$before . If you miss any, you'll see console errors .

vm.$after ^removed

Use the native DOM API:

myElement.parentNode.insertBefore(vm.$el, myElement.nextSibling)

myElement.parentNode.appendChild(vm.$el)

Run the migration helper on your codebase to find examples of vm.$after . If you miss any, you'll see console errors .

vm.$remove ^removed

Use the native DOM API:

vm.$el.remove()

Run the migration helper on your codebase to find examples of vm.$remove . If you miss any, you'll see console errors .

Meta Instance Methods

vm.$eval ^removed

No real use. If you do happen to rely on this feature somehow and aren’t sure how to work around it, post on the forum for ideas.

Upgrade Path

Run the migration helper on your codebase to find examples of vm.$eval . If you miss any, you'll see console errors .

vm.$interpolate ^removed

No real use. If you do happen to rely on this feature somehow and aren’t sure how to work around it, post on the forum for ideas.

Upgrade Path

Run the migration helper on your codebase to find examples of vm.$interpolate . If you miss any, you'll see console errors .

vm.$log ^removed

Use the Vue Devtools for the optimal debugging experience.

Upgrade Path

Run the migration helper on your codebase to find examples of vm.$log . If you miss any, you'll see console errors .

Instance DOM Options

replace: false ^removed

Components now always replace the element they’re bound to. To simulate the behavior of replace: false , you can wrap your root component with an element similar to the one you’re replacing. For example:

new Vue({
  el: '#app',
  template: '<div id="app"> ... </div>'
})

new Vue({
  el: '#app',
  render: function (h) {
    h('div', {
      attrs: {
        id: 'app',
      }
    }, /* ... */)
  }
})

Run the migration helper on your codebase to find examples of replace: false .

Global Config

Vue.config.debug ^removed

No longer necessary, since warnings come with stack traces by default now.

Run the migration helper on your codebase to find examples of Vue.config.debug .

Vue.config.async ^removed

Async is now required for rendering performance.

Run the migration helper on your codebase to find examples of Vue.config.async .

Vue.config.delimiters ^replaced

This has been reworked as a component-level option . This allows you to use alternative delimiters within your app without breaking 3rd-party components.

Upgrade Path

Run the migration helper on your codebase to find examples of Vue.config.delimiters .

Vue.config.unsafeDelimiters ^removed

HTML interpolation has been removed in favor of v-html .

Upgrade Path

Run the migration helper on your codebase to find examples of Vue.config.unsafeDelimiters . After this, the helper will also find instances of HTML interpolation so that you can replace them with `v-html`.

Global API

Vue.extend with el ^removed

The el option can no longer be used in Vue.extend . It’s only valid as an instance creation option.

Vue.elementDirective ^removed

Use components instead.

Run the migration helper on your codebase to find examples of Vue.elementDirective .

Vue.partial ^removed

Partials have been removed in favor of more explicit data flow between components, using props. Unless you’re using a partial in a performance-critical area, the recommendation is to use a normal component instead. If you were dynamically binding the name of a partial, you can use a dynamic component .

If you happen to be using partials in a performance-critical part of your app, then you should upgrade to functional components . They must be in a plain JS/JSX file (rather than in a .vue file) and are stateless and instanceless, like partials. This makes rendering extremely fast.

A benefit of functional components over partials is that they can be much more dynamic, because they grant you access to the full power of JavaScript. There is a cost to this power however. If you’ve never used a component framework with render functions before, they may take a bit longer to learn.

Upgrade Path

Run the migration helper on your codebase to find examples of Vue.partial .