Skip to content

Commit c456de9

Browse files
NataliaTepluhinaznckbencodezen
authored
Move component registration (#42)
* feat: started component basics * feat: add button-counter example * feat: moved component props * feat: reworked events on components * Added v-model on components * feat: added slots to components basic * feat: added dynamic components * fix: fixed config * fix: replaced fiddles with codesandboxes * Update src/guide/component-basics.md Co-Authored-By: Rahul Kadyan <hi@znck.me> * fix: removed new Vue reminiscenses * fix: fixed createApp reference * fix: fixed update events names * fix: fixed createApp * fix: changed modelValue to be camelCase * fix: fixed prop name * Update src/guide/component-basics.md Co-Authored-By: Rahul Kadyan <hi@znck.me> * Update src/guide/component-basics.md Co-Authored-By: Rahul Kadyan <hi@znck.me> * feat: added a note on case-insensitiveness * feat: moved component registration * Update src/guide/component-registration.md Co-Authored-By: Ben Hong <ben@bencodezen.io> * Update src/guide/component-registration.md Co-Authored-By: Ben Hong <ben@bencodezen.io> * Update src/guide/component-registration.md Co-Authored-By: Ben Hong <ben@bencodezen.io> * fix: removed global base registration recipe Co-authored-by: Rahul Kadyan <hi@znck.me> Co-authored-by: Ben Hong <ben@bencodezen.io>
1 parent 94e1724 commit c456de9

File tree

2 files changed

+185
-1
lines changed

2 files changed

+185
-1
lines changed

‎src/.vuepress/config.js

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,13 @@ module.exports = {
4040
'list',
4141
'events',
4242
'forms',
43-
'component-basics',
43+
'component-basics'
4444
]
45+
},
46+
{
47+
title: 'Components In-Depth',
48+
collapsable: true,
49+
children: ['component-registration']
4550
}
4651
]
4752
}

‎src/guide/component-registration.md

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Component Registration
2+
3+
> This page assumes you've already read the [Components Basics](component-basics.md). Read that first if you are new to components.
4+
5+
<div class="vueschool"><a href="https://vueschool.io/lessons/global-vs-local-components?friend=vuejs" target="_blank" rel="sponsored noopener" title="Free Vue.js Component Registration lesson">Watch a free video lesson on Vue School</a></div>
6+
7+
## Component Names
8+
9+
When registering a component, it will always be given a name. For example, in the global registration we've seen so far:
10+
11+
```js
12+
const app = createApp({...})
13+
14+
app.component('my-component-name', {
15+
/* ... */
16+
})
17+
```
18+
19+
The component's name is the first argument of `app.component`. In the example above, the component's name is "my-component-name".
20+
21+
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](TODO: single-file-components.html)), we strongly recommend following the [W3C rules](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) for custom tag names:
22+
23+
1. All lowercase
24+
2. Contains a hyphen (i.e., has multiple words connected with the hyphen symbol)
25+
26+
By doing so, this will help you avoid conflicts with current and future HTML elements.
27+
28+
You can see other recommendations for component names in the [Style Guide](TODO:../style-guide/#Base-component-names-strongly-recommended).
29+
30+
### Name Casing
31+
32+
When defining components in a string template or a single-file component, you have two options when defining component names:
33+
34+
#### With kebab-case
35+
36+
```js
37+
app.component('my-component-name', {
38+
/* ... */
39+
})
40+
```
41+
42+
When defining a component with kebab-case, you must also use kebab-case when referencing its custom element, such as in `<my-component-name>`.
43+
44+
#### With PascalCase
45+
46+
```js
47+
app.component('MyComponentName', {
48+
/* ... */
49+
})
50+
```
51+
52+
When defining a component with PascalCase, you can use either case when referencing its custom element. That means both `<my-component-name>` and `<MyComponentName>` are acceptable. Note, however, that only kebab-case names are valid directly in the DOM (i.e. non-string templates).
53+
54+
## Global Registration
55+
56+
So far, we've only created components using `Vue.component`:
57+
58+
```js
59+
Vue.createApp({...}).component('my-component-name', {
60+
// ... options ...
61+
})
62+
```
63+
64+
These components are **globally registered**. That means they can be used in the template of any root Vue instance created after registration. For example:
65+
66+
```js
67+
const app = Vue.createApp({})
68+
69+
app.component('component-a', {
70+
/* ... */
71+
})
72+
app.component('component-b', {
73+
/* ... */
74+
})
75+
app.component('component-c', {
76+
/* ... */
77+
})
78+
79+
app.mount('#app')
80+
```
81+
82+
```html
83+
<div id="app">
84+
<component-a></component-a>
85+
<component-b></component-b>
86+
<component-c></component-c>
87+
</div>
88+
```
89+
90+
This even applies to all subcomponents, meaning all three of these components will also be available _inside each other_.
91+
92+
## Local Registration
93+
94+
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.
95+
96+
In these cases, you can define your components as plain JavaScript objects:
97+
98+
```js
99+
const ComponentA = {
100+
/* ... */
101+
}
102+
const ComponentB = {
103+
/* ... */
104+
}
105+
const ComponentC = {
106+
/* ... */
107+
}
108+
```
109+
110+
Then define the components you'd like to use in a `components` option:
111+
112+
```js
113+
const app = Vue.createApp({
114+
components: {
115+
'component-a': ComponentA,
116+
'component-b': ComponentB
117+
}
118+
})
119+
```
120+
121+
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.
122+
123+
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:
124+
125+
```js
126+
const ComponentA = {
127+
/* ... */
128+
}
129+
130+
const ComponentB = {
131+
components: {
132+
'component-a': ComponentA
133+
}
134+
// ...
135+
}
136+
```
137+
138+
Or if you're using ES2015 modules, such as through Babel and Webpack, that might look more like:
139+
140+
```js
141+
import ComponentA from './ComponentA.vue'
142+
143+
export default {
144+
components: {
145+
ComponentA
146+
}
147+
// ...
148+
}
149+
```
150+
151+
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:
152+
153+
- the custom element name to use in the template, and
154+
- the name of the variable containing the component options
155+
156+
## Module Systems
157+
158+
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.
159+
160+
### Local Registration in a Module System
161+
162+
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.
163+
164+
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:
165+
166+
```js
167+
import ComponentA from './ComponentA'
168+
import ComponentC from './ComponentC'
169+
170+
export default {
171+
components: {
172+
ComponentA,
173+
ComponentC
174+
}
175+
// ...
176+
}
177+
```
178+
179+
Now both `ComponentA` and `ComponentC` can be used inside `ComponentB`'s template.

0 commit comments

Comments
 (0)