Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 38 ยท Stores and State

Destructuring Stores with storeToRefs

Learn why destructuring a Pinia store breaks reactivity, how storeToRefs keeps state and getters reactive, and why actions are destructured directly from the store.

JavaScript developers love destructuring: const { name, age } = user. With Pinia stores it has a catch. If you destructure state or getters the usual way, you get plain values that never update. This lesson explains why, and shows the one-line fix, storeToRefs.

Why plain destructuring loses reactivity

A store is a reactive object. Reading a property from it inside a reactive context (a template, computed, watch) registers a dependency. But destructuring happens once, in your setup(), and copies the current value:

JavaScript
const store = useCounterStore();
const { count } = store; // count is the number 0, not a reactive link
store.count++;           // store.count is 1, but count is still 0
flowchart LR
    A["store.count (reactive property)"] -->|"read in template"| B["tracked: updates the UI"]
    A -->|"const { count } = store"| C["a plain number copied once"]
    C --> D["never changes again"]

Destructuring cuts the connection between your variable and the store.

This is the same behavior you would see destructuring any reactive() object. It is not a Pinia bug, just a JavaScript fact.

The fix: storeToRefs

storeToRefs(store) returns an object where every state property and getter is turned into a ref that stays connected to the store. Destructuring that object is safe, because each ref keeps its link:

JavaScript
import { storeToRefs } from "pinia";

const store = useCounterStore();
const { count, doubled } = storeToRefs(store);

store.count++;
console.log(count.value);   // 1: connected
console.log(doubled.value); // 2: getters work too

In a template, refs unwrap automatically, so you write {{ count }}, not {{ count.value }}.

See the difference live. The first line uses plain destructuring and the second uses storeToRefs. Click the button and watch which one follows.

Plain destructuring vs storeToRefs

Actions are different

storeToRefs skips actions, on purpose. Actions are functions, and functions have no reactivity to lose. Pinia binds them to the store, so you can destructure them straight from the store and call them anywhere:

JavaScript
const store = useTodoStore();
const { items, remaining } = storeToRefs(store); // state + getters
const { add, toggle } = store;                   // actions

This works because Pinia already set this correctly inside each action, so add("x") behaves like store.add("x").

A handy rule: storeToRefs for data, plain destructuring for actions. If you find yourself writing store.something repeatedly, you do not need to destructure at all. Using store.count in the template is perfectly fine and the most common style.

What storeToRefs returns

You can see exactly which keys you get:

What does storeToRefs include?

The result contains items, filter and total: state and getters, all refs. Writing to a state ref writes to the store, so v-model on a destructured ref works.

Common patterns

In <script setup>:

VUE
<script setup>
import { storeToRefs } from "pinia";
import { useCartStore } from "@/stores/cart";

const cart = useCartStore();
const { items, total } = storeToRefs(cart);
const { addItem } = cart;
</script>

Writing with v-model: v-model="name" works with a ref obtained from storeToRefs, because writing to the ref updates the store.

Watching: watch(count, ...) works on the destructured ref, and so does watch(() => store.count, ...).

Passing to a composable: composables that accept refs (the MaybeRef pattern) work well with storeToRefs results.

What not to do

  • Do not wrap the store with toRefs(store). It would also turn actions and other store internals into refs. Use storeToRefs.
  • Do not destructure getters from store. They are computed values and need storeToRefs just like state.
  • Do not call storeToRefs in a hot path such as a render function. Call it once in setup().

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does const { count } = store lose reactivity?

    Destructuring reads the value a single time. The copy no longer tracks the store.
  2. 2. Which does storeToRefs include?

    It returns refs for state and getters. Actions are plain functions and are skipped.
  3. 3. How should you get an action out of a store?

    Actions are bound to the store, so destructuring them directly from the store is safe.
  4. 4. In a template, how do you display a ref from storeToRefs?

    Templates unwrap top-level refs automatically.

Summary

  • Plain destructuring copies values and breaks reactivity.
  • storeToRefs(store) gives connected refs for state and getters.
  • Destructure actions straight from the store.
  • Writing to a ref from storeToRefs writes to the store.
  • You can also just use store.property everywhere; destructuring is optional.

Next: Patching and Resetting State