1.0.0 Evangelion

"The fate of destruction is also the joy of rebirth." - SEELE

About the Release

Please read the blog post.

Known Issues

• v-for="(index, val) in items" syntax doesn't update the index properly. This has been fixed in dev branch and will be out in 1.0.1.

Upgrade Guide

General Tips

• If you are familiar with 0.12. or upgrading an active app from 0.12:
  1. Read through the notable changes below to get a general idea of the relatively big changes.
  2. Read through the revised official guide. It is highly recommended to do this before you upgrade.
  3. Upgrade to the 1.0.0 migration build first. The migration build is fully 0.12.16 compatible and also includes all the new features in 1.0.0. It also raises deprecation warnings for any usage of deprecated API.
  4. Consult the full changelog and the updated API Reference as you work through the deprecation warnings. Once your app no longer raises any warnings using the migration build, it should work properly in 1.0.0.
• If you are relatively new to Vue.js:
  • Just go read the official guide!

Notable Changes

• Template Syntax Change

  This is the biggest change: directive syntax has been overhauled. No more multiple clauses; arguments are now placed inside the attribute name. The attribute value should now always be a single JavaScript expression followed by filters.

  • 1.0.0 Template Cheatsheet
  • Detailed Changes
  • Docs

• Strict Mode by Default

  In the past, asset resolution (components, directives, filters...) has implicit fallback: if an asset is not found in the current component, Vue.js will recursively look for it in its parent, its parent's parent... and so on. This allows you to, say, define a component in the root instance and use it in any child component. It is convenient, however we've found that in large projects it results to implicit coupling between a child component and its ancestors. It also hurts maintainability - when you are looking at a child component in isolation, it's hard to identify where an asset comes from because it could've been provided by any ancestor up the component chain.

  Therefore, in 1.0 all asset resolution is "strict": an asset should either be defined on the current component, or defined as a true global asset (using one of the global Vue.xxx asset registration methods).

• Bye v-repeat, Hi v-for

  v-repeat has been replaced by v-for, which is much faster, but comes with a few differences:

  1. A alias is required now: so you should always do v-for="item in items", no more v-for="items".
  2. The scoping is different when you use v-for on a component - it no longer automatically injects the data and meta properties like $index and $key into the component - you now need to explicitly pass them down using props. This makes the child component explicit about where its data comes from.
  • Detailed Changes
  • Docs

• <slot> is the new <content>

  The Web Components spec drafters are ditching the <content> API in favor of <slot>. Since Vue.js components are modeled after Web Components, and since the <slot> API does make things more explicit than relying on CSS selectors, we are moving to the <slot> API too.

  • Reference
  • Docs

Full Changelog (from 0.12.16)

Template Syntax Changes

1. Directive Arguments

   The concept of multiple clauses (multiple directives separated by comma in the same attribute) is deprecated, and directive arguments are moved into the attribute name:

   <!-- before: -->
   <div v-dirname="arg1: expression1, arg2: expression2">
   
   <!-- after: -->
   <div
     v-dirname:arg1="expression1"
     v-dirname:arg2="expression2">

   Using real directives as example:

   <!-- before: -->
   <div v-on="click: doThis, keyup: doThat">
   
   <!-- after: -->
   <div
     v-on:click="doThis"
     v-on:keyup="doThat">

2. Literal Directives

   There is no longer "literal directives" from the implementation perspective. All directives are reactive by default, which makes it easy to know whether an attribute value is an expression or a literal string. If you wish to pass the directive a literal string, use the following syntax:

   <!-- before: no way to tell if this is a string or an expression! -->
   <div v-dirname="abc">
   
   <!-- after: explicitly denoting a literal string -->
   <div v-dirname.literal="abc">

   The ending .literal is called a Binding Modifier, which forces the directive to be bound in literal mode. We will see this concept used below for prop binding types as well. In literal mode, the directive's update function will be called once, with the literal string as the argument.

