Props

This page assumes you’ve already read the Components Basics. Read that first if you are new to components.

Prop Types

So far, we’ve only seen props listed as an array of strings:

  1. 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:

  1. props: {
  2.   title: String,
  3.   likes: Number,
  4.   isPublished: Boolean,
  5.   commentIds: Array,
  6.   author: Object,
  7.   callback: Function,
  8.   contactsPromise: Promise // or any other constructor
  9. }

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.

Passing Static or Dynamic Props

So far, you’ve seen props passed a static value, like in:

  1. <blog-post title="My journey with Vue"></blog-post>

You’ve also seen props assigned dynamically with v-bind, such as in:

  1. <!-- Dynamically assign the value of a variable -->
  2. <blog-post v-bind:title="post.title"></blog-post>
  4. <!-- Dynamically assign the value of a complex expression -->
  5. <blog-post v-bind: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.

Passing a Number

  1. <!-- Even though `42` is static, we need v-bind to tell Vue that -->
  2. <!-- this is a JavaScript expression rather than a string.       -->
  3. <blog-post v-bind:likes="42"></blog-post>
  5. <!-- Dynamically assign to the value of a variable. -->
  6. <blog-post v-bind:likes="post.likes"></blog-post>

Passing a Boolean

  1. <!-- Including the prop with no value will imply `true`. -->
  2. <blog-post is-published></blog-post>
  4. <!-- Even though `false` is static, we need v-bind to tell Vue that -->
  5. <!-- this is a JavaScript expression rather than a string.          -->
  6. <blog-post v-bind:is-published="false"></blog-post>
  8. <!-- Dynamically assign to the value of a variable. -->
  9. <blog-post v-bind:is-published="post.isPublished"></blog-post>

Passing an Array

  1. <!-- Even though the array is static, we need v-bind to tell Vue that -->
  2. <!-- this is a JavaScript expression rather than a string.            -->
  3. <blog-post v-bind:comment-ids="[234, 266, 273]"></blog-post>
  5. <!-- Dynamically assign to the value of a variable. -->
  6. <blog-post v-bind:comment-ids="post.commentIds"></blog-post>

Passing an Object

  1. <!-- Even though the object is static, we need v-bind to tell Vue that -->
  2. <!-- this is a JavaScript expression rather than a string.             -->
  3. <blog-post
  4.   v-bind:author="{
  5.     name: 'Veronica',
  6.     company: 'Veridian Dynamics'
  7.   }"
  8. ></blog-post>
  10. <!-- Dynamically assign to the value of a variable. -->
  11. <blog-post v-bind:author="post.author"></blog-post>

Passing the Properties of an Object

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 v-bind:prop-name). For example, given a post object:

  1. post: {
  2.   id: 1,
  3.   title: 'My Journey with Vue'
  4. }

The following template:

  1. <blog-post v-bind="post"></blog-post>

Will be equivalent to:

  1. <blog-post v-bind:id="post.id" v-bind:title="post.title"></blog-post>

One-Way Data Flow

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:

  1. The prop is used to pass in an initial value; the child component wants to use it as a local data property afterwards. In this case, it’s best to define a local data property that uses the prop as its initial value:
  1. props: ['initialCounter'],
  2. data() {
  3.   return {
  4.     counter: this.initialCounter
  5.   }
  6. }
  1. The prop is passed in as a raw value that needs to be transformed. In this case, it’s best to define a computed property using the prop’s value:
  1. props: ['size'],
  2. computed: {
  3.   normalizedSize: function () {
  4.     return this.size.trim().toLowerCase()
  5.   }
  6. }

Note

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 parent state.

