Api

Component Options

Data

data

The data object for the Vue instance. It can be accessed as vm.$data:

1
2
3
4
5
var data = { a: 1 }
var vm = new Vue({
  data: data
})
vm.$data === data // -> true

The Vue instance will proxy access to all its properties, therefore you can manipulate the properties on the Vue instance and the changes get synced back to the actual data object:

1
2
3
4
5
vm.a   // -> 1
vm.a = 2
data.a // -> 2
data.a = 3
vm.a   // -> 3

The object must be JSON-compliant (no circular references). You can use it just like an ordinary object, and it will look exactly the same when serialized with JSON.stringify. You can also share it between multiple Vue instances.

A special case here is when using the data option in Vue.extend(). Since we don’t want nested objects to be shared by all instances created from that extended constructor, we must provide a function that returns a fresh copy of the default data:

1
2
3
4
5
6
7
8
9
10
var MyComponent = Vue.extend({
  data: function () {
    return {
      message: 'some default data.',
      object: {
        fresh: true
      }
    }
  }
})

Under the hood, Vue.js attaches a hidden property __ob__ and recursively converts the object’s enumerable properties into getters and setters to enable dependency collection. Properties with keys that starts with $ or _ are skipped.

methods

Methods to be mixed into the Vue instance. You can access these methods directly on the VM instance, or use them in directive expressions. All methods will have their this context automatically bound to the Vue instance.

Example:

1
2
3
4
5
6
7
8
9
10
var vm = new Vue({
  data: { a: 1 },
  methods: {
    plus: function () {
      this.a++
    }
  }
})
vm.plus()
vm.a // 2

computed

Computed properties to be mixed into the Vue instance. All getters and setters have their this context automatically bound to the Vue instance.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
var vm = new Vue({
  data: { a: 1 },
  computed: {
    // get only, just need a function
    aDouble: function () {
      return this.a * 2
    },
    // both get and set
    aPlus: {
      get: function () {
        return this.a + 1
      },
      set: function (v) {
        this.a = v - 1
      }
    }
  }
})
vm.aPlus   // -> 2
vm.aPlus = 3
vm.a       // -> 2
vm.aDouble // -> 4

paramAttributes

An array of attribute names to be set on the Vue instance as initial data. Useful when passing data to a component.

Example:

1
2
3
4
5
6
7
Vue.component('param-demo', {
  paramAttributes: ['size', 'message'],
  compiled: function () {
    console.log(this.size)    // -> 100
    console.log(this.message) // -> 'hello!'
  }
})
1
<param-demo size="100" message="hello!"></param-demo>

Param attributes can also contain interpolation tags. The interpolation will be evaluated against the parent, and under the hood they will be compiled as v-with, which means when the value of the interpolated expression changes, the component’s corresponding property will also be updated:

1
<param-demo message="{{parentMessage}}"></param-demo>

Notes on hyphened attributes

HTML attribute names ignore upper and lower case differences, so we usually use hyphened attributes instead of camel case. There are some special cases when using paramAttributes with attributes that contains hyphens:

  1. If the attribute is a data attribute, the data- prefix will be auto stripped;

  2. If the attribute still contains dashes, it will be camelized. This is because it’s inconvenient to access top level properties containing dashes in templates: the expression my-param will be parsed as a minus expression unless you use the awkward this['my-param'] syntax.

This means a param attribute data-hello will be set on the vm as vm.hello; And my-param will be set as vm.myParam.

DOM

el

Provide the Vue instance with an existing DOM element. It can be a CSS selector string, an actual HTMLElement, or a function that returns an HTMLElement. The resolved element will be accessible as vm.$el.

When used in Vue.extend, a function must be provided so each instance gets a separately created element.

If the option is available at instantiation, the instance will immediately enter compilation; otherwise, the user will have to explicitly call vm.$mount() to manually start the compilation.

template

A string template to be inserted into vm.$el. Any existing markup inside vm.$el will be overwritten, unless content insertion points are present in the template. If the replace option is true, the template will replace vm.$el entirely.

If it starts with # it will be used as a querySelector and use the selected element’s innerHTML and the template string. This allows the use of the common <script type="x-template"> trick to include templates.

Vue.js uses DOM-based templating. The compiler walks through DOM elements and looks for directives and creates data bindings. This means all Vue.js templates are parsable HTML that can be converted into actual DOM elements by the browser. Vue.js converts string templates into DOM fragments so they can be cloned when creating more Vue instances. If you want your templates to be valid HTML, you can configure the directive prefix to start with data-.

replace

Whether to replace the original vm.$el with the template’s content instead of appending to it.

Lifecycle

All lifecycle hooks have their this context bound to the Vue instance they belong to. The Vue instance will also fire corresponding events for each hook in the form of "hook:<hookName>". e.g. for created, a "hook:created" event will be fired.