3. Attribute Bindings

   Mustache tags can only appear inside native attributes. To dynamically bind a custom attribute or a prop, use the v-bind directive (which replaces v-attr):

   <!-- this is valid -->
   <a href="{{baseURL}}/abc"></a>
   
   <!-- these are no longer valid -->
   <component is="{{view}}"></component>
   <partial name="{{partialName}}"></partial>
   
   <!-- use v-bind for non-native attributes -->
   <component v-bind:is="view"></component>
   <partial v-bind:name="partialName"></partial>

   Vue will raise a warning whenever mustaches are used in non-native attributes.

4. Props

   Previously props use mustaches to indicate reactivity. Now they must use v-bind:

   <!-- before -->
   <my-comp
     prop="a literal string"
     prop="{{expression}}">
   <my-comp>
   
   <my-comp
     prop="a literal string"
     v-bind:prop="expression">
   </my-comp>

   Binding type indicators (@ and *) are now replaced by more explicit binding modifiers:

   <!-- before -->
   <my-comp
     prop="{{defaultOneWay}}"
     prop="{{@twoWay}}"
     prop="{{*oneTime}}">
   </my-comp>
   
   <!-- after -->
   <my-comp
     v-bind:prop="defaultOneWay"
     v-bind:prop.sync="twoWay"
     v-bind:prop.once="oneTime">
   </my-comp>

5. Shorthands

   You may have noticed we will be using v-bind and v-on quite a lot. 1.0 will provide optional shorthand syntax for these two directives. v-bind: can be shortened to a single colon :, while v-on: can be shortened to a single @ symbol:

   <!-- attribute binding -->
   <img :src="imgSrc">
   
   <!-- event handlers -->
   <input @click="handleClick" @keyup="handleKeyup">
   
   <!-- props -->
   <my-comp
     :prop="expression"
     :prop.sync="twoWay"
     :prop.once="oneTime">
   </my-comp>
   
   <!-- special attributes -->
   <component :is="view"></component>
   <partial :name="partialName"></partial>

   If you are only using Vue as an enhancement on existing HTML pages, you may want to stick with the v- prefixed versions. The shorthand is designed to make the template more succinct when you are building large SPAs where Vue manages everything. Don't worry about it not looking like valid HTML - all browsers can parse it just fine, and Vue removes all the special stuff in the rendered HTML anyway.

Directive Changes

• v-for

  v-repeat has been deprecated in favor of v-for. Differences between v-for and v-repeat:

  1. Required alias

     Alias is required when using v-for, and the item in items syntax is preferred. It reads more naturally:

     <li v-for="item in items"></li>

     This also means the $value meta property will no longer be used. $index and $key are still available. You can also still refer to the parent scope index in nested loops as $parent.$index.

  2. No more anonymous child VMs

     Previously, v-repeat creates an actual child VM instance with inherit: true for every repeated block. This is no longer the case with v-for: each repeated block in v-for is now a real partially compiled fragment, with a lightweight intermediate "scope". This greatly reduces the overhead and as a result you should see significant performance improvement for both initial rendering (up to 100% for non-component loops) and re-rendering with track-by (up to 50%, as tested in dbmonster).

     This also means:

     1. Using an extra <template> repeat no longer creates the overhead of a child instance.
     2. v-ref would not work on v-for if the repeated block is not a component, because there are no longer anonymous child instances created in that case.

  3. Component Scoping

     Now this is the part that is the most different. Previously when you use a component with v-repeat, you get somewhat weird scoping:

     <!-- can't use $index here -->
     <comp v-repeat="item in list"></comp>

     In the above example, item and $index are automatically available inside the component, but not in the parent template. If you do want to use $index in the parent template, you have to create a <template> to wrap the repeat. In addition, this requires the component implementation to be aware that it is v-repeat specific, because the external data is not...

1.0.0-rc.2

The corresponding migration build for this release is 1.0.0-rc.2-migration.

New

