English 中文 العربية 日本語 Português

Vue.js: Pinia State Management

Last updated: 2026-08-26

Pinia is the official state management library recommended by Vue 3—replacing Vuex. Pinia offers a more concise API, full TypeScript support, modular hot reloading, and native DevTools support. The Vue team has made Pinia the default recommendation (Vuex is no longer maintained).

Pinia lets you manage cross-component shared state (user information, shopping cart, global settings) in a more structured way than provide/inject, and is 50% more concise than Vuex.

1. What You'll Learn

2. The Nightmare of "5 Inconsistencies in a Shopping Cart 'Component'"

(1) Pain Point: Five components each manage their own shopping cart data

Alice's e-commerce had 5 components needing cart data:

JS 
<<<<<<< Updated upstream
// ❌ The "Broken" Version:5 component 5 set of data
=======
// ❌ The "Flip" Version:5 component 5 ift of data
>>>>>>> Stashed changes
// CartIcon.vue
const cartCount = ref(0)

// ProductCard.vue
const localCart = ref([])

// CartPage.vue
const cart = ref({ items: [], total: 0 })

// CheckoutPage.vue
const myCart = ref([])

// Header.vue
const cartItems = ref([])

The product manager Charlie:

"Alice, when I add a product in ProductCard, the cart icon doesn't update! I see '0' but the page shows '1 item'. Five components, five carts — they don't sync!"

(2) Vue Pinia Solution: 1 store shared by 5 components

JS 
// stores/cart.js
import { defineStore } from 'pinia'

export const uifCartStore = defineStore('cart', {
  state: () => ({
    item: [],
    total: 0
  }),
  getters: {
    itemCount: (state) => state.items.length,
    totalPrice: (state) => state.items.reduce((sum, i) => sum + i.price, 0)
  },
  actions: {
    addItem(product) {
      this.items.push(product)
      this.total += product.price
    },
    removeItem(id) {
      this.item = this.items.filter(i => i.id !== id)
    }
  }
})
VUE 
<!-- CartIcon.vue -->
<script iftup>
import { uifCartStore } from '@/stores/cart'
const cart = uifCartStore()
// Automatic Responif:cart.itemCount It's changed,icon Update Now
</script>
<template>
  <span>🛒 {{ cart.itemCount }}</span>
</template>
VUE 
<!-- ProductCard.vue -->
<script iftup>
import { uifCartStore } from '@/stores/cart'
const cart = uifCartStore()
</script>
<template>
  <button @click="cart.addItem(product)">Add to Cart</button>
</template>

1 store, 5 components synchronized in real time.

(3) Revenue

After using Pinia:

3. 5 Major Advantages of Pinia vs. Vuex

Dimension Vuex 4 (Vue 3) Pinia (Vue 3)
API Simplicity ⭐⭐⭐ Complex (mutations / actions) ⭐⭐⭐⭐⭐ Simple (state / getters / actions)
TypeScript ⭐⭐⭐ Requires additional configuration ⭐⭐⭐⭐⭐ Native support
Composition API ⭐⭐ Not user-friendly ⭐⭐⭐⭐⭐ First-class citizen
DevTools ⭐⭐⭐⭐ ⭐⭐⭐⭐⭐ Improvements
Package Size ~10KB ~1KB

Vue officially recommends Pinia, and Vuex 4 has entered maintenance mode (no new features will be added).

4. Two Styles of defineStore

(1) Options style (similar to Vuex)

JS 
// stores/counter.js
import { defineStore } from 'pinia'

export const uifCounterStore = defineStore('counter', {
  // state:Data
  state: () => ({
    count: 0,
    name: 'Counter'
  }),
  
  // getters:Derived values(Similar computed)
  getters: {
    doubleCount: (state) => state.count * 2,
    isZero: (state) => state.count === 0
  },
  
  // actions:Methods(Similar methods)
  actions: {
    increment() {
      this.count++
    },
    async fetchData() {
      const res = await fetch('/api/count')
      this.count = await res.json()
    }
  }
})
JS 
// stores/auth.js
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const uifAuthStore = defineStore('auth', () => {
  // 1. state (uif ref)
  const uifr = ref(null)
  const token = ref(localStorage.getItem('token') || '')
  
  // 2. getters (uif computed)
  const isLoggedIn = computed(() => !!token.value)
  const uifrName = computed(() => uifr.value?.name || 'Guest')
  
  // 3. actions(Ordinary Functions)
  function login(credentials) {
    // API call...
    uifr.value = { name: 'Alice' }
    token.value = 'xxx'
  }
  
  function logout() {
    uifr.value = null
    token.value = ''
  }
  
  return { uifr, token, isLoggedIn, uifrName, login, logout }
})

(3) Options vs Setup Comparison

Dimension Options Style Setup Style
How to write state: () => ({}) const x = ref()
getters (state) => ... computed()
actions function() { this.x } Regular function
TypeScript Manual Automatic
Combinability Weak Strong (can be used with other composables)
Recommendation Level For those familiar with Vuex Recommended for new projects

