Setup

This section uses single-file component syntax for code examples

This guide assumes that you have already read the Composition API Introduction and Reactivity Fundamentals. Read that first if you are new to Composition API.

Arguments

When using the setup function, it will take two arguments:

  1. props
  2. context

Let’s dive deeper into how each argument can be used.

Props

The first argument in the setup function is the props argument. Just as you would expect in a standard component, props inside of a setup function are reactive and will be updated when new props are passed in.

  1. // MyBook.vue
  3. export default {
  4.   props: {
  5.     title: String
  6.   },
  7.   setup(props) {
  8.     console.log(props.title)
  9.   }
  10. }

WARNING

However, because props are reactive, you cannot use ES6 destructuring because it will remove props reactivity.

If you need to destructure your props, you can do this safely by utilizing the toRefs inside of the setup function.

  1. // MyBook.vue
  3. import { toRefs } from 'vue'
  5. setup(props) {
  6.     const { title } = toRefs(props)
  8.     console.log(title.value)
  9. }

Context

The second argument passed to the setup function is the context. The context is a normal JavaScript object that exposes three component properties:

  1. // MyBook.vue
  3. export default {
  4.   setup(props, context) {
  5.     // Attributes (Reactive Property)
  6.     console.log(context.attrs)
  8.     // Slots (Reactive Property)
  9.     console.log(context.slots)
  11.     // Emit Events (Method)
  12.     console.log(context.emit)
  13.   }
  14. }

Because it is a normal JavaScript object, i.e., it is not reactive, this means you can safely use ES6 destructuring on context.

  1. // MyBook.vue
  2. export default {
  3.     setup(props, { attrs, slots, emit }) {
  4.         ...
  5.     }
  6. }

As a result, similar to props, if you need to destructure either of these properties, you can utilize the toRefs method to create a similar effects.

  1. // MyBook.vue
  3. import { toRefs } from 'vue'
  5. export default {
  6.     setup(props, { attrs }) {
  7.         const { id } = toRefs(attrs)
  8.         console.log(id.value)
  9.     }
  10. )

Accessing Component Properties

When setup is executed, the component instance has not been created yet. As a result, you will only be able to access the following properties:

  • props
  • attrs
  • slots
  • emit

In other words, you will not have access to the following component options:

  • data
  • computed
  • methods

Usage with Templates

If setup returns an object, the properties on the object can be accessed in the component’s template:

  1. <!-- MyBook.vue -->
  2. <template>
  3.   <div>{{ readersNumber }} {{ book.title }}</div>
  4. </template>
  6. <script>
  7.   import { ref, reactive } from 'vue'
  9.   export default {
  10.     setup() {
  11.       const readersNumber = ref(0)
  12.       const book = reactive({ title: 'Vue 3 Guide' })
  14.       // expose to template
  15.       return {
  16.         readersNumber,
  17.         book
  18.       }
  19.     }
  20.   }
  21. </script>

Note that refs returned from setup are automatically unwrapped when accessed in the template so you shouldn’t use .value in templates.

Usage with Render Functions

setup can also return a render function which can directly make use of the reactive state declared in the same scope:

  1. // MyBook.vue
  3. import { h, ref, reactive } from 'vue'
  5. export default {
  6.   setup() {
  7.     const readersNumber = ref(0)
  8.     const book = reactive({ title: 'Vue 3 Guide' })
  9.     // Please note that we need to explicitly expose ref value here
  10.     return () => h('div', [readersNumber.value, book.title])
  11.   }
  12. }

Usage of this

Inside setup(), this won’t be a reference to Vue instance Since setup() is called before other component options are resolved, this inside setup() will behave quite differently from this in other options. This might cause confusions when using setup() along other Options API.