• v-for now support the v-for="(key, val) in obj" or v-for="(index, val) in arr" syntax. This allows nested loops to more easily reference the key or index.

• v-on can now omit the expression if it has modifiers. e.g. @submit.prevent will call preventDefault() on submit events.

• Custom directive API improvement:

  Custom directives can now provide a params Array, and the Vue compiler will automatically extract these attributes on the element that the directive is bound to. The old undocumented this.param() directive instance method has been deprecated.

  Example:

  <div v-example a="hi"></div>

  Vue.directive('example', {
    params: ['a'],
    bind: function () {
      console.log(this.params.a) // -> "hi"
    }
  })

  This API also supports dynamic attributes. The this.params[key] value is automatically kept up-to-date. In addition, you can specify a callback when the value has changed:

  <div v-example :a="someValue"></div>

  Vue.directive('example', {
    params: ['a'],
    paramWatchers: {
      a: function (val, oldVal) {
        console.log('a changed!')
      }
    }
  })

Fixed

• #1431 props with the same name not properly merged
• #1440 v-for components detach hook not called
• #1442 directives on a child component root not resolved in the right scope
• #1458 :class array syntax not removing stale classes

1.0.0-rc.1

Upgrade Note

The API can now be considered stable. Documentation for 1.0.0-rc.1 is available at rc.vuejs.org. It is recommended to read through the updated guide section before upgrading.

If you are upgrading from 0.12, the following list of changes may seem a bit overwhelming. To make it easier to migrate your existing app, there is a migration release (1.0.0-alpha.8) with full 0.12.16 compatibility and all the new features in 1.0.0. In addition, the migration release will raise deprecation warnings that will guide you to gradually migrate your app. When your app no longer raise any warnings in 1.0.0-alpha.8, it should work properly in 1.0.0-rc.1.

Changes from 1.0.0-beta.4

• Added init lifecycle hook, which is called before an instance's data observation. This is mainly intended for advanced plugin authors.
• Restrictions on attribute interpolation have been relaxed, now it uses a blacklist instead of a whitelist check which should no longer raise warnings on valid native attributes.

Full Changes from 0.12.16

Breaking

General

• The data binding syntax has been redesigned. Details

• The prefix global config has been deprecated. All directives will now consistently use the v- prefix.

• The strict global config has been deprecated. Asset resolution is now always in strict mode. Details

• The interpolate global config has been deprecated. Use v-pre on elements that should be skipped by the template compiler.

• The proto global config has been deprecated. This has served no practical purpose and almost never used.

• The inherit option has been deprecated. Alway pass data to child components via props.

• The $add method has been deprecated for both Vue instances and observed objects. Use $set instead. Details

• Event propagation for events sent via $dispatch and $broadcast now stops when it triggers a handler for the first time, unless the handler explicitly returns true. Details

• $dispatch now also triggers the event on the instance calling it.

• Vue no longer extends Object.prototype with $set and $delete methods. This has been causing issues with libraries that rely on these properties in certain condition checks (e.g. minimongo in Meteor). Instead of object.$set(key, value) and object.$delete(key), use the new global methods Vue.set(object, key, value) and Vue.delete(object, key).

• Array.prototype.$remove: now always treats the argument as the item to search for. (Previously it treats the argument as an index if the argument is a number).

• Instance method vm.$addChild() has been deprecated. Instead, a new option, parent has been (re)introduced. The usage is pretty simple:

  // before
  var child = parent.$addChild(options)
  
  // after
  var child = new Vue({ parent: parent })

• The orderBy filter now expects its second argument to be a number instead of a boolean. The argument was originally called reverse, and is now called order. A value that is greater than or equal to 0 indicates ascending order, a value smaller than 0 indicates descending order. As a result, the old syntax for descending order still works:

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

• Global asset registration methods, e.g. Vue.component, now returns the registered asset. This means you can now create, globally register and get reference to a component constructor in one step:

  var MyComponent = Vue.component('my-component', options)
  
  // equivalent to:
  var MyComponent = Vue.extend(options)
  Vue.component('my-component', MyComponent)

