Vue v-model
with Checkboxes in 5 minutes
Vue’s v-model
is a powerful directive that simplifies two-way data binding, making form inputs easy to manage. When dealing with checkboxes, however, things can get a bit tricky—especially when working with multiple selections or custom implementations.
In this post, we’ll break down how v-model
works with checkboxes, covering both single and multiple selections, common pitfalls, and best practices to keep your Vue components clean and efficient. Whether you're a beginner or looking to refine your Vue skills, this guide will help you leverage v-model
effectively in checkbox scenarios.
🚀 Let’s dive in!
1. Single Checkbox Binding
For a single checkbox, v-model
binds the checked
state to a Boolean value in the component’s data. Here’s an example:
<script setup>
import { ref } from 'vue'
const value = ref(false)
</script>
<template>
<input type="checkbox" v-model="value" />
<label>{{ value }}</label>
</template>
️You can easily test it in Vue playground
🐛 test here
Furthermore, you can give to the checkbox the ability to set different values to the ref variable, rather than just true
or false
, by setting the attributes true-value
and false-value
in the input element:
<script setup>
import { ref } from 'vue'
const value = ref()
</script>
<template>
<input
type="checkbox"
v-model="value"
true-value="Agree"
false-value="I do not agree"
/>
<label>{{ value }}</label>
</template>
2. Multiple Checkboxes with an Array
If you need to bind multiple checkboxes to a list, v-model
can be used with an array. When a checkbox is checked, its value is added to the array. When unchecked, the value is removed.
<script setup>
import { ref } from 'vue'
const items = ref([])
</script>
<template>
<div>
<input type="checkbox" value="Option 1" v-model="items" />
<label>Option 1</label>
</div>
<div>
<input type="checkbox" value="Option 2" v-model="items" />
<label>Option 2</label>
</div>
<div>
<input type="checkbox" value="Option 3" v-model="items" />
<label>Option 3</label>
</div>
<div>Selected items: {{ items }}</div>
</template>
Now, if the user checks “Option 3” and “Option 1”, items
will look like this:

️You can easily test it in Vue playground
🐛 test here
Common Pitfalls
While v-model simplifies checkbox handling in Vue, there are some common pitfalls to watch out for:
- Forgetting to initialize data properly — ensure that
boolean
orarray
data properties are properly initialized in theref
variable - Incorrectly using non-boolean values for single checkboxes — If using custom
true-value
andfalse-value
, ensure they are set correctly to avoid unexpected behaviors - Expecting v-model to work on dynamic elements without a
key
— When rendering checkboxes dynamically withv-for
, ensure each has aunique key
to prevent unexpected state issues
Conclusion
Using v-model
with checkboxes in Vue is straightforward, whether you are working with single checkboxes, groups of checkboxes, or custom values. By understanding these patterns, you can create more interactive and dynamic forms in your Vue applications.