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 received via the standardprops
interface.With
v-for
, you get the expected scoping:<comp v-for="item in list" :id="$index" :data="item"> </comp>
And you need to explicitly pass external data into the component as
props
. This makes your component implementation no longerv-repeat
specific and less magical. -
v-for
also supports 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-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 and v-style
-
v-class
andv-style
have been deprecated in favor of the new binding syntax (v-bind:class
andv-bind:style
). Bindings forclass
andstyle
have some dedicated enhancements. You can pass in JavaScript Object or Array literals:<!-- toggle classes --> <div v-bind:class="{ 'class-a': true, 'class-b': false }"></div> <!-- apply a list of classes --> <div v-bind:class="[ dynamicClass, 'literal-class' ]"></div> <!-- apply style object (camelCase accepted) --> <div v-bind:style="{ fontSize: '14px', color: 'red' }"></div> <!-- apply multiple style objects --> <div v-bind:style="[ styleObjectA, styleObjectB ]"></div>
-
-
v-on
-
You can use the
.stop
and.prevent
modifiers for callingstopPropagation()
andpreventDefault()
:<!-- event won't propagate --> <a v-on:click.stop="doThis"></a> <!-- this will no longer reload the page! --> <form v-on:submit.prevent></form>
-
The
key
filter forv-on
has been deprecated.v-on
can now leverage a Key Modifier that replaces the oldkey
filter (you can use all the old aliases usable in the key filter, or use a direct keyCode):<!-- before --> <input v-on=" keyup: handleEnter | key 'enter', keyup: handleEsc | key 'esc'"> <!-- after --> <input @keyup.enter="handleEnter" @keyup.esc="handleEsc">
-
v-on
will now also listen to custom Vue events (emitted viavm.$emit
) when it is used on a child component. The idea is that props and events should constitute the public API of a component:- props for passing data down;
- events for handling actions up.
A typical component would look like this:
<item-list v-bind:items="items" v-bind:mode="active" v-on:ready="onItemsReady" v-on:update="onItemsUpdate"> </item-list>
With shorthand:
<item-list :items="items" :mode="active" @ready="onItemsReady" @update="onItemsUpdate"> </item-list>
-
-
v-ref and v-el
v-el
andv-ref
were previously "literal" directives, but you just need to give them an argument. Also, to make things more explicit,vm.$
is nowvm.$refs
, andvm.$$
is nowvm.$els
.<!-- child component ref, registers vm.$refs.child --> <comp v-ref:child></comp> <!-- elsewhere... --> {{$refs.child.msg}} <!-- element ref, registers vm.$els.node --> <div v-el:node></div>
Caveat: camelCase names are converted to all lowercase when the HTML is parsed:
<comp v-ref:someThing></comp>
Gets rendered as:
<comp v-ref:something></comp>
Thus, it is necessary to use the dash-case <-> camelCase mapping for refs too (similar to props):
<comp v-ref:some-thing></comp> {{ $refs.someThing.msg }}
-
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 withv-bind
. -
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.
-
-
v-component
-
New Directive
- Added
v-else
directive. Docs
- Added
Component API Changes
<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 now longer supported. - Literal props will no longer be auto-casted into Booleans or Numbers - they are now always passed down as Strings.
Filter Changes
-
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>
General API Changes
-
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 })
-
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)
-
vm.$log()
messages now also include computed properties. -
Prop expressions now support filters.