Vue Reactive Refs

Vue Reactive Refs

Create and manage reactive primitive values and objects using ref and reactive

When to Use

• You need reactive state in a Vue 3 component using the Composition API
• Building composables that return reactive values
• Managing form inputs, counters, flags, or any mutable component state

Instructions

1. Use ref() for primitives (strings, numbers, booleans) — access via .value.
2. Use reactive() for objects — access properties directly (no .value).
3. Use computed() for derived values that should auto-update.
4. Never destructure a reactive() object — it breaks reactivity. Use toRefs() if needed.

import { ref, reactive, computed, toRefs } from 'vue';

const count = ref(0); // ref for primitive
const user = reactive({ name: 'Alice', age: 30 }); // reactive for object
const greeting = computed(() => `Hello, ${user.name}!`);

count.value++; // ref needs .value
user.age = 31; // reactive — direct access

5. In templates, refs are auto-unwrapped — use {{ count }} not {{ count.value }}.
6. Use shallowRef() or shallowReactive() for large objects where deep reactivity is not needed.

Details

Vue 3's reactivity system is built on ES6 Proxy. ref() wraps a value in a reactive container with a .value property. reactive() wraps an entire object, making all properties reactive. computed() creates a cached, read-only reactive value derived from other reactive sources.

Trade-offs:

• ref requires .value in JavaScript (not in templates) — a common source of bugs for new Vue developers
• reactive() loses reactivity when destructured — use toRefs() to safely destructure
• Deep reactivity on large objects can be expensive — use shallowRef/shallowReactive for performance
• Replacing a reactive() object entirely (state = newObj) does not trigger updates — mutate properties instead

When NOT to use:

• For non-reactive constants — just use const without wrapping
• For data that never changes after initialization — no need for reactivity overhead
• For large datasets rendered in lists — consider shallowRef with manual trigger via triggerRef()

Source

https://patterns.dev/vue/reactive-refs

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.