- The Vue Instance
- Template Syntax
- Computed Properties and Watchers
- Class and Style Bindings
- Conditional Rendering
- List Rendering
- Event Handling
- Form Input Bindings
- Components Basics
- Component Registration
- Custom Events
- Dynamic & Async Components
- Handling Edge Cases
Transitions & Animation
- Enter/Leave & List Transitions
- State Transitions
Reusability & Composition
- Custom Directives
- Render Functions & JSX
- Single File Components
- TypeScript Support
- Production Deployment
- State Management
- Server-Side Rendering
- Reactivity in Depth
- Migration from Vue 1.x
- Migration from Vue Router 0.7.x
- Migration from Vuex 0.6.x to 1.0
- Comparison with Other Frameworks
- Join the Vue.js Community!
- Meet the Team
You’re browsing the documentation for v2.x and earlier. For v3.x, click here.
This page assumes you’ve already read the Components Basics. Read that first if you are new to components.
When registering a component, it will always be given a name. For example, in the global registration we’ve seen so far:
The component’s name is the first argument of
The name you give a component may depend on where you intend to use it. When using a component directly in the DOM (as opposed to in a string template or single-file component), we strongly recommend following the W3C rules for custom tag names (all-lowercase, must contain a hyphen). This helps you avoid conflicts with current and future HTML elements.
You can see other recommendations for component names in the Style Guide.
You have two options when defining component names:
When defining a component with kebab-case, you must also use kebab-case when referencing its custom element, such as in
When defining a component with PascalCase, you can use either case when referencing its custom element. That means both
<MyComponentName> are acceptable. Note, however, that only kebab-case names are valid directly in the DOM (i.e. non-string templates).
So far, we’ve only created components using
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:
This even applies to all subcomponents, meaning all three of these components will also be available inside each other.
Then define the components you’d like to use in a
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:
Or if you’re using ES2015 modules, such as through Babel and Webpack, that might look more like:
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
If you’re not using a module system with
require, you can probably skip this section for now. If you are, we have some special instructions and tips just for you.
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 directory, 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
ComponentC can be used inside
Many of your components will be relatively generic, possibly only wrapping an element like an input or a button. We sometimes refer to these as base components and they tend to be used very frequently across your components.
The result is that many components may include long lists of base components:
Just to support relatively little markup in a template:
Fortunately, if you’re using Webpack (or Vue CLI 3+, 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.
Remember that global registration must take place before the root Vue instance is created (with
new Vue). Here’s an example of this pattern in a real project context.