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 Vue.component.
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
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 Vue.component:.
These components are globally registered. That means they can be used in the template of any root Vue instance (new Vue) created after registration. This even applies to all subcomponents, meaning all three of these components will also be available inside each other.
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.
Please note: Stencil reuses DOM elements for better performance. Consider the following code:
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 import/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 ComponentB.js or ComponentB.vue file:.
Now both ComponentA and ComponentC can be used inside ComponentB‘s template. 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. Caught a mistake or want to contribute to the documentation?Edit this on GitHub!Deployed onNetlify .
When starting a new project, it’s best to familiarize yourself with the technology’s tools and features.
Step 1 — Downloading Vue CLI 3
One important tool for Vue.js development is its command line interface (CLI) known as Vue CLI 3.
The Vue CLI offers a number of useful features that enhance the Vue development experience, but the main feature is its ability to generate and pre-configure a new single-page application with the vue create command.
By the end of this tutorial, you will have a working Vue.js application running on a local Node server.
This local server uses hot module reloading via Webpack to provide immediate feedback, rendered in-browser as you work.
Along the way, you will create .vue single-file components (SFC), such as a header and a footer. All of this you can save as a solid foundation for any future Vue projects. To follow this tutorial, you will need the following:.
Node.js version 10.6.0 or greater installed on your computer. To install this on macOS or Ubuntu 18.04, follow the steps in How To Install Node.js and Create a Local Development Environment on macOS or the Installing Using a PPA section of How To Install Node.js on Ubuntu 18.04.
Step 3 — Creating a Header Component
npm or Node Package Manager is a way to download and manage other people’s code to use in your project as a dependency. Yarn, on the other hand, executes NPM commands under the hood but provides additional features like caching. It’s up to personal preference regarding which one to use.
However, it is important to note that it’s not recommended to mix commands. It’s best to be consistent with one or the other for the duration of your project. Moving forward, this tutorial will use npm commands. The following command will download the necessary Vue CLI files from the registrar, which in this case is the npm (Node Package Manager) service:.
Note: On some systems, installing an npm package globally can result in a permission error, which will interrupt the installation. Since it is a security best practice to avoid using sudo with npm install, you can instead resolve this by changing npm’s default directory.
If you encounter an EACCES error, follow the instructions at the official npm documentation. You install this globally in order to use the CLI anywhere on your machine. If you don’t install this globally, it will only work in the directory that you installed it at. In the case of the command options, i means “install” and -g is a flag to install the code globally on your computer.
To verify if Vue CLI 3 was properly installed, run the following:. You will receive the following output with a version number.