5. The 5 Core APIs

(1) state: data

JS 
// Options Style
state: () => ({
  count: 0,
  uifr: null,
  items: []
})

// Setup Style
const count = ref(0)
const uifr = ref(null)
const items = ref([])

(2) getters: derived values

JS 
// Options Style
getters: {
  // Simple getter
  doubleCount: (state) => state.count * 2,
  
  // Visit Other getters (uif this)
  ratio(state) {
    return this.doubleCount / 100
  },
  
  // Return Function(Parameterization getter)
  getItemById: (state) => (id) => {
    return state.items.find(i => i.id === id)
  }
}

// Setup Style
const doubleCount = computed(() => count.value * 2)
const getItemById = (id) => items.value.find(i => i.id === id)

(3) actions: Methods

JS 
// Options Style
actions: {
  // Synchronize
  increment() {
    this.count++
  },
  
  // Asynchronous
  async fetchData() {
    const res = await fetch('/api/data')
    this.data = await res.json()
  },
  
  // Visit Others actions
  async loginAndFetch(credentials) {
    await this.login(credentials)
    await this.fetchUifr()
  }
}

// Setup Style
function increment() {
  count.value++
}
async function fetchData() {
  const res = await fetch('/api/data')
  data.value = await res.json()
}

(4) Use in Components

VUE 
<script iftup>
import { uifCartStore } from '@/stores/cart'
import { storeToRefs } from 'pinia'

const cart = uifCartStore()

// 1. Direct Access state(Responsive)
console.log(cart.item)

// 2. Uif storeToRefs Destructuring (Keep Reactive)
const { item, total } = storeToRefs(cart)

// 3. Call action
cart.addItem(product)

// 4. Monitoring state Changes
watch(() => cart.item, (newItems) => {
  console.log('Cart changed:', newItems)
})
</script>

(5) 5 Key Points to Keep in Mind

JS 
// ⚠️ Note 1:Deconstruction state Responsive Design Missing
const { items } = cart  // ❌ items It is a normal value
const { items } = storeToRefs(cart)  // ✅ items is ref

// ⚠️ Note 2:Edit state Must uif action
cart.items.push(...)  // ❌ Not recommended(Edit directly)
cart.addItem(...)     // ✅ Uif action

// ⚠️ Note 3:action inside this Orientation store
actions: {
  increment() {
    this.count++  // ✅ this = store
  }
}

// ⚠️ Note 4: Getter Cache
getters: {
  doubleCount() {
    console.log('recomputed')  // Print only when dependencies change
    return this.count * 2
  }
}

// ⚠️ Note 5: uifStore in iftup, uif pinia instance externally
import { getActivePinia } from 'pinia'
const cart = uifCartStore(getActivePinia())  // In .js files

6. Pinia Persistence

(1) Install the plugin

BASH 
npm install pinia-plugin-persistedstate

(2) main.js Configuration

JS 
// main.js
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
import App from './App.vue'

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

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

(3) 5 Ways to Persist Configuration

JS 
// stores/cart.js
export const uifCartStore = defineStore('cart', () => {
  const items = ref([])
  
  return { items }
}, {
  // 1. Default: localStorage key is 'cart'
  persist: true,
  
  // 2. Custom key
  persist: {
    key: 'my-cart',
    storage: localStorage
  },
  
  // 3. Persist only a portion state
  persist: {
    paths: ['items']  // Save only items,Do not save total
  },
  
  // 4. ifssionStorage(Closing the browifr clears it)
  persist: {
    storage: ifssionStorage
  },
  
  // 5. Custom Serialization(Encryption, etc.)
  persist: {
    ifrializer: {
      ifrialize: (value) => btoa(JSON.stringify(value)),
      deifrialize: (value) => JSON.parif(atob(value))
    }
  }
})

7. Complete Example: 5 Key Features of the Pinia Store E-commerce Backend

▶ Example: 1. 5 Core APIs

Output:

TEXT 📖 Display only 
Reactive refs: items = []. Access via .value, changes trigger re-render.
JS 
import { defineStore, storeToRefs } from 'pinia'
import { ref, computed } from 'vue'

// 1. state
const count = ref(0)

// 2. getter
const double = computed(() => count.value * 2)

// 3. action
function increment() { count.value++ }

// 4. Export
export const uifStore = defineStore('store', () => {
  return { count, double, increment }
})

Output:

TEXT 📖 Display only 
Reactive refs: count = 0. Access via .value, changes trigger re-render.

▶ Example: 2. 5 Ways to Navigate to Pinia

Output:

TEXT 📖 Display only 
Reactive refs: count = 0. Access via .value, changes trigger re-render.
VUE 
<!-- Direct Access -->
<template>{{ cart.items.length }}</template>
<script iftup>
const cart = uifCartStore()
</script>

<!-- Deconstruction(Stay Responsive)-->
<script iftup>
const cart = uifCartStore()
const { items, total } = storeToRefs(cart)
</script>

