This page assumes you've already read the Components Basics. Read that first if you are new to components.
So far, we've only seen props listed as an array of strings:
props: ['title', 'likes', 'isPublished', 'commentIds', 'author']
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:
props: { title: String, likes: Number, isPublished: Boolean, commentIds: Array, author: Object, callback: Function, contactsPromise: Promise // or any other constructor }
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 further down this page.
So far, you've seen props passed a static value, like in:
<blog-post title="My journey with Vue"></blog-post>
You've also seen props assigned dynamically with v-bind
or its shortcut, the :
character, such as in:
<!-- Dynamically assign the value of a variable --> <blog-post :title="post.title"></blog-post> <!-- Dynamically assign the value of a complex expression --> <blog-post :title="post.title + ' by ' + post.author.name"></blog-post>
In the two examples above, we happen to pass string values, but any type of value can actually be passed to a prop.
<!-- Even though `42` is static, we need v-bind to tell Vue that --> <!-- this is a JavaScript expression rather than a string. --> <blog-post :likes="42"></blog-post> <!-- Dynamically assign to the value of a variable. --> <blog-post :likes="post.likes"></blog-post>
<!-- Including the prop with no value will imply `true`. --> <!-- If you don't set is-published's type to Boolean in props, it will be an empty string instead of "true" value. --> <blog-post is-published></blog-post> <!-- Even though `false` is static, we need v-bind to tell Vue that --> <!-- this is a JavaScript expression rather than a string. --> <blog-post :is-published="false"></blog-post> <!-- Dynamically assign to the value of a variable. --> <blog-post :is-published="post.isPublished"></blog-post>
<!-- Even though the array is static, we need v-bind to tell Vue that --> <!-- this is a JavaScript expression rather than a string. --> <blog-post :comment-ids="[234, 266, 273]"></blog-post> <!-- Dynamically assign to the value of a variable. --> <blog-post :comment-ids="post.commentIds"></blog-post>
<!-- Even though the object is static, we need v-bind to tell Vue that --> <!-- this is a JavaScript expression rather than a string. --> <blog-post :author="{ name: 'Veronica', company: 'Veridian Dynamics' }" ></blog-post> <!-- Dynamically assign to the value of a variable. --> <blog-post :author="post.author"></blog-post>
If you want to pass all the properties of an object as props, you can use v-bind
without an argument (v-bind
instead of :prop-name
). For example, given a post
object:
post: { id: 1, title: 'My Journey with Vue' }
The following template:
<blog-post v-bind="post"></blog-post>
Will be equivalent to:
<blog-post v-bind:id="post.id" v-bind:title="post.title"></blog-post>
All props form a one-way-down binding between the child property and the parent one: when the parent property updates, it will flow down to the child, but not the other way around. This prevents child components from accidentally mutating the parent's state, which can make your app's data flow harder to understand.
In addition, every time the parent component is updated, all props in the child component will be refreshed with the latest value. This means you should not attempt to mutate a prop inside a child component. If you do, Vue will warn you in the console.
There are usually two cases where it's tempting to mutate a prop:
props: ['initialCounter'], data() { return { counter: this.initialCounter } }
props: ['size'], computed: { normalizedSize() { return this.size.trim().toLowerCase() } }
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 the parent state and Vue is unable to warn you against this. As a general rule, you should avoid mutating any prop, including objects and arrays as doing so ignores one-way data binding and may cause undesired results.
Components can specify requirements for their 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.
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:
app.component('my-component', { props: { // Basic type check (`null` and `undefined` values will pass any type validation) 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() { return { message: 'hello' } } }, // Custom validator function propF: { validator(value) { // The value must match one of these strings return ['success', 'warning', 'danger'].includes(value) } }, // Function with a default value propG: { type: Function, // Unlike object or array default, this is not a factory function - this is a function to serve as a default value default() { return 'Default function' } } } })
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.
The type
can be one of the following native constructors:
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:
function Person(firstName, lastName) { this.firstName = firstName this.lastName = lastName }
You could use:
app.component('blog-post', { props: { author: Person } })
to validate that the value of the author
prop was created with new Person
.
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:
const app = Vue.createApp({}) app.component('blog-post', { // camelCase in JavaScript props: ['postTitle'], template: '<h3>{{ postTitle }}</h3>' })
<!-- kebab-case in HTML --> <blog-post post-title="hello!"></blog-post>
Again, if you're using string templates, this limitation does not apply.
© 2013–present Yuxi Evan You
Licensed under the MIT License.
https://v3.vuejs.org/guide/component-props.html