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.