`. This allows us to more safely keep developing that component, without fear that we might change/remove something that a child component is relying on. The interface between these components remains clearly defined, just as with `props`.
+
+In fact, you can think of dependency injection as sort of "long-range props", except:
+
+* ancestor components don't need to know which descendants use the properties it provides
+* descendant components don't know need to know where injected properties are coming from
+
+However, there are downsides to dependency injection. It couples components in your application to the way they're currently organized, making refactoring more difficult. Provided properties are also not reactive. This is by design, because using them to create a central data store scales just as poorly as using $root for the same purpose. If the properties you want to share are specific to your app, rather than generic, or if you ever want to update provided data inside ancestors, then that's a good sign that you probably need a real state management solution like Vuex instead.
+
+Learn more about dependency injection in [the API doc](https://vuejs.org/v2/api/#provide-inject).
+
+## Programmatic Event Listeners
+
+So far, you've seen uses of `$emit`, listened to with `v-on`, but Vue instances also offer other methods in its events interface. We can:
+
+- Listen for an event with `$on(eventName, eventHandler)`
+- Listen for an event only once with `$once(eventName, eventHandler)`
+- Stop listening for an event with `$off(eventName, eventHandler)`
+
+You normally won't have to use these, but they're available for cases when you need to manually listen for events on a component instance. To learn more about their usage, check out the API for [Events Instance Methods](https://vuejs.org/v2/api/#Instance-Methods-Events).
+
+Note that Vue's event system is different from the browser's EventTarget API . Though they work similarly, $emit, $on, and $off are not aliases for dispatchEvent, addEventListener, and removeEventListener.
+
+## Circular References
+
+### Recursive Components
+
+Components can recursively invoke themselves in their own template. However, they can only do so with the `name` option:
+
+``` js
+name: 'unique-name-of-my-component'
+```
+
+When you register a component globally using `Vue.component`, the global ID is automatically set as the component's `name` option.
+
+``` js
+Vue.component('unique-name-of-my-component', {
+ // ...
+})
+```
+
+If you're not careful, recursive components can also lead to infinite loops:
+
+``` js
+name: 'stack-overflow',
+template: '
'
+```
+
+A component like the above will result in a "max stack size exceeded" error, so make sure recursive invocation is conditional (i.e. uses a `v-if` that will eventually be `false`).
+
+### Circular References Between Components
+
+Let's say you're building a file directory tree, like in Finder or File Explorer. You might have a `tree-folder` component with this template:
+
+``` html
+
+ {{ folder.name }}
+
+```
+
+Then a `tree-folder-contents` component with this template:
+
+``` html
+
+
+ {{ child.name }}
+
+
+```
+
+When you look closely, you'll see that these components will actually be each other's descendent _and_ ancestor in the render tree - a paradox! When registering components globally with `Vue.component`, this paradox is resolved for you automatically. If that's you, you can stop reading here.
+
+However, if you're requiring/importing components using a __module system__, e.g. via Webpack or Browserify, you'll get an error:
+
+```
+Failed to mount component: template or render function not defined.
+```
+
+To explain what's happening, let's call our components A and B. The module system sees that it needs A, but first A needs B, but B needs A, but A needs B, etc. It's stuck in a loop, not knowing how to fully resolve either component without first resolving the other. To fix this, we need to give the module system a point at which it can say, "A needs B _eventually_, but there's no need to resolve B first."
+
+In our case, let's make that point the `tree-folder` component. We know the child that creates the paradox is the `tree-folder-contents` component, so we'll wait until the `beforeCreate` lifecycle hook to register it:
+
+``` js
+beforeCreate: function () {
+ this.$options.components.TreeFolderContents = require('./tree-folder-contents.vue').default
+}
+```
+
+Or alternatively, you could use Webpack's asynchronous `import` when you register the component locally:
+
+``` js
+components: {
+ TreeFolderContents: () => import('./tree-folder-contents.vue')
+}
+```
+
+Problem solved!
+
+## Alternate Template Definitions
+
+### Inline Templates
+
+When the `inline-template` special attribute is present on a child component, the component will use its inner content as its template, rather than treating it as distributed content. This allows more flexible template-authoring.
+
+``` html
+
+
+
These are compiled as the component's own template.
+
Not parent's transclusion content.
+
+```
+
+However, inline-template makes the scope of your templates harder to reason about. As a best practice, prefer defining templates inside the component using the template option or in a <template> element in a .vue file.
+
+### X-Templates
+
+Another way to define templates is inside of a script element with the type `text/x-template`, then referencing the template by an id. For example:
+
+``` html
+
+```
+
+``` js
+Vue.component('hello-world', {
+ template: '#hello-world-template'
+})
+```
+
+These can be useful for demos with large templates or in extremely small applications, but should otherwise be avoided, because they separate templates from the rest of the component definition.
+
+## Controlling Updates
+
+Thanks to Vue's Reactivity system, it always knows when to update (if you use it correctly). There are edge cases, however, when you might want to force an update, despite the fact that no reactive data has changed. Then there are other cases when you might want to prevent unnecessary updates.
+
+### Forcing an Update
+
+If you find yourself needing to force an update in Vue, in 99.99% of cases, you've made a mistake somewhere.
+
+You may not have accounted for change detection caveats [with arrays](https://vuejs.org/v2/guide/list.html#Caveats) or [objects](https://vuejs.org/v2/guide/list.html#Object-Change-Detection-Caveats), or you may be relying on state that isn't tracked by Vue's reactivity system, e.g. with `data`.
+
+However, if you've ruled out the above and find yourself in this extremely rare situation of having to manually force an update, you can do so with [`$forceUpdate`](../api/#vm-forceUpdate).
+
+### Cheap Static Components with `v-once`
+
+Rendering plain HTML elements is very fast in Vue, but sometimes you might have a component that contains **a lot** of static content. In these cases, you can ensure that it's only evaluated once and then cached by adding the `v-once` directive to the root element, like this:
+
+``` js
+Vue.component('terms-of-service', {
+ template: `
+
+
Terms of Service
+ ... a lot of static content ...
+
+ `
+})
+```
+
+Once again, try not to overuse this pattern. While convenient in those rare cases when you have to render a lot of static content, it's simply not necessary unless you actually notice slow rendering -- plus, it could cause a lot of confusion later. For example, imagine another developer who's not familiar with v-once or simply misses it in the template. They might spend hours trying to figure out why the template isn't updating correctly.
diff --git a/src/v2/guide/components-props.md b/src/v2/guide/components-props.md
new file mode 100644
index 0000000000..0bd1f71139
--- /dev/null
+++ b/src/v2/guide/components-props.md
@@ -0,0 +1,314 @@
+---
+title: Props
+type: guide
+order: 102
+---
+
+> This page assumes you've already read the [Components Basics](components.html). Read that first if you are new to components.
+
+## Prop Casing (camelCase vs kebab-case)
+
+HTML attribute names are case-insensitive, so browsers will interpret any uppercase characters as lowercase. That means when you're using in-DOM templates, camelCased prop names need to use their kebab-cased (hyphen-delimited) equivalents:
+
+``` js
+Vue.component('blog-post', {
+ // camelCase in JavaScript
+ props: ['postTitle'],
+ template: '{{ postTitle }} '
+})
+```
+
+``` html
+
+
+
+
+
+```
+
+### Passing an Array
+
+```html
+
+
+Note that objects and arrays in JavaScript are passed by reference, so if the prop is an array or object, mutating the object or array itself inside the child component **will** affect parent state.
+
+## Prop Validation
+
+Components can specify requirements for its props. If a requirement isn't met, Vue will warn you in the browser's JavaScript console. This is especially useful when developing a component that's intended to be used by others.
+
+To specify prop validations, you case provide an object with validation requirements to the value of `props`, instead of an array of strings. For example:
+
+``` js
+Vue.component('my-component', {
+ props: {
+ // Basic type check (`null` matches any type)
+ propA: Number,
+ // Multiple possible types
+ propB: [String, Number],
+ // Required string
+ propC: {
+ type: String,
+ required: true
+ },
+ // Number with a default value
+ propD: {
+ type: Number,
+ default: 100
+ },
+ // Object with a default value
+ propE: {
+ type: Object,
+ // Object or array defaults must be returned from
+ // a factory function
+ default: function () {
+ return { message: 'hello' }
+ }
+ },
+ // Custom validator function
+ propF: {
+ validator: function (value) {
+ // The value must match one of these strings
+ return ['success', 'warning', 'danger'].indexOf(value) !== -1
+ }
+ }
+ }
+})
+```
+
+When prop validation fails, Vue will produce a console warning (if using the development build).
+
+Note that props are validated **before** a component instance is created, so instance properties (e.g. `data`, `computed`, etc) will not be available inside `default` or `validator` functions.
+
+### Type Checks
+
+The `type` can be one of the following native constructors:
+
+- String
+- Number
+- Boolean
+- Function
+- Object
+- Array
+- Symbol
+
+In addition, `type` can also be a custom constructor function and the assertion will be made with an `instanceof` check. For example, given the following constructor function exists:
+
+```js
+function Person (firstName, lastName) {
+ this.firstName = firstName
+ this.lastName = lastName
+}
+```
+
+You could use:
+
+```js
+Vue.component('blog-post', {
+ props: {
+ author: Person
+ }
+})
+```
+
+to validate that the value of the `author` prop was created with `new Person`.
+
+## Non-Prop Attributes
+
+A non-prop attribute is an attribute that is passed to a component, but does not have a corresponding prop defined.
+
+While explicitly defined props are preferred for passing information to a child component, authors of component libraries can't always foresee the contexts in which their components might be used. That's why components can accept arbitrary attributes, which are added to the component's root element.
+
+For example, imagine we're using a 3rd-party `bootstrap-date-input` component with a Bootstrap plugin that requires a `data-date-picker` attribute on the `input`. We can add this attribute to our component instance:
+
+``` html
+
+ {{ label }}
+
+ `
+})
+```
+
+This pattern allows you to use base components more like raw HTML elements, without having to care about which element is actually at its root:
+
+```html
+`.
+
+#### With PascalCase
+
+```js
+Vue.component('MyComponentName', { /* ... */ })
+```
+
+When defining a component with PascalCase, you can use either case when referencing its custom element. That means both `` and `` are acceptable. Note, however, that only kebab-case names are valid directly in the DOM (i.e. non-string templates).
+
+## Global Registration
+
+So far, we've only created components using `Vue.component`:
+
+```js
+Vue.component('my-component-name', {
+ // ... options ...
+})
+```
+
+These components are **globally registered**. That means they can be used in the template of any root Vue instance (`new Vue`) created after registration. For example:
+
+```js
+Vue.component('component-a', { /* ... */ })
+Vue.component('component-b', { /* ... */ })
+Vue.component('component-c', { /* ... */ })
+
+new Vue({ el: '#app' })
+```
+
+```html
+
+
+```
+
+This even applies to all subcomponents, meaning all three of these components will also be available _inside each other_.
+
+## Local Registration
+
+Global registration often isn't ideal. For example, if you're using a build system like Webpack, globally registering all components means that even if you stop using a component, it could still be included in your final build. This unnecessarily increases the amount of JavaScript your users have to download.
+
+In these cases, you can define your components as plain JavaScript objects:
+
+```js
+var ComponentA = { /* ... */ }
+var ComponentB = { /* ... */ }
+var ComponentC = { /* ... */ }
+```
+
+Then define the components you'd like to use in a `components` option:
+
+```js
+new Vue({
+ el: '#app'
+ components: {
+ 'component-a': ComponentA,
+ 'component-b': ComponentB
+ }
+})
+```
+
+For each property in the `components` object, the key will be the name of the custom element, while the value will contain the options object for the component.
+
+Note that **locally registered components are _not_ also available in subcomponents**. For example, if you wanted `ComponentA` to be available in `ComponentB`, you'd have to use:
+
+```js
+var ComponentA = { /* ... */ }
+
+var ComponentB = {
+ components: {
+ 'component-a': ComponentA
+ },
+ // ...
+}
+```
+
+Or if you're using ES2015 modules, such as through Babel and Webpack, that might look more like:
+
+```js
+import ComponentA from './ComponentA.vue'
+
+export default {
+ components: {
+ ComponentA
+ },
+ // ...
+}
+```
+
+Note that in ES2015+, placing a variable name like `ComponentA` inside an object is shorthand for `ComponentA: ComponentA`, meaning the name of the variable is both:
+
+- the custom element name to use in the template, and
+- the name of the variable containing the component options
+
+## Module Systems
+
+If you're not using a module system with `import`/`require`, you can probably skip this section for now. If you are, we have some special instructions and tips just for you.
+
+### Local Registration in a Module System
+
+If you're still here, then it's likely you're using a module system, such as with Babel and Webpack. In these cases, we recommend creating a `components`, with each component in its own file.
+
+Then you'll need to import each component you'd like to use, before you locally register it. For example, in a hypothetical `CompononentB.js` or `ComponentB.vue` file:
+
+```js
+import ComponentA from './ComponentA'
+import ComponentC from './ComponentC'
+
+export default {
+ components: {
+ ComponentA,
+ ComponentC
+ },
+ // ...
+}
+```
+
+Now both `ComponentA` and `ComponentC` can be used inside `ComponentB`'s template.
+
+### Automatic Global Registration of Base Components
+
+Many of your components will be relatively generic, possibly only wrapping an an element like an input or a button. We sometimes refer to these as [base components](../style-guide/#Base-component-names-strongly-recommended) and they tend to be used very frequently across your components.
+
+The result is that many components may include long lists of base components:
+
+```js
+import BaseButton from './BaseButton.vue'
+import BaseIcon from './BaseIcon.vue'
+import BaseInput from './BaseInput.vue'
+
+export default {
+ components: {
+ BaseButton,
+ BaseIcon,
+ BaseInput
+ }
+}
+```
+
+Just to support relatively little markup in a template:
+
+```html
+
+
+```
+
+Fortunately, if you're using Webpack (or [Vue CLI 3+](https://github.com/vuejs/vue-cli), which uses Webpack internally), you can use `require.context` to globally register only these very common base components. Here's an example of the code you might use to globally import base components in your app's entry file (e.g. `src/main.js`):
+
+```js
+import Vue from 'vue'
+import upperFirst from 'lodash/upperFirst'
+import camelCase from 'lodash/camelCase'
+
+const requireComponent = require.context(
+ // The relative path of the components folder
+ './components',
+ // Whether or not to look in subfolders
+ false,
+ // The regular expression used to match base component filenames
+ /Base[A-Z]\w+\.(vue|js)$/
+)
+
+requireComponent.keys().forEach(fileName => {
+ // Get component config
+ const componentConfig = requireComponent(fileName)
+
+ // Get PascalCase name of component
+ const componentName = upperFirst(
+ camelCase(
+ // Strip the leading `'./` and extension from the filename
+ fileName.replace(/^\.\/(.*)\.\w+$/, '$1')
+ )
+ )
+
+ // Register component globally
+ Vue.component(
+ componentName,
+ // Look for the component options on `.default`, which will
+ // exist if the component was exported with `export default`,
+ // otherwise fall back to module's root.
+ componentConfig.default || componentConfig
+ )
+})
+```
+
+Remember that **global registration must take place before the root Vue instance is created (with `new Vue`)**. [Here's an example](https://github.com/chrisvfritz/vue-enterprise-boilerplate/blob/master/src/components/_globals.js) of this pattern in a real project context.
diff --git a/src/v2/guide/components-slots.md b/src/v2/guide/components-slots.md
new file mode 100644
index 0000000000..f90cf8e6ef
--- /dev/null
+++ b/src/v2/guide/components-slots.md
@@ -0,0 +1,229 @@
+---
+title: Slots
+type: guide
+order: 104
+---
+
+> This page assumes you've already read the [Components Basics](components.html). Read that first if you are new to components.
+
+## Slot Content
+
+Vue implements a content distribution API that's modeled after the current [Web Components spec draft](https://github.com/w3c/webcomponents/blob/gh-pages/proposals/Slots-Proposal.md), using the `` element to serve as distribution outlets for content.
+
+This allows you to compose components like this:
+
+``` html
+
+ Your Profile
+
+```
+
+Then in the template for ``, you might have:
+
+``` html
+
+
+```
+
+When the component renders, the `` element will be replaced by "Your Profile". Slots can contain any template code, including HTML:
+
+``` html
+
+
+
+```
+
+Or even other components:
+
+``` html
+
+
+
+```
+
+If `` did **not** contain a `` element, any content passed to it would simply be discarded.
+
+## Named Slots
+
+There are times when it's useful to have multiple slots. For example, in a hypothetical `base-layout` component with the following template:
+
+``` html
+
+
+
+
+
+
+
+```
+
+For these cases, the `` element has a special attribute, `name`, which can be used to define additional slots:
+
+``` html
+
+
+
+
+
+
+```
+
+To provide content to named slots, we can use the `slot` attribute on a `` element in the parent:
+
+```html
+
+
+ Here might be a page title
+
+
+ A paragraph for the main content.
+ And another one.
+
+
+ Here's some contact info
+
+
+```
+
+Or, the `slot` attribute can also be used directly on a normal element:
+
+``` html
+
+ Here might be a page title
+
+ A paragraph for the main content.
+ And another one.
+
+ Here's some contact info
+
+```
+
+There can still be one unnamed slot, which is the **default slot** that serves as a catch-all outlet for any unmatched content. In both examples above, the rendered HTML would be:
+
+``` html
+
+
+ Here might be a page title
+
+
+ A paragraph for the main content.
+ And another one.
+
+
+ Here's some contact info
+
+
` component might want the content of the button to be "Submit" by default, but also allow users to override with "Save", "Upload", or anything else.
+
+To achieve this, specify the default content in between the `` tags.
+
+```html
+
+ Submit
+
+```
+
+If the slot is provided content by the parent, it will replace the default content.
+
+## Compilation Scope
+
+When you want to use data inside a slot, such as in:
+
+``` html
+
+ Logged in as {{ user.name }}
+
+```
+
+That slot has access to the same instance properties (i.e. the same "scope") as the rest of the template. The slot does **not** have access to ``'s scope. For example, trying to access `url` would not work. As a rule, remember that:
+
+> Everything in the parent template is compiled in parent scope; everything in the child template is compiled in the child scope.
+
+## Scoped Slots
+
+> New in 2.1.0+
+
+Sometimes you'll want to provide a component with a reusable slot that can access data from the child component. For example, a simple `` component may contain the following in its template:
+
+```html
+
+```
+
+But in some parts of our app, we want the individual todo items to render something different than just the `todo.text`. This is where scoped slots come in.
+
+To make the feature possible, all we have to do is wrap the todo item content in a `` element, then pass the slot any data relevant to its context: in this case, the `todo` object:
+
+```html
+
+
+
+
+
+
+ {{ todo.text }}
+
+
+
+```
+
+Now when we use the `` component, we can optionally define an alternative `` for todo items, but with access to data from the child via the `slot-scope` attribute:
+
+```html
+
+
+
+
+
+ ✓
+ {{ slotProps.todo.text }}
+
+
+```
+
+> In 2.5.0+, `slot-scope` is no longer limited to the `` element, but can instead be used on any element or component in the slot.
+
+### Destructuring `slot-scope`
+
+The value of `slot-scope` can actually accept any valid JavaScript expression that can appear in the argument position of a function definition. This means in supported environments ([single-file components](single-file-components.html) or [modern browsers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Browser_compatibility)) you can also use [ES2015 destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Object_destructuring) in the expression, like so:
+
+```html
+
+
+ ✓
+ {{ todo.text }}
+
+
+```
+
+This is a great way to make scoped slots a little cleaner.
diff --git a/src/v2/guide/components.md b/src/v2/guide/components.md
index 8db71229a4..f46db89e24 100644
--- a/src/v2/guide/components.md
+++ b/src/v2/guide/components.md
@@ -1,1481 +1,595 @@
---
-title: Components
+title: Components Basics
type: guide
order: 11
---
-## What are Components?
+## Base Example
-Components are one of the most powerful features of Vue. They help you extend basic HTML elements to encapsulate reusable code. At a high level, components are custom elements that Vue's compiler attaches behavior to. In some cases, they may also appear as a native HTML element extended with the special `is` attribute.
-
-All Vue components are also Vue instances, and so accept the same options object (except for a few root-specific options) and provide the same lifecycle hooks.
-
-## Using Components
-
-### Global Registration
-
-We've learned in the previous sections that we can create a new Vue instance with:
+Here's an example of a Vue component:
``` js
-new Vue({
- el: '#some-element',
- // options
+// Define a new component called button-counter
+Vue.component('button-counter', {
+ data: function () {
+ return {
+ count: 0
+ }
+ },
+ template: 'You clicked me {{ count }} times. '
})
```
-To register a global component, you can use `Vue.component(tagName, options)`. For example:
+Components are reusable Vue instances with a name: in this case, ``. We can use this component as a custom element inside a root Vue instance created with `new Vue`:
-``` js
-Vue.component('my-component', {
- // options
-})
+```html
+
+
```
-Note that Vue does not enforce the [W3C rules](https://www.w3.org/TR/custom-elements/#concepts) for custom tag names (all-lowercase, must contain a hyphen) though following this convention is considered good practice.
-
-Once registered, a component can be used in an instance's template as a custom element, `
-
+```js
+new Vue({ el: '#components-demo' })
```
-``` js
-// register
-Vue.component('my-component', {
- template: 'A custom component!
'
+{% raw %}
+
+
+
+{% endraw %}
-// create a root instance
-new Vue({
- el: '#example'
-})
-```
+Since components are reusable Vue instances, they accept the same options as `new Vue`, such as `data`, `computed`, `watch`, `methods`, and lifecycle hooks. The only exceptions are a few root-specific options like `el`.
-Which will render:
+## Reusing Components
-``` html
-
-
A custom component!
+Components can be reused as many times as you want:
+
+```html
+
+
```
{% raw %}
-
-
+
+
{% endraw %}
-### Local Registration
+Notice that when clicking on the buttons, each one maintains its own, separate `count`. That's because each time you use a component, a new **instance** of it is created.
-You don't have to register every component globally. You can make a component available only in the scope of another instance/component by registering it with the `components` instance option:
+### `data` Must Be a Function
-``` js
-var Child = {
- template: '
A custom component!
'
+When we defined the `
` component, you may have noticed that `data` wasn't directly provided an object, like this:
+
+```js
+data: {
+ count: 0
}
+```
-new Vue({
- // ...
- components: {
- // will only be available in parent's template
- 'my-component': Child
+Instead, **a component's `data` option must be a function**, so that each instance can maintain an independent copy of the returned data object:
+
+```js
+data: function () {
+ return {
+ count: 0
}
-})
+}
```
-The same encapsulation applies for other registerable Vue features, such as directives.
+If Vue didn't have this rule, clicking on one button would affect the data of _all other instances_, like below:
+
+{% raw %}
+
+
+
+{% endraw %}
-### DOM Template Parsing Caveats
+## Organizing Components
-When using the DOM as your template (e.g. using the `el` option to mount an element with existing content), you will be subject to some restrictions that are inherent to how HTML works, because Vue can only retrieve the template content **after** the browser has parsed and normalized it. Most notably, some elements such as ``, ``, `` and `` have restrictions on what elements can appear inside them, and some elements such as `` can only appear inside certain other elements.
+It's common for an app to be organized into a tree of nested components:
-This will lead to issues when using custom components with elements that have such restrictions, for example:
+
-``` html
-
-```
+For example, you might have components for a header, sidebar, and content area, each typically containing other components for navigation links, blog posts, etc.
-The custom component `` will be hoisted out as invalid content, thus causing errors in the eventual rendered output. A workaround is to use the `is` special attribute:
+To use these components in templates, they must be registered so that Vue knows about them. There are two types of component registration: **global** and **local**. So far, we've only registered components globally, using `Vue.component`:
-``` html
-
+```js
+Vue.component('my-component-name', {
+ // ... options ...
+})
```
-**It should be noted that these limitations do not apply if you are using string templates from one of the following sources**:
+Globally registered components can be used in the template of any root Vue instance (`new Vue`) created afterwards -- and even inside all subcomponents of that Vue instance's component tree.
-- `
{% endraw %}
-Since all three component instances share the same `data` object, incrementing one counter increments them all! Ouch. Let's fix this by instead returning a fresh data object:
+In a typical app, however, you'll likely have an array of posts in `data`:
-``` js
-data: function () {
- return {
- counter: 0
+```js
+new Vue({
+ el: '#blog-post-demo',
+ data: {
+ posts: [
+ { id: 1, title: 'My journey with Vue' },
+ { id: 2, title: 'Blogging with Vue' },
+ { id: 3, title: 'Why Vue is so fun' },
+ ]
}
-}
+})
```
-Now all our counters each have their own internal state:
+Then want to render a component for each one:
-{% raw %}
-
-
-
-{% endraw %}
+```html
+
-
+When building out a `` component, your template will eventually contain more than just the title:
-## Props
+```html
+{{ post.title }}
+```
-### Passing Data with Props
+At the very least, you'll want to include the post's content:
-Every component instance has its own **isolated scope**. This means you cannot (and should not) directly reference parent data in a child component's template. Data can be passed down to child components using **props**.
+```html
+{{ post.title }}
+
+```
-A prop is a custom attribute for passing information from parent components. A child component needs to explicitly declare the props it expects to receive using the [`props` option](../api/#props):
+If you try this in your template however, Vue will show an error, explaining that **every component must have a single root element**. You can fix this error by wrapping the template in a parent element, such as:
-``` js
-Vue.component('child', {
- // declare the props
- props: ['message'],
- // like data, the prop can be used inside templates and
- // is also made available in the vm as this.message
- template: '{{ message }} '
-})
+```html
+
```
-Then we can pass a plain string to it like so:
+## Sending Messages to Parents with Events
-``` html
-` component, some features may require communicating back up to the parent. For example, we may decide to include an accessibility feature to enlarge the text of blog posts, while leaving the rest of the page its default size:
-Result:
+In the parent, we can support this feature by adding a `postFontSize` data property:
-{% raw %}
-
-
-
-{% endraw %}
-
-### camelCase vs. kebab-case
+```
-HTML attributes are case-insensitive, so when using non-string templates, camelCased prop names need to use their kebab-case (hyphen-delimited) equivalents:
+Which can be used in the template to control the font size of all blog posts:
-``` js
-Vue.component('child', {
- // camelCase in JavaScript
- props: ['myMessage'],
- template: '{{ myMessage }} '
-})
+```html
+
```
-``` html
-
-
+
{{ post.title }}
+
+ Enlarge text
+
+
+
The above example and some future ones use JavaScript's [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) to make multi-line templates more readable. These are not supported by Internet Explorer (IE), so if you must support IE and are not transpiling (e.g. with Babel or TypeScript), use [newline escapes](https://css-tricks.com/snippets/javascript/multiline-string-variables-in-javascript/) instead.
-Similar to binding a normal attribute to an expression, we can also use `v-bind` for dynamically binding props to data on the parent. Whenever the data is updated in the parent, it will also flow down to the child:
+The problem is, this button doesn't do anything:
-``` html
-
-
+```html
+
+ Enlarge text
+
```
-``` js
-new Vue({
- el: '#prop-example-2',
- data: {
- parentMsg: 'Message from parent'
- }
-})
+When we click on the button, we need to communicate to the parent that it should enlarge the text of all posts. Fortunately, Vue instances provide a custom events system to solve this problem. To emit an event to the parent, we can call the built-in [**`$emit`** method](../api/#Instance-Methods-Events), passing the name of the event:
+
+```html
+
+ Enlarge text
+
```
-You can also use the shorthand syntax for `v-bind`:
+Then on our blog post, we can listen for this event with `v-on`, just as we would with a native DOM event:
-``` html
-
-
-
-
+
{% endraw %}
-If you want to pass all the properties in an object as props, you can use `v-bind` without an argument (`v-bind` instead of `v-bind:prop-name`). For example, given a `todo` object:
-
-``` js
-todo: {
- text: 'Learn Vue',
- isComplete: false
-}
-```
+### Emitting a Value With an Event
-Then:
+It's sometimes useful to emit a specific value with an event. For example, we may want the `
` component to be in charge of how much to enlarge the text by. In those cases, we can use `$emit`'s 2nd parameter to provide this value:
-``` html
-
+ Enlarge text
+
```
-Will be equivalent to:
+Then when we listen to the event in the parent, we can access the emitted event's value with `$event`:
-``` html
-Note that objects and arrays in JavaScript are passed by reference, so if the prop is an array or object, mutating the object or array itself inside the child **will** affect parent state.
+``` html
+
+ Something bad happened.
+
```
-And the `data-3d-date-picker="true"` attribute will automatically be added to the root element of `bs-date-input`.
+Which might render something like:
-### Replacing/Merging with Existing Attributes
+{% raw %}
+
+
+ Something bad happened.
+
+
` element:
-``` html
-
+ Error!
+
+ `
+})
```
-To specify a theme for our date picker plugin, we might need to add a specific class, like this:
+As you'll see above, we just add the slot where we want it to go -- and that's it. We're done!
-``` html
-
+
+ {{ tab }}
+
+
+
+
+{% endraw %}
-## Custom Events
+The above is made possible by Vue's `` element with the `is` special attribute:
-We have learned that the parent can pass data down to the child using props, but how do we communicate back to the parent when something happens? This is where Vue's custom event system comes in.
+```html
+
+Note that Vue's event system is different from the browser's [EventTarget API](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget). Though they work similarly, `$on` and `$emit` are __not__ aliases for `addEventListener` and `dispatchEvent`.
+That's all you need to know about dynamic components for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Dynamic & Async Components](components-dynamic-async.html).
-In addition, a parent component can listen to the events emitted from a child component using `v-on` directly in the template where the child component is used.
+## DOM Template Parsing Caveats
-You cannot use `$on` to listen to events emitted by children. You must use `v-on` directly in the template, as in the example below.
+Some HTML elements, such as ``, ``, `` and `` have restrictions on what elements can appear inside them, and some elements such as ``, ``, and `` can only appear inside certain other elements.
-Here's an example:
+This will lead to issues when using components with elements that have such restrictions. For example:
``` html
-
+
```
-``` js
-Vue.component('button-counter', {
- template: '{{ counter }} ',
- data: function () {
- return {
- counter: 0
- }
- },
- methods: {
- incrementCounter: function () {
- this.counter += 1
- this.$emit('increment')
- }
- },
-})
+The custom component `` will be hoisted out as invalid content, causing errors in the eventual rendered output. Fortunately, the `is` special attribute offers a workaround:
-new Vue({
- el: '#counter-event-example',
- data: {
- total: 0
- },
- methods: {
- incrementTotal: function () {
- this.total += 1
- }
- }
-})
+``` html
+
```
-{% raw %}
-
-
-{% endraw %}
-
-In this example, it's important to note that the child component is still completely decoupled from what happens outside of it. All it does is report information about its own activity, just in case a parent component might care.
-
-
-Here's an example on how to use payload data:
-
-``` html
-
-```
-
-``` js
-Vue.component('button-message', {
- template: `
- Send
-
`,
- data: function () {
- return {
- message: 'test message'
- }
- },
- methods: {
- handleSendMessage: function () {
- this.$emit('message', { message: this.message })
- }
- }
-})
-
-new Vue({
- el: '#message-event-example',
- data: {
- messages: []
- },
- methods: {
- handleMessage: function (payload) {
- this.messages.push(payload.message)
- }
- }
-})
-```
-
-{% raw %}
-
-
-{% endraw %}
-
-In this second example, it's important to note that the child component is still completely decoupled from what happens outside of it. All it does is report information about its own activity including a payload data into event emitter, just in case a parent component might care.
-
-### Binding Native Events to Components
-
-There may be times when you want to listen for a native event on the root element of a component. In these cases, you can use the `.native` modifier for `v-on`. For example:
-
-``` html
-
-
-```
-
-Note that you still have to declare the `checked` prop explicitly.
-
-### Non Parent-Child Communication
-
-Sometimes two components may need to communicate with one-another but they are not parent/child to each other. In simple scenarios, you can use an empty Vue instance as a central event bus:
-
-``` js
-var bus = new Vue()
-```
-``` js
-// in component A's method
-bus.$emit('id-selected', 1)
-```
-``` js
-// in component B's created hook
-bus.$on('id-selected', function (id) {
- // ...
-})
-```
-
-In more complex cases, you should consider employing a dedicated [state-management pattern](state-management.html).
-
-## Content Distribution with Slots
-
-When using components, it is often desired to compose them like this:
-
-``` html
-
-
-```
-
-There are two things to note here:
-
-1. The `` component does not know what content it will receive. It is decided by the component using ``.
-
-2. The `` component very likely has its own template.
-
-To make the composition work, we need a way to interweave the parent "content" and the component's own template. This is a process called **content distribution** (or "transclusion" if you are familiar with Angular). Vue.js implements a content distribution API that is modeled after the current [Web Components spec draft](https://github.com/w3c/webcomponents/blob/gh-pages/proposals/Slots-Proposal.md), using the special `` element to serve as distribution outlets for the original content.
-
-### Compilation Scope
-
-Before we dig into the API, let's first clarify which scope the contents are compiled in. Imagine a template like this:
-
-``` html
-
- {{ message }}
-
-```
-
-Should the `message` be bound to the parent's data or the child data? The answer is the parent. A simple rule of thumb for component scope is:
-
-> Everything in the parent template is compiled in parent scope; everything in the child template is compiled in child scope.
-
-A common mistake is trying to bind a directive to a child property/method in the parent template:
-
-``` html
-
-Child
',
- data: function () {
- return {
- someChildProperty: true
- }
- }
-})
-```
-
-Similarly, distributed content will be compiled in the parent scope.
-
-### Single Slot
-
-Parent content will be **discarded** unless the child component template contains at least one `` outlet. When there is only one slot with no attributes, the entire content fragment will be inserted at its position in the DOM, replacing the slot itself.
-
-Anything originally inside the `` tags is considered **fallback content**. Fallback content is compiled in the child scope and will only be displayed if the hosting element is empty and has no content to be inserted.
-
-Suppose we have a component called `my-component` with the following template:
-
-``` html
-
-
I'm the child title
-
- This will only be displayed if there is no content
- to be distributed.
-
-
-```
-
-And a parent that uses the component:
-
-``` html
-
-
I'm the parent title
-
- This is some original content
- This is some more original content
-
-
-
I'm the parent title
-
-
I'm the child title
-
This is some original content
-
This is some more original content
-
-
` elements have a special attribute, `name`, which can be used to further customize how content should be distributed. You can have multiple slots with different names. A named slot will match any element that has a corresponding `slot` attribute in the content fragment.
-
-There can still be one unnamed slot, which is the **default slot** that serves as a catch-all outlet for any unmatched content. If there is no default slot, unmatched content will be discarded.
-
-For example, suppose we have an `app-layout` component with the following template:
-
-``` html
-
-
-
-
-
-
-```
-
-Parent markup:
-
-``` html
-
- Here might be a page title
-
- A paragraph for the main content.
- And another one.
-
- Here's some contact info
-
-```
-
-The rendered result will be:
-
-``` html
-
-
- Here might be a page title
-
-
- A paragraph for the main content.
- And another one.
-
-
- Here's some contact info
-
-
-
-```
-
-In the parent, a `` element with a special attribute `slot-scope` must exist, indicating that it is a template for a scoped slot. The value of `slot-scope` will be used as the name of a temporary variable that holds the props object passed from the child:
-
-``` html
-
-
-
- hello from parent
- {{ props.text }}
-
-
-
-```
-
-If we render the above, the output will be:
-
-``` html
-
-
- hello from parent
- hello from child
-
-
` and can be used on any element or component.
-
-A more typical use case for scoped slots would be a list component that allows the component consumer to customize how each item in the list should be rendered:
-
-``` html
-
-
-
- {{ props.text }}
-
-
-```
-
-And the template for the list component:
-
-``` html
-
-```
-
-#### Destructuring
-
-`slot-scope`'s value is in fact a valid JavaScript expression that can appear in the argument position of a function signature. This means in supported environments (in single-file components or in modern browsers) you can also use ES2015 destructuring in the expression:
-
-``` html
-
- {{ text }}
-
-```
-
-## Dynamic Components
-
-You can use the same mount point and dynamically switch between multiple components using the reserved `` element and dynamically bind to its `is` attribute:
-
-``` js
-var vm = new Vue({
- el: '#example',
- data: {
- currentView: 'home'
- },
- components: {
- home: { /* ... */ },
- posts: { /* ... */ },
- archive: { /* ... */ }
- }
-})
-```
-
-``` html
-
-
-
-```
-
-If you prefer, you can also bind directly to component objects:
-
-``` js
-var Home = {
- template: 'Welcome home!
'
-}
-
-var vm = new Vue({
- el: '#example',
- data: {
- currentView: Home
- }
-})
-```
-
-### `keep-alive`
-
-If you want to keep the switched-out components in memory so that you can preserve their state or avoid re-rendering, you can wrap a dynamic component in a `` element:
-
-``` html
-
-
-
-
-
-```
-
-Check out more details on `` in the [API reference](../api/#keep-alive).
-
-## Misc
-
-### Authoring Reusable Components
-
-When authoring components, it's good to keep in mind whether you intend to reuse it somewhere else later. It's OK for one-off components to be tightly coupled, but reusable components should define a clean public interface and make no assumptions about the context it's used in.
-
-The API for a Vue component comes in three parts - props, events, and slots:
-
-- **Props** allow the external environment to pass data into the component
-
-- **Events** allow the component to trigger side effects in the external environment
-
-- **Slots** allow the external environment to compose the component with extra content.
-
-With the dedicated shorthand syntaxes for `v-bind` and `v-on`, the intents can be clearly and succinctly conveyed in the template:
-
-``` html
-
- Hello!
-
-```
-
-### Child Component Refs
-
-Despite the existence of props and events, sometimes you might still need to directly access a child component in JavaScript. To achieve this you have to assign a reference ID to the child component using `ref`. For example:
-
-``` html
-
-
-```
-
-``` js
-var parent = new Vue({ el: '#parent' })
-// access child component instance
-var child = parent.$refs.profile
-```
-
-When `ref` is used together with `v-for`, the ref you get will be an array containing the child components mirroring the data source.
-
-`$refs` are only populated after the component has been rendered, and it is not reactive. It is only meant as an escape hatch for direct child manipulation - you should avoid using `$refs` in templates or computed properties.
-
-### Async Components
-
-In large applications, we may need to divide the app into smaller chunks and only load a component from the server when it's actually needed. To make that easier, Vue allows you to define your component as a factory function that asynchronously resolves your component definition. Vue will only trigger the factory function when the component actually needs to be rendered and will cache the result for future re-renders. For example:
-
-``` js
-Vue.component('async-example', function (resolve, reject) {
- setTimeout(function () {
- // Pass the component definition to the resolve callback
- resolve({
- template: 'I am async!
'
- })
- }, 1000)
-})
-```
-
-The factory function receives a `resolve` callback, which should be called when you have retrieved your component definition from the server. You can also call `reject(reason)` to indicate the load has failed. The `setTimeout` here is for demonstration; how to retrieve the component is up to you. One recommended approach is to use async components together with [Webpack's code-splitting feature](https://webpack.js.org/guides/code-splitting/):
-
-``` js
-Vue.component('async-webpack-example', function (resolve) {
- // This special require syntax will instruct Webpack to
- // automatically split your built code into bundles which
- // are loaded over Ajax requests.
- require(['./my-async-component'], resolve)
-})
-```
-
-You can also return a `Promise` in the factory function, so with Webpack 2 + ES2015 syntax you can do:
-
-``` js
-Vue.component(
- 'async-webpack-example',
- // The `import` function returns a `Promise`.
- () => import('./my-async-component')
-)
-```
-
-When using [local registration](components.html#Local-Registration), you can also directly provide a function that returns a `Promise`:
-
-``` js
-new Vue({
- // ...
- components: {
- 'my-component': () => import('./my-async-component')
- }
-})
-```
-
-If you're a Browserify user that would like to use async components, its creator has unfortunately [made it clear](https://github.com/substack/node-browserify/issues/58#issuecomment-21978224) that async loading "is not something that Browserify will ever support." Officially, at least. The Browserify community has found [some workarounds](https://github.com/vuejs/vuejs.org/issues/620), which may be helpful for existing and complex applications. For all other scenarios, we recommend using Webpack for built-in, first-class async support.
-
-### Advanced Async Components
-
-> New in 2.3.0+
-
-Starting in 2.3.0+ the async component factory can also return an object of the following format:
-
-``` js
-const AsyncComp = () => ({
- // The component to load. Should be a Promise
- component: import('./MyComp.vue'),
- // A component to use while the async component is loading
- loading: LoadingComp,
- // A component to use if the load fails
- error: ErrorComp,
- // Delay before showing the loading component. Default: 200ms.
- delay: 200,
- // The error component will be displayed if a timeout is
- // provided and exceeded. Default: Infinity.
- timeout: 3000
-})
-```
-
-Note that when used as a route component in `vue-router`, these properties will be ignored because async components are resolved upfront before the route navigation happens. You also need to use `vue-router` 2.4.0+ if you wish to use the above syntax for route components.
-
-### Component Naming Conventions
-
-When registering components (or props), you can use kebab-case, camelCase, or PascalCase.
-
-``` js
-// in a component definition
-components: {
- // register using kebab-case
- 'kebab-cased-component': { /* ... */ },
- // register using camelCase
- 'camelCasedComponent': { /* ... */ },
- // register using PascalCase
- 'PascalCasedComponent': { /* ... */ }
-}
-```
-
-Within HTML templates though, you have to use the kebab-case equivalents:
-
-``` html
-
-
'
-```
-
-A component like the above will result in a "max stack size exceeded" error, so make sure recursive invocation is conditional (i.e. uses a `v-if` that will eventually be `false`).
-
-### Circular References Between Components
-
-Let's say you're building a file directory tree, like in Finder or File Explorer. You might have a `tree-folder` component with this template:
-
-``` html
-
- {{ folder.name }}
-
-```
-
-Then a `tree-folder-contents` component with this template:
-
-``` html
-
-
- {{ child.name }}
-
-
-```
-
-When you look closely, you'll see that these components will actually be each other's descendent _and_ ancestor in the render tree - a paradox! When registering components globally with `Vue.component`, this paradox is resolved for you automatically. If that's you, you can stop reading here.
-
-However, if you're requiring/importing components using a __module system__, e.g. via Webpack or Browserify, you'll get an error:
-
-```
-Failed to mount component: template or render function not defined.
-```
-
-To explain what's happening, let's call our components A and B. The module system sees that it needs A, but first A needs B, but B needs A, but A needs B, etc, etc. It's stuck in a loop, not knowing how to fully resolve either component without first resolving the other. To fix this, we need to give the module system a point at which it can say, "A needs B _eventually_, but there's no need to resolve B first."
-
-In our case, let's make that point the `tree-folder` component. We know the child that creates the paradox is the `tree-folder-contents` component, so we'll wait until the `beforeCreate` lifecycle hook to register it:
-
-``` js
-beforeCreate: function () {
- this.$options.components.TreeFolderContents = require('./tree-folder-contents.vue').default
-}
-```
-
-Problem solved!
-
-### Inline Templates
-
-When the `inline-template` special attribute is present on a child component, the component will use its inner content as its template, rather than treating it as distributed content. This allows more flexible template-authoring.
-
-``` html
-
-
-
These are compiled as the component's own template.
-
Not parent's transclusion content.
-
-```
-
-However, `inline-template` makes the scope of your templates harder to reason about. As a best practice, prefer defining templates inside the component using the `template` option or in a `template` element in a `.vue` file.
-
-### X-Templates
-
-Another way to define templates is inside of a script element with the type `text/x-template`, then referencing the template by an id. For example:
-
-``` html
-
-```
-
-``` js
-Vue.component('hello-world', {
- template: '#hello-world-template'
-})
-```
-
-These can be useful for demos with large templates or in extremely small applications, but should otherwise be avoided, because they separate templates from the rest of the component definition.
-
-### Cheap Static Components with `v-once`
-
-Rendering plain HTML elements is very fast in Vue, but sometimes you might have a component that contains **a lot** of static content. In these cases, you can ensure that it's only evaluated once and then cached by adding the `v-once` directive to the root element, like this:
-
-``` js
-Vue.component('terms-of-service', {
- template: '\
- \
-
Terms of Service \
- ... a lot of static content ...\
- \
- '
-})
-```
+Once you feel comfortable with the knowledge you've just digested, we recommend coming back to read the full guide on [Dynamic & Async Components](components-props.html), as well as the other pages in the Components In-Depth section of the sidebar.
diff --git a/themes/vue/layout/partials/toc.ejs b/themes/vue/layout/partials/toc.ejs
index 670345398f..ebe1968b32 100644
--- a/themes/vue/layout/partials/toc.ejs
+++ b/themes/vue/layout/partials/toc.ejs
@@ -5,6 +5,9 @@
<% if (fileName === 'installation') { %>
Essentials Components In-Depth Transitions & Animation