A Comprehensive Guide to Using Pinia for State Management in Vue 3

When developing a Vue 3 project, the author encountered difficulties passing data across multiple component layers and found that Vuex was too heavyweight, so they turned to Pinia, the official state‑management library for Vue.

Installation

yarn add pinia
// or
npm install pinia

After installing, Pinia is attached to the Vue app in main.js:

import { createApp } from 'vue'
import App from './App.vue'
import { createPinia } from 'pinia'

const pinia = createPinia()
const app = createApp(App)
app.use(pinia)
app.mount('#app')

The core concept is a Store , created with defineStore. The function receives a unique name and an options object.

Option‑store (object) syntax

// Central store
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: ref(0),
    isLogin: ref(false)
  }),
  actions: {
    add() {
      this.count++
    }
  }
})

Setup‑store (function) syntax

import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const isLogin = ref(false)
  function add() { count.value++ }
  return { count, isLogin, add }
})

Stores can be used in any component. For example, in App.vue:

<template>
  <div>
    <p>Count: {{ counterStore.count }}</p>
    <p>Logged in: {{ counterStore.isLogin }}</p>
    <button @click="counterStore.add">Add</button>
  </div>
</template>

<script setup>
import { useCounterStore } from './stores/counter'
const counterStore = useCounterStore()
</script>

When destructuring a store, reactivity can be lost; Pinia provides helpers such as toRef, toRefs, and storeToRefs to preserve it, or you can directly destructure in <script setup> because the proxy is retained.

// Using toRefs
const { count, add } = toRefs(counterStore)
// Using storeToRefs
const { count } = storeToRefs(counterStore)
// Direct destructuring in script setup
const { add } = counterStore

Pinia also offers built‑in store methods: $reset – restores the initial state. $patch – batch updates state (object or function form). $state – replaces the whole state object. $subscribe – watches state changes for side effects.

// $reset example
counterStore.count = 10
counterStore.$reset()

// $patch object form
counterStore.$patch({ count: 5, isLogin: true })
// $patch function form
counterStore.$patch(state => { state.count++ })

// $state replacement
counterStore.$state = { count: 100, isLogin: true }

// $subscribe example
counterStore.$subscribe((mutation, state) => {
  console.log('State changed:', state.count)
})

For persistence across page reloads, the community plugin pinia-plugin-persistedstate can be installed and added to the Pinia instance:

yarn add pinia-plugin-persistedstate

import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)

In summary, Pinia provides an intuitive, flexible, and lightweight approach to state management for modern Vue applications, making it a preferable alternative to the heavier Vuex.