1---
2title: Always Use .value When Accessing ref() in JavaScript
3impact: HIGH
4impactDescription: Forgetting .value causes silent failures and bugs in reactive state updates
5type: capability
6tags: [vue3, reactivity, ref, composition-api]
7---
8 
9# Always Use .value When Accessing ref() in JavaScript
10 
11**Impact: HIGH** - Forgetting `.value` causes silent failures where state updates don't trigger reactivity, leading to hard-to-debug issues.
12 
13When using `ref()` in Vue 3's Composition API, the reactive value is wrapped in an object and must be accessed via `.value` in JavaScript code. However, in templates, Vue automatically unwraps refs so `.value` is not needed there. This inconsistency is a common source of bugs.
14 
15## Task Checklist
16 
17- [ ] Always use `.value` when reading or writing ref values in `<script>` or `.js`/`.ts` files
18- [ ] Never use `.value` in `<template>` - Vue unwraps refs automatically there
19- [ ] When passing refs to functions, decide whether to pass the ref object or `.value`
20- [ ] Use IDE/TypeScript to catch missing `.value` errors early
21 
22**Incorrect:**
23```javascript
24import { ref } from 'vue'
25 
26const count = ref(0)
27 
28// These do NOT work as expected
29count++           // Tries to increment the ref object, not the value
30count = 5         // Reassigns the variable, loses reactivity
31console.log(count) // Logs "[object Object]", not the number
32 
33const items = ref([1, 2, 3])
34items.push(4)     // Error: push is not a function
35```
36 
37**Correct:**
38```javascript
39import { ref } from 'vue'
40 
41const count = ref(0)
42 
43// Always use .value in JavaScript
44count.value++           // Correctly increments to 1
45count.value = 5         // Correctly sets value to 5
46console.log(count.value) // Logs "5"
47 
48const items = ref([1, 2, 3])
49items.value.push(4)     // Correctly adds 4 to the array
50```
51 
52```vue
53<template>
54  <!-- In templates, NO .value needed - Vue unwraps automatically -->
55  <p>{{ count }}</p>
56  <button @click="count++">Increment</button>
57</template>
58```
59 
60## Reference
61- [Vue.js Reactivity Fundamentals - ref()](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#ref)
62