Introduction

    Reaching this far in the documentation, you should already be familiar with both the basics of Vue and .

    Creating Vue components allows us to extract repeatable parts of the interface coupled with its functionality into reusable pieces of code. This alone can get our application pretty far in terms of maintainability and flexibility. However, our collective experience has proved that this alone might not be enough, especially when your application is getting really big – think several hundreds of components. When dealing with such large applications, sharing and reusing code becomes especially important.

    Let’s imagine that in our app, we have a view to show a list of repositories of a certain user. On top of that, we want to apply search and filter capabilities. Our component handling this view could look like this:

    This component has several responsibilities:

    1. Getting repositories from a presumedly external API for that user name and refreshing it whenever the user changes
    2. Searching for repositories using a string
    3. Filtering repositories using a filters object

    Organizing logics with component’s options (data, computed, methods, watch) works in most cases. However, when our components get bigger, the list of logical concerns also grows. This can lead to components that are hard to read and understand, especially for people who didn’t write them in the first place.

    Example presenting a large component where its logical concerns are grouped by colors.

    Such fragmentation is what makes it difficult to understand and maintain a complex component. The separation of options obscures the underlying logical concerns. In addition, when working on a single logical concern, we have to constantly “jump” around option blocks for the relevant code.

    It would be much nicer if we could collocate code related to the same logical concern. And this is exactly what the Composition API enables us to do.

    Basics of Composition API

    Now that we know the why we can get to the how. To start working with the Compsition API we first need a place where we can actually use it. In a Vue component, we call this place the setup.

    The new setup component option is executed before the component is created, once the props are resolved, and serves as the entry point for composition API’s.

    WARNING

    Because the component instance is not yet created when setup is executed, there is no this inside a setup option. This means, with the exception of props, you won’t be able to access any properties declared in the component – local state, computed properties or methods.

    The setup option should be a function that accepts props and context which we will talk about . Additionally, everything that we return from setup will be exposed to the rest of our component (computed properties, methods, lifecycle hooks and so on) as well as to the component’s template.

    Let’s add setup to our component:

    1. // src/components/UserRepositories.vue
    3. export default {
    4.   components: { RepositoriesFilters, RepositoriesSortBy, RepositoriesList },
    5.   props: {
    6.     user: { type: String }
    7.   },
    8.   setup(props) {
    9.     console.log(props) // { user: '' }
    11.     return {} // anything returned here will be available for the rest of the component
    12.   }
    13.   // the "rest" of the component
    14. }

    Now let’s start with extracting the first logical concern (marked as “1” in the original snippet).

    • The list of repositories
    • The function to update the list of repositories
    • Returning both the list and the function so they are accessible by other component options
    1. // src/components/UserRepositories.vue `setup` function
    2. import { fetchUserRepositories } from '@/api/repositories'
    4. // inside our component
    5. setup (props) {
    6.   let repositories = []
    7.   const getUserRepositories = async () => {
    8.     repositories = await fetchUserRepositories(props.user)
    9.   }
    11.   return {
    12.     repositories,
    13.     getUserRepositories // functions returned behave the same as methods
    14.   }
    15. }

    This is our starting point, except it’s not working yet because our repositories variable is not reactive. This means from a user’s perspective, the repository list would remain empty. Let’s fix that!

    In Vue 3.0 we can make any variable reactive anywhere with a new ref function, like this:

    1. import { ref } from 'vue'
    3. const counter = ref(0)

    ref takes the argument and returns it wrapped within an object with a value property, which can then be used to access or mutate the value of the reactive variable:

    1. import { ref } from 'vue'
    3. const counter = ref(0)
    5. console.log(counter) // { value: 0 }
    6. console.log(counter.value) // 0
    8. counter.value++
    9. console.log(counter.value) // 1

    Wrapping values inside an object might seem unnecessary but is required to keep the behavior unified across different data types in JavaScript. That’s because in JavaScript, primitive types like Number or String are passed by value, not by reference:

    Pass by reference vs pass by value

    Having a wrapper object around any value allows us to safely pass it across our whole app without worrying about losing its reactivity somewhere along the way.

    Note

    In other words, ref creates a Reactive Reference to our value. The concept of working with References will be used often throughout the Composition API.

    Back to our example, let’s create a reactive repositories variable:

    Done! Now whenever we call getUserRepositories, repositories will be mutated and the view will be updated to reflect the change. Our component should now look like this:

    1. // src/components/UserRepositories.vue
    2. import { fetchUserRepositories } from '@/api/repositories'
    3. import { ref } from 'vue'
    5. export default {
    6.   components: { RepositoriesFilters, RepositoriesSortBy, RepositoriesList },
    7.   props: {
    8.     user: { type: String }
    9.   },
    10.   setup (props) {
    11.     const repositories = ref([])
    12.     const getUserRepositories = async () => {
    13.       repositories.value = await fetchUserRepositories(props.user)
    14.     }
    16.     return {
    17.       repositories,
    18.       getUserRepositories
    19.     }
    20.   },
    21.   data () {
    22.     return {
    23.       filters: { ... }, // 3
    24.       searchQuery: '' // 2
    25.     }
    26.   },
    27.   computed: {
    29.   },
    30.   watch: {
    31.     user: 'getUserRepositories' // 1
    32.   },
    33.   methods: {
    34.     updateFilters () { ... }, // 3
    35.   },
    36.   mounted () {
    37.     this.getUserRepositories() // 1
    38.   }
    39. }

    We have moved several pieces of our first logical concern into the setup method, nicely put close to each other. What’s left is calling getUserRepositories in the mounted hook and setting up a watcher to do that whenever the user prop changes.

    We will start with the lifecycle hook.

    To make Composition API feature-complete compared to Options API, we also need a way to register lifecycle hooks inside setup. This is possible thanks to several new functions exported from Vue. Lifecycle hooks on composition API have the same name as for Options API but are prefixed with on: i.e. mounted would look like onMounted.

    These functions accept a callback that will be executed when the hook is called by the component.

    Let’s add it to our setup function:

    1. // src/components/UserRepositories.vue `setup` function
    2. import { fetchUserRepositories } from '@/api/repositories'
    3. import { ref, onMounted } from 'vue'
    5. // in our component
    6. setup (props) {
    7.   const repositories = ref([])
    8.   const getUserRepositories = async () => {
    9.     repositories.value = await fetchUserRepositories(props.user)
    10.   }
    12.   onMounted(getUserRepositories) // on `mounted` call `getUserRepositories`
    14.   return {
    15.     repositories,
    16.     getUserRepositories
    17.   }
    18. }

    Now we need to react to the changes made to the user prop. For that we will use the standalone watch function.

    • A Reactive Reference or getter function that we want to watch
    • A callback
    • Optional configuration options

    Here’s a quick look at how it works.

    1. import { ref, watch } from 'vue'
    3. const counter = ref(0)
    4. watch(counter, (newValue, oldValue) => {
    5.   console.log('The new counter value is: ' + counter.value)
    6. })

    Whenever counter is modified, for example counter.value = 5, the watch will trigger and execute the callback (second argument) which in this case will log 'The new counter value is: 5' into our console.

    Below is the Options API equivalent:

    1. export default {
    2.   data() {
    3.     return {
    4.       counter: 0
    5.     }
    6.   },
    7.   watch: {
    8.     counter(newValue, oldValue) {
    9.       console.log('The new counter value is: ' + this.counter)
    10.     }
    11.   }
    12. }

    For more details on watch, refer to our in-depth guide.

    Let’s now apply it to our example:

    You probably have noticed the use of toRefs at the top of our setup. This is to ensure our watcher will react to changes made to the user prop.

    With those changes in place, we’ve just moved the whole first logical concern into a single place. We can now do the same with the second concern – filtering based on searchQuery, this time with a computed property.

    Similar to ref and watch, computed properties can also be created outside of a Vue component with the computed function imported from Vue. Let’s get back to our counter example:

    1. import { ref, computed } from 'vue'
    3. const counter = ref(0)
    4. const twiceTheCounter = computed(() => counter.value * 2)
    6. counter.value++
    7. console.log(counter.value) // 1
    8. console.log(twiceTheCounter.value) // 2

    Here, the computed function returns a read-only Reactive Reference to the output of the getter-like callback passed as the first argument to computed. In order to access the value of the newly-created computed variable, we need to use the .value property just like with ref.

    Let’s move our search functionality into setup:

    1. // src/components/UserRepositories.vue `setup` function
    2. import { fetchUserRepositories } from '@/api/repositories'
    3. import { ref, onMounted, watch, toRefs, computed } from 'vue'
    5. // in our component
    6. setup (props) {
    7.   // using `toRefs` to create a Reactive Reference to the `user` property of props
    8.   const { user } = toRefs(props)
    10.   const repositories = ref([])
    11.   const getUserRepositories = async () => {
    13.     repositories.value = await fetchUserRepositories(user.value)
    14.   }
    16.   onMounted(getUserRepositories)
    18.   // set a watcher on the Reactive Reference to user prop
    19.   watch(user, getUserRepositories)
    21.   const searchQuery = ref('')
    22.   const repositoriesMatchingSearchQuery = computed(() => {
    23.     return repositories.value.filter(
    24.     )
    25.   })
    27.   return {
    28.     repositories,
    29.     getUserRepositories,
    30.     searchQuery,
    31.     repositoriesMatchingSearchQuery
    32.   }
    33. }

    We could do the same for other logical concerns but you might be already asking the question – Isn’t this just moving the code to the setup option and making it extremely big? Well, that’s true. That’s why before moving on with the other responsibilities, we will first extract the above code into a standalone composition function. Let’s start with creating useUserRepositories:

    1. // src/composables/useUserRepositories.js
    3. import { fetchUserRepositories } from '@/api/repositories'
    4. import { ref, onMounted, watch, toRefs } from 'vue'
    6. export default function useUserRepositories(user) {
    7.   const repositories = ref([])
    8.   const getUserRepositories = async () => {
    9.     repositories.value = await fetchUserRepositories(user.value)
    10.   }
    12.   onMounted(getUserRepositories)
    13.   watch(user, getUserRepositories)
    15.   return {
    16.     repositories,
    17.     getUserRepositories
    18.   }
    19. }

    And then the searching functionality:

    1. // src/composables/useRepositoryNameSearch.js
    3. import { ref, onMounted, watch, toRefs } from 'vue'
    5. export default function useRepositoryNameSearch(repositories) {
    6.   const searchQuery = ref('')
    7.   const repositoriesMatchingSearchQuery = computed(() => {
    8.     return repositories.value.filter(repository => {
    9.       return repository.name.includes(searchQuery.value)
    10.     })
    11.   })
    13.   return {
    14.     searchQuery,
    15.     repositoriesMatchingSearchQuery
    16.   }
    17. }

    Now having those two functionalities in separate files, we can start using them in our component. Here’s how this can be done:

    At this point you probably already know the drill, so let’s skip to the end and migrate the leftover filtering functionality. We don’t really need to get into the implementation details as it’s not the point of this guide.

    1. // src/components/UserRepositories.vue
    2. import { toRefs } from 'vue'
    3. import useUserRepositories from '@/composables/useUserRepositories'
    4. import useRepositoryNameSearch from '@/composables/useRepositoryNameSearch'
    5. import useRepositoryFilters from '@/composables/useRepositoryFilters'
    7. export default {
    8.   components: { RepositoriesFilters, RepositoriesSortBy, RepositoriesList },
    9.   props: {
    10.     user: { type: String }
    11.   },
    12.   setup(props) {
    13.     const { user } = toRefs(props)
    15.     const { repositories, getUserRepositories } = useUserRepositories(user)
    17.     const {
    18.       searchQuery,
    19.       repositoriesMatchingSearchQuery
    20.     } = useRepositoryNameSearch(repositories)
    22.     const {
    23.       filters,
    24.       updateFilters,
    25.       filteredRepositories
    26.     } = useRepositoryFilters(repositoriesMatchingSearchQuery)
    28.     return {
    29.       // Since we don’t really care about the unfiltered repositories
    30.       // we can expose the end results under the `repositories` name
    31.       repositories: filteredRepositories,
    32.       getUserRepositories,
    33.       searchQuery,
    34.       filters,
    35.       updateFilters
    36.     }
    37. }

    And we are done!

    Keep in mind that we’ve only scratched the surface of Composition API and what it allows us to do. To learn more about it, refer to the in-depth guide.