You keep hearing about this composition API in Vue. But it's a little scary and intimidating, and why it's so much better isn't really all that clear to you.
In this article you'll see exactly why you should learn to use it by comparing the old way to the new way. The examples also start out simple and get more complex, so you can see that the composition API isn't really all that different from what you're used to.
This replaces Vue 2's current options API, but the good news is that you aren't required to use it in Vue 3 applications. You can still use the tried-and-true options API and write your components just like you would have previously in Vue 2. For those who want to adopt this new method now or just want to familiarize with the updates, here's a few examples of some common, simple components, re-written using Vue 3's composition API.
A simple counter
Pretty much the go-to "Hello world" of frontend frameworks, the counter component. Let's see what one looks like in Vue 2:
<template>
<div class="counter">
<span>{{ counter }}</span>
<button @click="counter += 1">+1</button>
<button @click="counter -= 1">-1</button>
</div>
</template>
<script>
export default {
data() {
return {
counter: 0
}
}
}
</script>
We're displaying a span tag with a counter data object, which starts at zero. We then have two buttons with v-on:click attributes and inline code telling them to increase, or decrease, the counter by one. Then in the script tag, we're initializing that counter through a returned object in the data method.
Now let's take a look at what the same component looks like in Vue 3:
<template>
<span>{{ counter }}</span>
<button @click="counter += 1">+1</button>
<button @click="counter -= 1">-1</button>
</template>
<script>
import { ref } from 'vue';
export default {
setup() {
const counter = ref(0);
return {
counter
};
}
}
</script>
The first thing you might notice is that I've removed that wrapper div from the template. Previously in Vue, you'd get an error if you tried to render a component with more than one top-level element under the template tag. In Vue 3, this is no longer the case!
Moving down to the script section, it's a little longer than the previous component. That's kind of to be expected though, since our functionality is the bare minimum and there's slightly more setup with the composition API. Let's go over the changes line-by-line.
import { ref } from 'vue';
The ref method is required in order to give any data point reactivity in the composition API. By default, variables returned from the setup method are not reactive.
export default {
setup() { ... }
}
Next, we have the new setup method. This is the entrypoint for all composition API components, and anything in the returned object from it will be exposed to the rest of our component. This includes things like computed properties, data objects, methods, and component lifecycle hooks.
setup() {
const counter = ref(0);
return {
counter
};
}
We're first creating a counter using the previously-mentioned ref method, and passing it the initial value, zero. Then, all we have to do is return that counter, wrapped in an object.
From there, our component works just like it previously did, displaying the current value and allowing the user to adjust it based on the button presses given! Let's move on and take a look at something with a little more moving parts.
A shopping cart
Moving up in complexity, we'll create a component that uses two common attributes in Vue, computed properties and defined methods. I think a great example for that would be a basic shopping cart component, which shows items that a user has selected on something like an e-commerce website.
Here's an example of that in Vue 2 using the options API:
<template>
<div class="cart">
<div class="row" v-for="(item, index) in items">
<span>{{ item.name }}</span>
<span>{{ item.quantity }}</span>
<span>{{ item.price * item.quantity }}</span>
<button @click="removeItem(index)">Remove</button>
</div>
<div class="row">
<h3>Total: <span>{{ cartTotal }}</span></h3>
</div>
</div>
</template>
<script>
export default {
data() {
return {
items: [
{
name: "Cool Gadget",
quantity: 3,
price: 19.99
},
{
name: "Mechanical Keyboard",
quantity: 1,
price: 129.99
}
]
}
},
methods: {
removeItem(index) {
this.items.splice(index, 1);
}
},
computed: {
cartTotal() {
return this.items.reduce((total, item) => {
return total += (item.price * item.quantity);
}, 0);
}
}
}
</script>
Items in the cart are listed with v-for, and a button is present after each one to remove it from the main array on click. The total cost of the cart is calculated through a computed property that uses reduce and the value is displayed at the bottom of the items. Pretty straightforward, I think!
Let's see what a similar component with these attributes looks like in Vue 3 using the composition API:
<template>
<div class="cart">
<div class="row" v-for="(item, index) in items">
<span>{{ item.name }}</span>
<span>{{ item.quantity }}</span>
<span>{{ item.price * item.quantity }}</span>
<button @click="removeItem(index)">Remove</button>
</div>
<div class="row">
<h3>Total: <span>{{ cartTotal }}</span></h3>
</div>
</div>
</template>
<script>
import { ref, computed } from 'vue';
export default {
setup() {
const items = ref([
{
name: "Cool Gadget",
quantity: 3,
price: 19.99
},
{
name: "Mechanical Keyboard",
quantity: 1,
price: 129.99
}
]);
const removeItem = (index) => {
items.value.splice(index, 1);
};
const cartTotal = computed(() => {
return items.value.reduce((total, item) => {
return total += (item.price * item.quantity);
}, 0);
});
return {
items,
removeItem,
cartTotal
};
}
}
</script>
The biggest difference is that the computed property and method aren't in their own properties in the root Vue object, instead they're just plain methods defined and returned in the main setup() method.
For methods, we just create them as functions:
const removeItem = (index) => {
items.value.splice(index, 1);
};
And as long as we include them in the returned object, they're exposed to (and can be used by) the rest of the component. Computed properties are almost the exact same, with the exception of being wrapped in a computed method that's imported from the main Vue package:
const cartTotal = computed(() => {
return items.value.reduce((total, item) => {
return total += (item.price * item.quantity);
}, 0);
});
This way, we can de-couple parts of our components and separate them even further into portions of functionality that can be re-used and imported into multiple other components. We'll see how to do this in our next example.
For instance, if we wanted to, we could easily split out the cartTotal computed property or the removeItem method into their own files. Then instead of defining and using them in the main component above, we'd import them and just call the designated method.
On to the last component!
A like button
Our third and final example is even more complex than the last two, let's see what a component would look like that has to pull in data from an API endpoint and react to user input.
This is what that might look like with the options API in a Vue 2 application:
<template>
<button @click="sendLike" :disabled="isDisabled">{{ likesAmount }}</button>
</template>
<script>
export default {
data() {
return {
likes: 0,
isDisabled: false
}
},
mounted() {
fetch('/api/post/1')
.then((response) => response.json())
.then((data) => {
this.likes = data.post.likes;
});
},
methods: {
sendLike() {
this.isDisabled = true;
this.likes++;
fetch('/api/post/1/likes', {
method: 'POST'
})
.then((response) => {
this.isDisabled = false;
}
.catch((error) => {
this.likes--;
this.isDisabled = false;
});
}
},
computed: {
likesAmount() {
return this.likes + ' people have liked this';
}
}
}
</script>
A little more complicated than our previous examples, but let's break it down.
We're starting off in the template with a button, that has a v-on:click bind to a sendLike method, and a bound disabled attribute to the data attribute isDisabled. Inside of that button we're showing the amount of likes with a likes data attribute.
Moving through to the script, we're initializing the data object returned with 0 likes, and isDisabled set to false. We're using the mounted() lifecycle method to call an API endpoint and set the amount of likes to a specific post's likes.
Then we define a sendLike method, which disables the button and increases the likes by 1. (We're increasing the likes before actually sending the request so that our user interaction is recorded immediately.)
Finally, we send the request to our make-believe API, and await the response. Either way, we remove the disabled attribute from the button, but if the server returns an error for some reason, we remove the initial like that was recorded and reset likes to the previous value.
Now, let's see what a similar component would look like in Vue 3 using the composition API:
<template>
<button @click="sendLike" :disabled="isDisabled">{{ likesAmount }}</button>
</template>
<script>
import { ref, computed, onMounted } from 'vue';
export default {
setup() {
const likes = ref(0);
const isDisabled = ref(false);
onMounted(() => {
fetch('/api/post/1')
.then((response) => response.json())
.then((data) => {
likes = data.post.likes;
});
});
const sendLike = async () => {
isDisabled.value = true;
likes.value++;
fetch('/api/post/1/likes', {
method: 'POST'
})
.then((response) => {
isDisabled.value = false;
})
.catch((error) => {
likes.value--;
isDisabled.value = false;
});
}
const likesAmount = computed(() => {
return likes.value + ' people have liked this';
});
return {
likes,
isDisabled,
likesAmount,
sendLike
};
}
}
</script>
Alright, there it is!
Now, a main difference between this and our counter component is the addition of a mounted lifecycle hook. Instead of being another separate method like in Vue 2's options API, this is again just written as a function in setup, wrapped in an included onMounted() method.
This is where the composition API can start to shine with composables. This like button component is getting a little long, and it includes some functionality that could be split out into a separate file and imported instead.
For example, we might want to include the retrieval and updating of likes in different components, so we can create a new JavaScript file which handles just that:
// useLikes.js
import { ref, computed, onMounted } from 'vue';
export default function useLikes(postId) {
const likes = ref(0);
const likesAmount = computed(() => {
return likes + ' people have liked this'
});
onMounted(() => {
fetch(`/api/posts/${postId}`)
.then((response) => response.json())
.then((data) => {
likes.value = data.post.likes;
});
});
return {
likes,
likesAmount
}
}
This renderless component, useLikes, initiates the placeholder likes amount, 0. It then sends a fetch request to the API endpoint of the post whose ID is passed in. After that completes, our likes are then updated to match whatever is attributed to that current post.
So, how's this used back in our main component? Like this:
<template>
<button @click="sendLike" :disabled="isDisabled">{{ likesAmount }}</button>
</template>
<script>
import { useLikes } from '@/useLikes';
import { ref, computed, onMounted } from 'vue';
export default {
setup() {
const {
likes,
likesAmount
} = useLikes(1);
const isDisabled = ref(false);
const sendLike = async () => {
isDisabled.value = true;
likes.value++;
fetch('/api/post/1/likes', {
method: 'POST'
})
.then((response) => {
isDisabled.value = false;
})
.catch((error) => {
likes.value--;
isDisabled.value = false;
});
}
return {
likes,
isDisabled,
likesAmount,
sendLike
};
}
}
</script>
First we use an import statement to get our exported useLikes function, and then use a destructured object that consists of the likes and likesAmount ref object and method respectively. They're brought into our main component through that same useLikes function.
All that was left to do was pass in the postId attribute, which we've set as a hard-coded value to 1.
Wrapping up
Well, there you have it! You've seen three different components that were created in Vue 2, and then their counterparts replicated in Vue 3.
Whether you're a developer experienced in the framework, or one who's still learning the ropes, I hope these helped you on your journey through this newest version of Vue. Despite its different, sometimes intimidating appearance, the composition API can help you organize and refactor your frontend code in a more stable and maintainable way.
If you have any questions, comments, or want to chat more about
web development in general, donβt hesitate to reach out on Twitter or through the discussion below.
Latest comments (28)
I'm completely disagree with the arguments, compositions API doesn't provide any benefits and only creates a messy and unstructured code. I'm sticking to options API even in Vue 3 projects, it just makes more sense, the code is clear and simple and it's so much easier to work especially when multiple developers involved. There is rally no downsides in options API, people that are telling about separating code functionality in a single component making a mistake in the first place where they don't split different functionality to different components. Components in Vue should be small and simple and options API works beautiful with proper architecture.
I still like more Vue 2 than 3 but it also depends of how you implemented the composition api in your project. It is maybe more the way you structured you project and how you abstracted your logic and reused your components
When the composition API was announced I was hesitant, my argument was that most of the dev time would go towards the new composition api. It came out and I tried it, and Iβd say it was ok. Iβve written large scale applications with Vue 2. Matter of fact Iβm currently working on 3 large scale applications in Vue 2 right now at work. So Iβm very familiar with the options API in large applications. To me itβs easier. Large Applications are usually more complex to deal with, with the options API I can go to a component and tell you very quickly where things are, and with a little code review weβve kept components well maintained and clean still.
My point is this - you can write βspaghettiβ code on any language, framework, or pattern. In the end it is up to you, the developer, to keep the codebase clean. Iβve already seen, in my honest opinion, not great code with the new composition API, so I donβt think it fixes any problems. Itβs up the developers to actually write it that way to fix it. Which in my experience is possible in both ways.
So itβs not that I have an issue with the Composition API, I just donβt think it fixes the problems people say they fix. In the end cleaner code is up to the developer maintaining the project, not the framework or pattern they use, and is still relatively opinionated.
I started using
Composition APIwithTypeScriptlast year and damn - that was great experience. Not only because code looks "cooler" and cleaner but also with fact that you can much easier split your code into single "plugins".With this you can move things like
onMountedetc. to separated files and implement those without any problem to any component you want.There is one great thing that was implemented in 3.2 -
<script setup>which transforms your code from this:to this:
You don't need to use Composition API, sure but I think you will :D
So this is like React Hooks?
Agree, I liked Vue because of the straightforward templates and because it was easier to understand than React, but now the composition API complicates it and makes it a React wannabe.
Imho options API is better because before I had learnt Vue, knowing what the code would do was clearer than if you use composition API, which introduces ref and I don't know what does that do.
but you have deal with
thiswhich in vue is kinda not the same thing that you would get inside clear JavaScript codeI'm ok with dealing with this.
Didn't know about that short cut!
PM / Dev Manager non-web developer here. Looking at Angular vs React vs Vue vs Flutter vs Blazor vs Svelte, I concluded that Vue is superior for my purpose of creating quick internal MVPs. However, much like the debate in the comments, the Vue2 vs Vue3 uncertainty has definitely made me question investing in Vue. I seriously applaud all you front-end web developers building real world solutions on what feels like a constantly shifting "hot mess" of WIP projects and concepts.
I agree normally but with the setup attribute itβs a lot cleaner than setting up the setup function in the exported object