Directives

• v-repeat has been deprecated in favor of v-for. Details

  In addition to the differences specified in the link above:

  • v-for no longer uses track-by="$index" behavior for Arrays of primitive values by default. It now uses the value itself as the cache key. As a result, v-for will raise warning when the Array contains duplicate values and prompt the user to use track-by="$index" to handle duplicate values.
  • v-for no longer converts the value to Array before piping it through filters. Custom filters used on v-for will now get the raw value. However, the built-in filterBy and orderBy filters will convert the values into Arrays, so any filters after them will received the converted Array values.

• v-class and v-style have been deprecated in favor of the new binding syntax (v-bind:class and v-bind:style, for details see the end of No.3 here)

• v-ref and v-el usage has changed. Details

• v-component has been deprecated in favor of the is attribute. Details

• Added v-else directive. Details

• v-model: multiple checkbox input can now be bound to the same v-model value (must be an Array):

  <input type="checkbox" value="Jack" v-model="checkedNames">
  <input type="checkbox" value="John" v-model="checkedNames">
  <input type="checkbox" value="Mike" v-model="checkedNames">

  With checkedNames' initial value being an Array, the checked boxes' values will be pushed into the Array, while unchecked ones will be removed from it. For example, if we check the first two boxes, checkedNames will have the value ["Jack", "John"]. Of course, you can also dynamically bind the value with v-bind.

• v-on: added two modifiers, .stop and .prevent which automatically calls event.stopPropagation() and event.preventDefault() for you:

  <!-- event won't propagate -->
  <a v-on:click.stop="doThis"></a>
  
  <!-- this will no longer reload the page! -->
  <form v-on:submit.prevent="onSubmit"></form>

• v-on will now also listen to custom Vue events when used on a child component. (See No.6 here)

• The key filter for v-on has been deprecated. Instead, use the new key modifer syntax. (See No.7 here)

• The options param for <select v-model> has been deprecated. You can now just use v-for to render the options and it will work properly with the v-model on the containing <select> element.

• The wait-for param for components has been deprecated in favor of the new activate lifecycle hook. Details

Component API

• <content> outlet has been deprecated in favor of the new <slot> API. Details
• Props syntax has changed as part of the new binding syntax.
• $data can no longer be used as a prop.
• Props with the data- prefix are no longer supported.
• Literal props will no longer be auto-casted into Booleans or Numbers - they are now always passed down as Strings.

Non-Breaking Changes

• vm.$log() messages now also include computed properties.
• Prop expressions now support filters.

1.0.0-beta.4

About this Release

This is planned to be the last beta release. The first RC will be out next week and official release is planned for end of October.

The corresponding migration build for this release is 1.0.0-alpha.8.

1.0 documentation preview that matches this release is now available at rc.vuejs.org.

Changes from 1.0.0-beta.3

Breaking

• Vue no longer extends Object.prototype with $set and $delete methods. This has been causing issues with libraries that rely on these properties in certain condition checks (e.g. minimongo in Meteor). Instead of object.$set(key, value) and object.$delete(key), use the new global methods Vue.set(object, key, value) and Vue.delete(object, key).

• Instance method vm.$addChild() has been deprecated. Instead, a new option, parent has been (re)introduced. The usage is pretty simple:

  // before
  var child = parent.$addChild(options)
  
  // after
  var child = new Vue({ parent: parent })

• The global config proto has been deprecated. This has served no practical purpose and almost never used.

• v-for no longer uses track-by="$index" behavior for Arrays of primitive values by default. It now uses the value itself as the cache key. As a result, v-for will raise warning when the Array contains duplicate values and prompt the user to use track-by="$index" to handle duplicate values.

• v-for no longer converts the value to Array before piping it through filters. Custom filters used on v-for will now get the raw value. However, the built-in filterBy and orderBy filters will convert the values into Arrays, so any filters after them will received the converted Array values.

