Skip to content

Commit eee7fcd

Browse files
authored
Reorganize component props to introduce prop types earlier, fixes #1644 (#1646)
@BlitZz96 brought up a good point in [this issue](#1644) about users lacking the necessary background knowledge to fully understand Passing Static and Dynamic Props, at least as it relates to booleans and potentially other types in the future. To fix this, I added a new Prop Types section right before it.
1 parent 9e977cd commit eee7fcd

File tree

1 file changed

+36
-9
lines changed

1 file changed

+36
-9
lines changed

src/v2/guide/components-props.md

+36-9
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,29 @@ Vue.component('blog-post', {
2525

2626
Again, if you're using string templates, this limitation does not apply.
2727

28-
## Static and Dynamic Props
28+
## Prop Types
29+
30+
So far, we've only seen props listed as an array of strings:
31+
32+
```js
33+
props: ['title', 'likes', 'isPublished', 'commentIds', 'author']
34+
```
35+
36+
Usually though, you'll want every prop to be a specific type of value. In these cases, you can list props as an object, where the properties' names and values contain the prop names and types, respectively:
37+
38+
```js
39+
props: {
40+
title: String,
41+
likes: Number,
42+
isPublished: Boolean,
43+
commentIds: Array,
44+
author: Object
45+
}
46+
```
47+
48+
This not only documents your component, but will also warn users in the browser's JavaScript console if they pass the wrong type. You'll learn much more about [type checks and other prop validations](#Prop-Validation) further down this page.
49+
50+
## Passing Static or Dynamic Props
2951

3052
So far, you've seen props passed a static value, like in:
3153

@@ -36,7 +58,11 @@ So far, you've seen props passed a static value, like in:
3658
You've also seen props assigned dynamically with `v-bind`, such as in:
3759

3860
```html
61+
<!-- Dynamically assign the value of a variable -->
3962
<blog-post v-bind:title="post.title"></blog-post>
63+
64+
<!-- Dynamically assign the value of a complex expression -->
65+
<blog-post v-bind:title="post.title + ' by ' + post.author.name"></blog-post>
4066
```
4167

4268
In the two examples above, we happen to pass string values, but _any_ type of value can actually be passed to a prop.
@@ -56,14 +82,14 @@ In the two examples above, we happen to pass string values, but _any_ type of va
5682

5783
```html
5884
<!-- Including the prop with no value will imply `true`. -->
59-
<blog-post favorited></blog-post>
85+
<blog-post is-published></blog-post>
6086

6187
<!-- Even though `false` is static, we need v-bind to tell Vue that -->
6288
<!-- this is a JavaScript expression rather than a string. -->
63-
<base-input v-bind:favorited="false">
89+
<blog-post v-bind:is-published="false"></blog-post>
6490

6591
<!-- Dynamically assign to the value of a variable. -->
66-
<base-input v-bind:favorited="post.currentUserFavorited">
92+
<blog-post v-bind:is-published="post.isPublished"></blog-post>
6793
```
6894

6995
### Passing an Array
@@ -82,10 +108,10 @@ In the two examples above, we happen to pass string values, but _any_ type of va
82108
```html
83109
<!-- Even though the object is static, we need v-bind to tell Vue that -->
84110
<!-- this is a JavaScript expression rather than a string. -->
85-
<blog-post v-bind:comments="{ id: 1, title: 'My Journey with Vue' }"></blog-post>
111+
<blog-post v-bind:author="{ name: 'Veronica', company: 'Veridian Dynamics' }"></blog-post>
86112

87113
<!-- Dynamically assign to the value of a variable. -->
88-
<blog-post v-bind:post="post"></blog-post>
114+
<blog-post v-bind:author="post.author"></blog-post>
89115
```
90116

91117
### Passing the Properties of an Object
@@ -148,7 +174,7 @@ There are usually two cases where it's tempting to mutate a prop:
148174

149175
## Prop Validation
150176

151-
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.
177+
Components can specify requirements for its props, such as the types you've already seen. 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.
152178

153179
To specify prop validations, you can provide an object with validation requirements to the value of `props`, instead of an array of strings. For example:
154180

@@ -200,9 +226,10 @@ The `type` can be one of the following native constructors:
200226
- String
201227
- Number
202228
- Boolean
203-
- Function
204-
- Object
205229
- Array
230+
- Object
231+
- Date
232+
- Function
206233
- Symbol
207234

208235
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:

0 commit comments

Comments
 (0)