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:

1. Forgetting to initialize data properly — ensure that booleanor arraydata properties are properly initialized in the ref variable
2. Incorrectly using non-boolean values for single checkboxes — If using custom true-value and false-value, ensure they are set correctly to avoid unexpected behaviors
3. Expecting v-model to work on dynamic elements without a key — When rendering checkboxes dynamically with v-for, ensure each has a unique 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.

References:

• https://vuejs.org/guide/essentials/forms#checkbox