Releases: vuejs/vue
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 theindex
properly. This has been fixed indev
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:
- Read through the notable changes below to get a general idea of the relatively big changes.
- Read through the revised official guide. It is highly recommended to do this before you upgrade.
- 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.
- 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.
-
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 byv-for
, which is much faster, but comes with a few differences:- A alias is required now: so you should always do
v-for="item in items"
, no morev-for="items"
. - 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.
- A alias is required now: so you should always do
-
<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.
Full Changelog (from 0.12.16)
Template Syntax Changes
-
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">
-
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'supdate
function will be called once, with the literal string as the argument. -
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 replacesv-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.
-
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>
-
Shorthands
You may have noticed we will be using
v-bind
andv-on
quite a lot. 1.0 will provide optional shorthand syntax for these two directives.v-bind:
can be shortened to a single colon:
, whilev-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 ofv-for
. Differences betweenv-for
andv-repeat
:-
Required alias
Alias is required when using
v-for
, and theitem 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
. -
No more anonymous child VMs
Previously,
v-repeat
creates an actual child VM instance withinherit: true
for every repeated block. This is no longer the case withv-for
: each repeated block inv-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 withtrack-by
(up to 50%, as tested in dbmonster).This also means:
- Using an extra
<template>
repeat no longer creates the overhead of a child instance. v-ref
would not work onv-for
if the repeated block is not a component, because there are no longer anonymous child instances created in that case.
- Using an extra
-
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 isv-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 thev-for="(key, val) in obj"
orv-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 callpreventDefault()
onsubmit
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 undocumentedthis.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
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 thev-
prefix. -
The
strict
global config has been deprecated. Asset resolution is now always in strict mode. Details -
The
interpolate
global config has been deprecated. Usev-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 returnstrue
. 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 ofobject.$set(key, value)
andobject.$delete(key)
, use the new global methodsVue.set(object, key, value)
andVue.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 calledreverse
, and is now calledorder
. A value that is greater than or equal to0
indicates ascending order, a value smaller than0
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 ofv-for
. DetailsIn addition to the differences specified in the link above:
v-for
no longer usestrack-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 usetrack-by="$index"
to handle duplicate values.v-for
no longer converts the value to Array before piping it through filters. Custom filters used onv-for
will now get the raw value. However, the built-infilterBy
andorderBy
filters will convert the values into Arrays, so any filters after them will received the converted Array values.
-
v-class
andv-style
have been deprecated in favor of the new binding syntax (v-bind:class
andv-bind:style
, for details see the end of No.3 here) -
v-ref
andv-el
usage has changed. Details -
v-component
has been deprecated in favor of theis
attribute. Details -
Added
v-else
directive. Details -
v-model
: multiple checkbox input can now be bound to the samev-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 withv-bind
. -
v-on
: added two modifiers,.stop
and.prevent
which automatically callsevent.stopPropagation()
andevent.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 forv-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 usev-for
to render the options and it will work properly with thev-model
on the containing<select>
element. -
The
wait-for
param for components has been deprecated in favor of the newactivate
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 ofobject.$set(key, value)
andobject.$delete(key)
, use the new global methodsVue.set(object, key, value)
andVue.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 usestrack-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 usetrack-by="$index"
to handle duplicate values. -
v-for
no longer converts the value to Array before piping it through filters. Custom filters used onv-for
will now get the raw value. However, the built-infilterBy
andorderBy
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 calledreverse
, and is now calledorder
. A value that is greater than or equal to0
indicates ascending order, a value smaller than0
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 samev-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 withv-bind
. -
v-on
: added two modifiers,.stop
and.prevent
which automatically callsevent.stopPropagation()
andevent.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 withv-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
infilterBy 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 withv-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 thev-
prefix. - The
strict
global config has been deprecated. Asset resolution is now always in strict mode. Details - The
interpolate
global config has been deprecated. Usev-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 returnstrue
. Details
Directives
v-repeat
has been deprecated in favor ofv-for
. Detailsv-class
andv-style
have been deprecated in favor of the new binding syntax. Detailsv-ref
andv-el
usage has changed. Detailsv-component
has been deprecated in favor of theis
attribute. Detailsv-on
will now also listen to custom Vue events when used on a child component. Details- The
key
filter forv-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 usev-for
to render the options and it will work properly with thev-model
on the containing<select>
element. - The
wait-for
param for components has been deprecated in favor of the newactivate
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 byv-bind:attr
, with:attr
as shorthand;on-event
is now replaced byv-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 byv-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 byv-ref:child
.vm.$
is also renamed tovm.$refs
.$$.node
is now replaced byv-el:node
.vm.$$
is also renamed tovm.$els
.
Non-breaking
v-on
now also works for custom events when used on a child component.
Fixed
- all fixes in 0.12.15.