• The orderBy filter now expects its second argument to be a number instead of a boolean. The argument was originally called reverse, and is now called order. A value that is greater than or equal to 0 indicates ascending order, a value smaller than 0 indicates descending order. As a result, the old syntax for descending order still works:

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

• Global asset registration methods, e.g. Vue.component, now returns the registered asset. This means you can now create, globally register and get reference to a component constructor in one step:

  var MyComponent = Vue.component('my-component', options)
  
  // equivalent to:
  var MyComponent = Vue.extend(options)
  Vue.component('my-component', MyComponent)

Non Breaking

• v-on can now handle multiple key modifiers:

  <input @keyup.enter.esc="onEnterOrEsc">

• Directive modifiers are now exposed to custom directive instances as this.modifiers:

  <div v-my-directive.one.two="xxx">

  Vue.directive('my-directive', {
    bind: function () {
      this.modifiers.one // -> true
      this.modifiers.two // -> true
    }
  })

Fixed

• #1398 Use more reliable visibility check for transitions. This fixes situations where elements are stuck on leave if the parent element is not visible.
• #1399 Modifiers are no longer included in this.arg for custom directives.
• #1400 only warn twoWay prop binding type mismatch when the prop is present.

1.0.0-beta.3

Upgrade Note: If you are upgrading to this release from 0.12.x, install 1.0.0-alpha.7 first, which has full 0.12 compatibility and appropriate deprecation warnings that can help you identify deprecations that need to be fixed.

New

• v-model: multiple checkbox input can now be bound to the same v-model value (must be an Array):

  <input type="checkbox" value="Jack" v-model="checkedNames">
  <input type="checkbox" value="John" v-model="checkedNames">
  <input type="checkbox" value="Mike" v-model="checkedNames">

  With checkedNames' initial value being an Array, the checked boxes' values will be pushed into the Array, while unchecked ones will be removed from it. For example, if we check the first two boxes, checkedNames will have the value ["Jack", "John"]. Of course, you can also dynamically bind the value with v-bind.

• v-on: added two modifiers, .stop and .prevent which automatically calls event.stopPropagation() and event.preventDefault() for you:

  <!-- event won't propagate -->
  <a v-on:click.stop="doThis"></a>
  
  <!-- this will no longer reload the page! -->
  <form v-on:submit.prevent="onSubmit"></form>

Changed

• vm.$dispatch: now also triggers the event on self.
• Array.prototype.$remove: now always treats the argument as the item to search for. (Previously it treats the argument as an index if the argument is a number).

Fixed

• Improved attribute interpolation validity check by including a11y and a more complete list of global attributes.
• #1363 partial: dynamic partial resolved in wrong scope when inside v-for
• #1370 observer: v-for alias not reactive when replaced
• #1378 props: error parsing path for two-way props with dynamic paths

1.0.0-beta.2

Upgrade Note: If you are upgrading to this release from 0.12.x, install 1.0.0-alpha.6 first, which has full 0.12 compatibility and appropriate deprecation warnings that can help you identify deprecations that need to be fixed.

Includes all changes in 0.12.16. In addition:

New

• Attribute interpolations are back! You can again use this familiar syntax:

  <a href="{{baseUrl}}/abc"></a>

  However, this syntax now has a limitation: it is now allowed only in native attributes that are appropriate on the current element. If you use it in a directive, a non-native attribute, or a prop, Vue will warn you. This makes it explicit where mustaches are allowed, while keeping the familiar and syntax which sometimes is more convenient than v-bind.

• v-else now works with v-show:

  <div v-show="ok">OK</div>
  <div v-else>NOT OK</div>

Fixed

• Compatibility with vue-router 0.6.1.
• Fixed event propagation stopping without triggering any handler.
• Fixed special filter arguments, e.g. in in filterBy search in 'name' not correctly recognized as special case string.

1.0.0-alpha.6

Includes all changes in 0.12.16. In addition:

• v-else now works with v-show:

  <div v-show="ok">OK</div>
  <div v-else>NOT OK</div>

• Adjusted attribute interpolation deprecation warnings to be in accordance with 1.0.0-beta.2.

0.12.16

New

• New global method: Vue.mixin().

  Apply a global mixin to all Vue instances. This is intended to make it easier for plugins to inject custom behavior. Not recommended in application code.

• vm.$watch can now accept expressions with filters:

  vm.$watch('msg | uppercase', ...)

Fixed

• Fixed a performance regression introduced in 0.12 which made filtering super large arrays (> 5000 items) very slow.
• vm.$interpolate now always returns a string.

Internals

• Vue.config.optionMergeStrategies is now exposed for plugin authors. (This is already in 1.0.0 series releases)

1.0.0-beta.1

This is the first beta release for 1.0.0, which implements all the changes / new features currently available in 1.0.0-alpha.5, but without the backwards compatibility. If your app works in 1.0.0-alpha.5 without raising any deprecation warnings, then it should work properly in 1.0.0-beta.1.

The API can be considered relatively stable. Breaking changes are still possible in new beta releases, but will be kept to a minimum with best effort.

Full Changes from 0.12.15

Breaking

General

• The data binding syntax has been redesigned. Details
• The prefix global config has been deprecated. All directives will now consistently use the v- prefix.
• The strict global config has been deprecated. Asset resolution is now always in strict mode. Details
• The interpolate global config has been deprecated. Use v-pre on elements that should be skipped by the template compiler.
• The inherit option has been deprecated. Alway pass data to child components via props.
• The $add method has been deprecated for both Vue instances and observed objects. Use $set instead. Details
• Event propagation for events sent via $dispatch and $broadcast now stops when it triggers a handler for the first time, unless the handler explicitly returns true. Details

Directives

• v-repeat has been deprecated in favor of v-for. Details
• v-class and v-style have been deprecated in favor of the new binding syntax. Details
• v-ref and v-el usage has changed. Details
• v-component has been deprecated in favor of the is attribute. Details
• v-on will now also listen to custom Vue events when used on a child component. Details
• The key filter for v-on has been deprecated. Instead, use the new key modifer syntax. Details
• The options param for <select v-model> has been deprecated. You can now just use v-for to render the options and it will work properly with the v-model on the containing <select> element.
• The wait-for param for components has been deprecated in favor of the new activate lifecycle hook. Details

Component API

• <content> outlet has been deprecated in favor of the new <slot> API. Details
• Props syntax has changed as part of the new binding syntax.
• $data can no longer be used as a prop.
• Props with the data- prefix are no longer supported.
• Literal props will no longer be auto-casted into Booleans or Numbers - they are now always passed down as Strings.

Non-Breaking Changes

• vm.$log() messages now also include computed properties.
• Prop expressions now support filters.

1.0.0-alpha.5

Alpha versions are pre-releases and the API may change at any time. By using the alpha releases you are responsible for any risk involved. If you have an in-production 0.12 app, it's recommended to wait until the stable 1.0 migration release before upgrading.

Changes from 1.0.0-alpha.4

Breaking

For a full reference of the latest syntax, see #1325

• bind-attr is now replaced by v-bind:attr, with :attr as shorthand;
• on-event is now replaced by v-on:event, with @event as shorthand; Also, key filter is now denoted with . as a modifier: @keyup.esc="handleEsc".
• Literal directive: v-dir#="xxx" is now replaced by v-dir.literal="xxx".
• Prop binding types:
  • :prop@="twoWay" is now replaced by :prop.sync="twoWay"
  • :prop*="oneTime" is now replaced by :prop.once="oneTime"
• Child component and element refs:
  • $.child is now replaced by v-ref:child. vm.$ is also renamed to vm.$refs.
  • $$.node is now replaced by v-el:node. vm.$$ is also renamed to vm.$els.

Non-breaking

• v-on now also works for custom events when used on a child component.

Fixed

• all fixes in 0.12.15.