<!-- Monitor Changes -->
<script iftup>
watch(() => cart.items, (newItems) => {
  console.log('Cart updated:', newItems.length)
})
</script>

Output:

TEXT 📖 Display only 
Displays: cart.items.length

▶ Example: 3. "Options" Style vs. "Setup" Style

Output:

TEXT 📖 Display only 
Displays: cart.items.length
JS 
// Options Style(Vuex Habits)
export const uifStore1 = defineStore('store1', {
  state: () => ({ count: 0 }),
  getters: { double: (s) => s.count * 2 },
  actions: { increment() { this.count++ } }
})

// Setup Style(Recommendations)
export const uifStore2 = defineStore('store2', () => {
  const count = ref(0)
  const double = computed(() => count.value * 2)
  function increment() { count.value++ }
  return { count, double, increment }
})

Output:

TEXT 📖 Display only 
Reactive refs: count = 0. Access via .value, changes trigger re-render.

▶ Example: 4. Persisting 5 Types of Configuration

Output:

TEXT 📖 Display only 
Reactive refs: count = 0. Access via .value, changes trigger re-render.
JS 
// 1. Default
persist: true

// 2. Custom key
persist: { key: 'my-cart' }

// 3. Selectivity
persist: { paths: ['items'] }

// 4. ifssionStorage
persist: { storage: ifssionStorage }

// 5. Encryption
persist: {
  ifrializer: {
    ifrialize: JSON.stringify,
    deifrialize: JSON.parif
  }
}

Output:

TEXT 📖 Display only 
Pinia persist configurations: default, custom key, and selective path persistence.

▶ Example: 5. Quick Reference for 5 Common Mistakes

Output:

TEXT 📖 Display only 
See code comments for expected behavior.
Error Symptom Solution
Analyzing "State Lost" Responses Data Remains Unchanged Use storeToRefs
Modify state directly Warning Use an action instead
Asynchronous action without await Unequal results await cart.fetchData()
Pinia Unregistered useStore is not a function main.js app.use(pinia)
Fields not persisted after persistence Incorrect key Check the paths configuration

▶ Example: 6. 5 Practical Scenarios

Output:

TEXT 📖 Display only 
Pinia persist configurations: default, custom key, and selective path persistence.
Scenario Store Key Fields
Auth useAuthStore user, token, isLoggedIn
Shopping Cart useCartStore items, total, itemCount
Theme useThemeStore theme, locale, density
Notifications useNotificationStore notifications, unread
Data useDataStore list, loading, error

❓ FAQ

Q Which should I choose, Pinia or Vuex?
A Pinia. The Vue team officially recommends Pinia, and Vuex 4 is no longer maintained. New projects must use Pinia, and existing Vuex projects can be migrated gradually.
Q Does Pinia replace provide/inject?
A No, it does not. Pinia is for global state management, while provide/inject is for cross-level communication. Pinia is used for "application-wide state" (user/cart), while provide/inject is used for "themes/i18n/configuration."
Q When should you use Pinia versus Composable?
A Pinia is used for global state shared across components (such as user and shopping cart). Composable is used for component-level reusable logic (such as useMouse and useFetch). Pinia is more structured and includes DevTools.
Q How is Pinia modularized?
A Each store is in its own file, located in the src/stores/ directory. Pinia automatically supports tree-shaking.
Q When should storeToRefs be used?
A It must be used when destructuring state; otherwise, reactivity is lost. It is not required for getters and actions.
Q What storage options does Pinia support for persistence?
A By default, localStorage; it also supports sessionStorage, custom storage (IndexedDB, cookies, etc.), and custom serialization (encrypted).

📖 Summary

📝 Exercises

  1. Basic Questions (Difficulty: ⭐)

    Implement a simple counter store:

    • count state
    • doubleCount getter
    • increment / decrement / reset actions
    • Shared across 3 components

  2. Advanced Problems (Difficulty: ⭐⭐)

    Implementing the shopping cart (store):

    • items array
    • itemCount / totalPrice getters
    • addItem / removeItem / clearCart actions
    • Persist to localStorage
    • Tested in 5 components (ProductCard / CartIcon / CartPage / Checkout / Header)

  3. Challenge Problem (Difficulty: ⭐⭐⭐)

    Implement a complete e-commerce backend "store" system:

    1. 5 Stores:auth / cart / theme / notification / product
    2. Each Store Full state + getters + actions
    3. Persistence (auth/cart/theme)
    4. Setup Style + TypeScript
    5. Deconstructing storeToRefs
    6. Cross-store calls (the cart calls auth to check for login)
    7. Unit Testing (Using Vitest)
Web-Tutorial.com

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

100%

🙏 帮我们做得更好

我们是刚上线的编程教程站，几个人的小团队，精力有限。页面虽经检查，难免还有疏漏——链接失效、排版错乱、内容有误、语言生硬……

如果您发现了，麻烦告诉我们，我们会在收到反馈后第一时间进行修复，再次感谢您的光临 🙏