5e074956ee8ba1fea26e30d28c190495?s=300 avatar

5e074956ee8ba1fea26e30d28c190495?s=300

Full stack developer creating content at Auth0. I love taking a deep dive into hard-to-understand concepts and creating content that makes them easier to grasp. In my free time you can usually find me reading, hanging out with my dogs, or curling in the squat rack.

Former Developer Content Manager

Holly Guevara

Learn how to use the Vue 3 Composition API to build a project idea generator.

Vue Composition API Tutorial: Build a Project Idea Generator

Learn about the new Composition API in Vue 3 and how it compares to the Options API



The long-awaited [Vue.js 3](https://vuejs.org/) is scheduled for release in the 1st quarter of 2020. The announcement of a new API, the Composition API, resulted in some [controversy in the Vue community](https://www.reddit.com/r/vuejs/comments/c319el/vue_3_will_change_vue_in_a_big_way_current_syntax/). It has since simmered down, but what is the Composition API anyway?

Although Vue 3, in its entirety, hasn't been released yet, the Composition API is already out and ready to use. In this article, we'll take a look at why the Composition API was introduced, how it works, and how it compares to the options-based API. At the end, we'll build two versions of the same component: one with the Composition API and one with the options-based API!

![Vue 3 Composition API vs Options API](https://images.ctfassets.net/23aumh6u8s0i/4iCUUq6ilCnIyOwPWQEVaI/c6621244683eef1b975f3c54391343f6/vue-3-composition-api-vs-options)

## What is the Composition API

Just to get the obvious concern out of the way, this new API **will not break** current Vue 2.x options-based code! We can even continue to use the Options API in Vue 3. The Composition API is just an addition to the language that was created to address the limitations of the Options API used in Vue 2. We'll touch on those limitations in the next section.

For now, let's talk about *what* it is.

Evan You, the creator of Vue, has described the Composition API as a **reactive API coupled with the ability to register lifecycle hooks using globally imported functions**. This is a little hard to digest, but the main point is that the Composition API provides a different way to manage reactivity at all points in an application, without compromising organization and readability.

At the root of it, the Composition API isn't really adding anything new to the language. Instead, think about it this way: it's exposing some of the internal functions (aka, magic) that Vue already uses, allowing us to use these functions directly in components.

<include src="TweetQuote" quoteText="The Vue 3 Composition API makes Vue internal functions available for use in your Vue applications."/>

> [Adam Wathan](https://twitter.com/adamwathan) has an excellent podcast called [Full Stack Radio](http://www.fullstackradio.com/). If you're interested in learning more about the Composition API and Vue 3 in general, I'd highly recommend checking out [Episode 129: Evan You &mdash; What's Coming in Vue.js 3.0](http://www.fullstackradio.com/129), where Adam talks in-depth about the Composition API with [Evan You](https://twitter.com/youyuxi).

<AmpContent>
    <include src="TweetQuote" quoteText="New @fullstackradio is out! I talk to @youyuxi about all of the features and changes coming in Vue.js 3.0 🎉 Super deep-dive with lots of technical discussion, brace yourself! 😄"/>

</AmpContent>

<NonAmpContent>

  <blockquote class="twitter-tweet"><p lang="en" dir="ltr">🚀 New <a href="https://twitter.com/fullstackradio?ref_src=twsrc%5Etfw">@fullstackradio</a> is out!<br><br>I talk to <a href="https://twitter.com/youyuxi?ref_src=twsrc%5Etfw">@youyuxi</a> about all of the features and changes coming in Vue.js 3.0 🎉<br><br>Super deep-dive with lots of technical discussion, brace yourself! 😄<a href="https://t.co/zz9UIA96XE">https://t.co/zz9UIA96XE</a> <a href="https://t.co/cQlfyGQ5RG">pic.twitter.com/cQlfyGQ5RG</a></p>&mdash; Adam Wathan (@adamwathan) <a href="https://twitter.com/adamwathan/status/1199648232420364288?ref_src=twsrc%5Etfw">November 27, 2019</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

</NonAmpContent>

## Why the Change?

Before we jump into the comparison, let's look at some of the pain points in Vue 2 that the Composition API aims to solve.

### Better extensibility and organization

One major concern among developers was that their Vue projects became hard to manage as they grew in size and complexity.

In Vue 2.x, components are organized using options such as `data`, `mounted`, `methods`, etc. Because of this, logic isn't really grouped by feature, which can make it hard to read through a large and complex file. Readers would often have to scroll back and forth to follow what's going on. Another downside of this organization is that it made logic reuse difficult, as features are split up unintuitively in a component.

The [Composition API RFC includes this excellent diagram](https://vue-composition-api-rfc.netlify.com/#code-organization) showing the flow of different concerns in the same component built with both the Options API and Composition API. Each color represents a different logical concern. As shown, using composition functions with the Composition API allows for better organization in components.

![Vue 3 Composition API vs Options API code structure](https://images.ctfassets.net/23aumh6u8s0i/7E7YcG8WeU1RzSicIp5p50/9e07fbb2098fa81496f5e9ca4f3c8e62/vue-3-composition-vs-options-organization)

### Better TypeScript support

The next issue with Vue 2.x was that the sometimes confusing nature of `this` inside components often made it difficult to use TypeScript. The Options API relies on a lot of "magic" from the Vue compiler.

The Composition API, however, uses those internal functions directly, so `this` behaves as expected in JavaScript. This allows for much better TypeScript support when using the Composition API.

## Options API vs. Composition API

The best way to understand the changes is to see it in action.

Let's build out a simple component that allows the user to add two numbers with the press of a button. First, we'll quickly review how that would be done with the options-based API. Then we'll rebuild that same component with the Composition API to illustrate the differences.

![Vue 3 Composition API sample application](https://images.ctfassets.net/23aumh6u8s0i/6y4oOSD5MuurfOLNZ1ddJg/983b6510894c2974a18ce113550e7b06/vue-3-composition-api-app)

### Building with Options API

Here's what we'll need to create the simple addition calculator pictured above:

* **3 variables** &mdash; 1st number to add, 2nd number to add, sum
* **2 input boxes** &mdash; 1st number to add, 2nd number to add
* A **method** to add the two numbers together

And here's how it's done in Vue 2:

``` html  

<template>
    <div class="add">
        <h3>Addition Calculator</h3>
        <form id="sum">
            <input type="text" class="form-control" v-model="num1">
            <input type="text" class="form-control" v-model="num2">
            <button @click="addNumbers" type="button" class="btn btn-light">
                Add me!
            </button>
        </form>
        <p><strong>Sum:</strong> {{ sum }}</p>
    </div>
</template>
<script>
export default {
    name: 'Add',
    data() {
        return {
            num1: 0,
            num2: 0,
            sum: 0
        };
    },
    methods: {
        addNumbers: function () {
            this.sum = parseInt(this.num1) + parseInt(this.num2);
        }
    }
}
</script>
<style scoped>
    .add {
        background: #d67182;
        box-shadow: 1px 3px 6px #a3a3a3;
        padding: 50px 30px;
        width: 300px;
        text-align: center;
        margin: 80px auto;
    }
    p, h3 {
        color: #FFFFFF;
    }
    #sum {
        margin-top: 25px;
    }
    .form-control {
        margin-bottom: 15px;
    }
    .btn {
        margin-bottom: 30px;
    }
</style>

```

> **Note**: We can use `computed` here instead of `addNumbers` to get the value for `sum` and forego the button altogether. However, we're just going to put it into a separate method to demonstrate how functions and code structure works in the Composition API.

With the Vue 2 options-based API, we have our reactive data object returned in the `data()` function. Then the `AddNumbers()` function will be registered in the `methods` property. To access the variables from `data()`, we must use `this`.

Now, `this` is nested inside the method, so it should refer to the method's object instead of the entire instance, but it doesn't. Vue is working behind the scenes here to handle this for us. In general, this is pretty straightforward and intuitive, but in more complicated cases, this behind the scenes handling can cause unexpected behavior of `this`.

This "magic" is also part of what has made TypeScript support tough in Vue 2. Now let's look at how this same component is built with the Vue 3 Composition API.

### Building with Composition API

To keep this short, we'll just focus on building the component here. If you'd like to practice with the Composition API and rebuild this on your own, the Composition API can be added into a new Vue 2 project by running the following in your terminal:

```
vue create project-name
npm install @vue/composition-api 
```

Then in the `main.js` file:

```js
import Vue from 'vue';
import VueCompositionApi from '@vue/composition-api';

Vue.use(VueCompositionApi);
```

> For more information on this, check out the [official Vue Composition API repo](https://github.com/vuejs/composition-api).  

Now onto the final act 🎩! Let's rebuild the addition component using the Composition API. We're going to exclude the `<style>` section because nothing changes there. 

``` html  

<template>
    <div class="add">
        <h3>Addition Calculator</h3>
        <form id="sumComp">
            <input type="text" class="form-control" v-model="num1">
            <input type="text" class="form-control" v-model="num2">
            <button @click="addNumbers" type="button" class="btn btn-light">
            Add me!
        </button>
        </form>
        <p><strong>Sum:</strong> {{ sum }}</p>
    </div>
</template>
<script>
import { ref } from '@vue/composition-api';
export default {
    name: 'AddComposition',
    setup() {
        let num1 = ref(0);
        let num2 = ref(0);
        let sum = ref(0);
        function addNumbers() {
            sum.value = parseInt(num1.value) + parseInt(num2.value);
        }
        return {
            num1,
            num2,
            sum,
            addNumbers
        }
    }
}
</script>

```

First, we're importing the functions we need to use from the Composition API at the top. In this case, that's just `ref`.

Next, notice that everything is now inside a `setup()` function. Any functions or properties that need to be used in the template should go in `setup()` since this is how they're returned to the template.

Inside `setup()`, the reactive variables we're using are defined at the top as standalone variables, as opposed to a return object in the `data()` function.

The function `addNumbers()` is also hanging out on its own instead of nested in the `methods` property. We can now easily reuse our functions across component instances, which will significantly improve the readability of large codebases. Notice also that `this` is no longer needed to reference variables! Using the Composition API functions directly instead of through [Vue component options](https://012.vuejs.org/api/options.html) removes the `this` magic that was occurring behind the scenes.

Finally, we're returning the functions and properties to the template.

#### Reactivity: ref vs reactive

One new thing here is the use of `ref` in the variables, e.g., `let num1 = ref(0)`. This is how we're making our variables reactive! There are two functions that can be used to handle state and reactivity: `ref` and `reactive`.

**`ref()`**

`ref`, as shown in this example, takes a value and returns a reactive reference object. This object has a single value: `.value` that points to the value provided. Notice the use of `.value` on the variables in the `addNumbers()` method.

Refs can be created directly, as we've done here, or by using `computed()`.

The `computed()` getter function will return an immutable (can't be changed) `ref` object thats value can be accessed with `.value()`. It can also accept an object with a setter function to make it mutable if necessary.

Earlier, we mentioned that it would be better to find the sum of the numbers with `computed()`, but we kept it in the method for demonstration's sake.

Here's how it would be done using `computed()`:

```js
let sum = computed(() => parseInt(num1.value) + parseInt(num2.value));
```

Make sure to add `computed` to the import at the top as well:

```js
import { computed } from '@vue/composition-api';
```

> **Note**: Because `computed()` creates a ref, it can be used with [primitive values](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) as well. Normally the primitive value would get lost because primitives (essentially non-object values, such as a number) are passed by value, not reference. `ref`, however, will wrap the value and create an object. The value of the object can be referenced with `ref.value`. And then, when the `computed()` value changes, `ref.value` will change as well.

**`reactive()`**

The next way to handle reactivity is by using `reactive`. This is equivalent to `Vue.observable()` from Vue 2.x. It accepts an object and returns a proxy to that object that will be tracked. In this example, we're using `ref` for reactivity, but we could easily use `reactive` instead, like so:

```js
let state = reactive({ 
    num1: 0,
    num2: 0,
    sum: 0
})
```

If done this way, then `addNumbers()` would change to:

```js
function addNumbers() {
    sum = parseInt(num1) + parseInt(num2);
}
```

This was a very simple example of a component built with the Composition API, but hopefully it has demonstrated how the new API can lead to better code organization and less "magic".

While waiting for Vue 3 to come out, why not experiment with **adding authentication to your Vue 2 application**? Follow the example below to add authentication to a Vue.js + Node.js application or check out [this beginner tutorial to build an events showcase app using the Vue Options API](https://auth0.com/blog/beginner-vuejs-tutorial-with-user-login/). Remember, the Options API will still be useable in Vue 3, so there's no harm at all in starting with Vue 2 now. 

<include src="asides/Vue" />

## Summary

We've now gone over what the Composition API is, why it was necessary, and how you can build a component using it. The Composition API is already published and ready to use, so make sure you go [check it out on GitHub](https://github.com/vuejs/composition-api)! Let me know below if you'll be trying out the Composition API or sticking to the options-based API. Thanks for reading!

---


"composition-api"