Prop Validation

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:

  1. app.component('my-component', {
  2.   props: {
  3.     // Basic type check (`null` and `undefined` values will pass any type validation)
  4.     propA: Number,
  5.     // Multiple possible types
  6.     propB: [String, Number],
  7.     // Required string
  8.     propC: {
  9.       type: String,
  10.       required: true
  11.     },
  12.     // Number with a default value
  13.     propD: {
  14.       type: Number,
  15.       default: 100
  16.     },
  17.     // Object with a default value
  18.     propE: {
  19.       type: Object,
  20.       // Object or array defaults must be returned from
  21.       // a factory function
  22.       default: function() {
  23.         return { message: 'hello' }
  24.       }
  25.     },
  26.     // Custom validator function
  27.     propF: {
  28.       validator: function(value) {
  29.         // The value must match one of these strings
  30.         return ['success', 'warning', 'danger'].indexOf(value) !== -1
  31.       }
  32.     },
  33.     // Function with a default value
  34.     propG: {
  35.       type: Function,
  36.       // Unlike object or array default, this is not a factory function - this is a function to serve as a default value
  37.       default: function() {
  38.         return 'Default function'
  39.       }
  40.     }
  41.   }
  42. })

When prop validation fails, Vue will produce a console warning (if using the development build).

Note

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.

Type Checks

The type can be one of the following native constructors:

  • String
  • Number
  • Boolean
  • Array
  • Object
  • Date
  • Function
  • Symbol

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:

  1. function Person(firstName, lastName) {
  2.   this.firstName = firstName
  3.   this.lastName = lastName
  4. }

You could use:

  1. app.component('blog-post', {
  2.   props: {
  3.     author: Person
  4.   }
  5. })

to validate that the value of the author prop was created with new Person.

Non-Prop Attributes

A non-prop attribute is an attribute that is passed to a component, but does not have a corresponding prop defined. Common examples of this include class, style, and id attributes.

Attribute Inheritance

When a component returns a single root node, non-prop attributes will automatically be added to the root node’s attributes. For example, in the instance of a date-picker component:

  1. app.component('date-picker', {
  2.   template: `
  3.     <div class="date-picker">
  4.       <input type="datetime" />
  5.     </div>
  6.   `
  7. })

In the event we need to define the status of the date-picker component via a data-status property, it will be applied to the root node (i.e., div.date-picker).

  1. <!-- Date-picker component with a non-prop attribute -->
  2. <date-picker data-status="activated"></date-picker>
  4. <!-- Rendered date-picker component -->
  5. <div class="date-picker" data-status="activated">
  6.   <input type="datetime" />
  7. </div>

Disabling Attribute Inheritance

If you do not want a component to automatically inherit attributes, you can set inheritAttrs: false in the component’s options.

There are two common scenarios when attribute inheritance needs to be disabled:

  1. When attributes need to be applied to other elements besides the root node
  2. When a component has multiple root nodes

By setting the inheritAttrs option to false, this gives you access to the component’s $attrs property, which includes all attributes not included to component props and emits properties (e.g., class, style, v-on listeners, etc.).

Single Root Node

Using our date-picker component example from the previous section, in the event we need to apply all non-prop attributes to the input element rather than the root div element, this can be accomplished by using the v-bind shortcut.

  1. app.component('date-picker', {
  2.   inheritAttrs: false,
  3.   template: `
  4.     <div class="date-picker">
  5.       <input type="datetime" v-bind="$attrs" />
  6.     </div>
  7.   `
  8. })

With this new configuration, our data-status attribute will be applied to our input element!

  1. <!-- Date-picker component with a non-prop attribute -->
  2. <date-picker data-status="activated"></date-picker>
  4. <!-- Rendered date-picker component -->
  5. <div class="date-picker">
  6.   <input type="datetime" data-status="activated" />
  7. </div>

Multiple Root Nodes

Unlike single root node components, components with multiple root nodes do not have an automatic attribute fallthrough behavior if inheritAttrs and $attrs are not defined. A runtime warning will be issued if this is left off

  1. app.component('custom-layout', {
  2.   inheritAttrs: false,
  3.   template: `
  4.     <header>...</header>
  5.     <main v-bind="$attrs">...</main>
  6.     <footer>...</footer>
  7.   `
  8. })

Prop Casing (camelCase vs kebab-case)

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:

  1. const app = Vue.createApp({})
  3. app.component('blog-post', {
  4.   // camelCase in JavaScript
  5.   props: ['postTitle'],
  6.   template: '<h3>{{ postTitle }}</h3>'
  7. })
  1. <!-- kebab-case in HTML -->
  2. <blog-post post-title="hello!"></blog-post>

Again, if you’re using string templates, this limitation does not apply.