created

Called synchronously after the instance is created. At this stage, the instance has finished processing the options which means the following have been set up: data observation, computed properties, methods, watch/event callbacks. However, DOM compilation has not been started, and the $el property will not be available yet.

beforeCompile

Called right before the compilation starts.

compiled

Called after the compilation is finished. At this stage all directives have been linked so data changes will trigger DOM updates. However, $el is not guaranteed to have been inserted into the document yet.

ready

Called after compilation and the $el is inserted into the document for the first time. Note this insertion must be executed via Vue (with methods like vm.$appendTo() or as a result of a directive update) to trigger the ready hook.

attached

Called when vm.$el is attached to DOM by a directive or a VM instance method such as $appendTo(). Direct manipulation of vm.$el will not trigger this hook.

detached

Called when vm.$el is removed from the DOM by a directive or a VM instance method. Direct manipulation of vm.$el will not trigger this hook.

beforeDestroy

Called right before a Vue instance is destroyed. At this stage the instance is still fully functional.

destroyed

Called after a Vue instance has been destroyed. When this hook is called, all bindings and directives of the Vue instance have been unbound and all child Vue instances have also been destroyed.

Note if there is a leaving transition, the destroyed hook is called after the transition has finished.

Assets

These are private assets that will be available only to this Vue instance and its children during compilation.

directives

A hash of directives to be made available to the Vue instance. For details on how to write a custom directive, see Writing Custom Directives.

filters

A hash of filters to be made available to the Vue instance. For details on how to write a custom filter, see Writing Custom Filters.

components

A hash of components to be made available to the Vue instance. For details on how to extend and compose Vue instances, see Component System.

partials

A hash of partials to be made available to the Vue instance. Also see v-partial.

transitions

A hash of transitions to be made available to the Vue instance. For details see the guide on Transitions.

Others

inherit

Whether to inherit parent scope data. Set it to true if you want to create a component that inherits parent scope. When inherit is set to true, you can:

  1. Bind to parent scope properties in the component template;
  2. Directly access parent properties on the component instance itself, via prototypal inheritance.

One important thing to know when using inherit: true is that the child can also set parent properties, because all Vue instance data properties are getter/setters.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
var parent = new Vue({
  data: { a: 1 }
})
var child = parent.$addChild({
  inherit: true,
  data: { b: 2 }
})
child.a  // -> 1
child.b  // -> 2
// the following line modifies parent.a
// instead of creating a new property on child:
child.a = 2
parent.a // -> 2

events

An object where keys are events to listen for and values are the corresponding callbacks. Note these are Vue events rather than DOM events. The value can also be a string of a method name. The Vue instance will call $on() for each entry in the object at instantiation.

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var vm = new Vue({
  events: {
    'hook:created': function () {
      console.log('created!')
    },
    greeting: function (msg) {
      console.log(msg)
    },
    // can also use a string for methods
    bye: 'sayGoodbye'
  },
  methods: {
    sayGoodbye: function () {
      console.log('goodbye!')
    }
  }
}) // -> created!
vm.$emit('greeting', 'hi!') // -> hi!
vm.$emit('bye')             // -> goodbye!

watch

An object where keys are expressions to watch and values are the corresponding callbacks. The value can also be a string of a method name. The Vue instance will call $watch() for each entry in the object at instantiation.

Example:

1
2
3
4
5
6
7
8
9
10
11
var vm = new Vue({
  data: {
    a: 1
  },
  watch: {
    'a': function (val, oldVal) {
      console.log('new: %s, old: %s', val, oldVal)
    }
  }
})
vm.a = 2 // -> new: 2, old: 1

mixins

The mixins option accepts an array of mixin objects. These mixin objects can contain instance options just like normal instance objects, and they will be merged against the eventual options using the same option merging logic in Vue.extend(). e.g. If your mixin contains a created hook and the component itself also has one, both functions will be called.

Example:

1
2
3
4
5
6
7
8
9
var mixin = {
  created: function () { console.log(2) }
}
var vm = new Vue({
  created: function () { console.log(1) },
  mixins: [mixin]
})
// -> 1
// -> 2

name

When inspecting an extended Vue component in the console, the default constructor name is VueComponent, which isn’t very informative. By passing in an optional name option to Vue.extend(), you will get a better inspection output so that you know which component you are looking at. The string will be camelized and used as the component’s constructor name.

Example:

1
2
3
4
5
var Ctor = Vue.extend({
  name: 'cool-stuff'
})
var vm = new Ctor()
console.log(vm) // -> CoolStuff {$el: null, ...}
Caught a mistake or want to contribute to the documentation? Fork this site on Github!