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

props
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.

// MyBook.vue

export default {
  props: {
    title: String
  },
  setup(props) {
    console.log(props.title)
  }
}

1
2
3
4
5
6
7
8
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.

// MyBook.vue

import { toRefs } from 'vue'

setup(props) {
	const { title } = toRefs(props)

	console.log(title.value)
}

1
2
3
4
5
6
7
8
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:

// MyBook.vue

export default {
  setup(props, context) {
    // Attributes (Reactive Property)
    console.log(context.attrs)

    // Slots (Reactive Property)
    console.log(context.slots)

    // Emit Events (Method)
    console.log(context.emit)
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
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.

// MyBook.vue
export default {
	setup(props, { attrs, slots, emit }) {
		...
	}
}

1
2
3
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.

// MyBook.vue

import { toRefs } from 'vue'

export default {
	setup(props, { attrs }) {
		const { id } = toRefs(attrs)
		console.log(id.value)
	}
)

1
2
3
4
5
6
7
8
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:

<!-- MyBook.vue -->
<template>
  <div>{{ readersNumber }} {{ book.title }}</div>
</template>

<script>
  import { ref, reactive } from 'vue'

  export default {
    setup() {
      const readersNumber = ref(0)
      const book = reactive({ title: 'Vue 3 Guide' })

      // expose to template
      return {
        readersNumber,
        book
      }
    }
  }
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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:

// MyBook.vue

import { h, ref, reactive } from 'vue'

export default {
  setup() {
    const readersNumber = ref(0)
    const book = reactive({ title: 'Vue 3 Guide' })
    // Please note that we need to explicitly expose ref value here
    return () => h('div', [readersNumber.value, book.title])
  }
}

1
2
3
4
5
6
7
8
9
10
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.

← Introduction Lifecycle Hooks→