Skip to content

API Documentation / pinia

Module: pinia ​

Enumerations ​

Interfaces ​

Type Aliases ​

PiniaStorePlugin ​

Ƭ PiniaStorePlugin: PiniaPlugin

Plugin to extend every store.

Deprecated

use PiniaPlugin instead


StateTree ​

Ƭ StateTree: Record<string | number | symbol, any>

Generic state of a Store


Store ​

Ƭ Store<Id, S, G, A>: _StoreWithState<Id, S, G, A> & UnwrapRef<S> & _StoreWithGetters<G> & _ActionsTree extends A ? {} : A & PiniaCustomProperties<Id, S, G, A> & PiniaCustomStateProperties<S>

Store type to build a store.

Type parameters ​

NameType
Idextends string = string
Sextends StateTree = {}
G{}
A{}

StoreActions ​

Ƭ StoreActions<SS>: SS extends Store<string, StateTree, _GettersTree<StateTree>, infer A> ? A : _ExtractActionsFromSetupStore<SS>

Extract the actions of a store type. Works with both a Setup Store or an Options Store.

Type parameters ​

Name
SS

StoreGeneric ​

Ƭ StoreGeneric: Store<string, StateTree, _GettersTree<StateTree>, _ActionsTree>

Generic and type-unsafe version of Store. Doesn't fail on access with strings, making it much easier to write generic functions that do not care about the kind of store that is passed.


StoreGetters ​

Ƭ StoreGetters<SS>: SS extends Store<string, StateTree, infer G, _ActionsTree> ? _StoreWithGetters<G> : _ExtractGettersFromSetupStore<SS>

Extract the getters of a store type. Works with both a Setup Store or an Options Store.

Type parameters ​

Name
SS

StoreOnActionListener ​

Ƭ StoreOnActionListener<Id, S, G, A>: (context: StoreOnActionListenerContext<Id, S, G, {} extends A ? _ActionsTree : A>) => void

Type parameters ​

NameType
Idextends string
Sextends StateTree
GG
AA

Type declaration ​

▸ (context): void

Argument of store.$onAction()

Parameters ​
NameType
contextStoreOnActionListenerContext<Id, S, G, {} extends A ? _ActionsTree : A>
Returns ​

void


StoreOnActionListenerContext ​

Ƭ StoreOnActionListenerContext<Id, S, G, A>: _ActionsTree extends A ? _StoreOnActionListenerContext<StoreGeneric, string, _ActionsTree> : { [Name in keyof A]: Name extends string ? _StoreOnActionListenerContext<Store<Id, S, G, A>, Name, A> : never }[keyof A]

Context object passed to callbacks of store.$onAction(context => {}) TODO: should have only the Id, the Store and Actions to generate the proper object

Type parameters ​

NameType
Idextends string
Sextends StateTree
GG
AA

StoreState ​

Ƭ StoreState<SS>: SS extends Store<string, infer S, _GettersTree<StateTree>, _ActionsTree> ? UnwrapRef<S> : _ExtractStateFromSetupStore<SS>

Extract the state of a store type. Works with both a Setup Store or an Options Store. Note this unwraps refs.

Type parameters ​

Name
SS

SubscriptionCallback ​

Ƭ SubscriptionCallback<S>: (mutation: SubscriptionCallbackMutation<S>, state: UnwrapRef<S>) => void

Type parameters ​

Name
S

Type declaration ​

▸ (mutation, state): void

Callback of a subscription

Parameters ​
NameType
mutationSubscriptionCallbackMutation<S>
stateUnwrapRef<S>
Returns ​

void


SubscriptionCallbackMutation ​

Ƭ SubscriptionCallbackMutation<S>: SubscriptionCallbackMutationDirect | SubscriptionCallbackMutationPatchObject<S> | SubscriptionCallbackMutationPatchFunction

Context object passed to a subscription callback.

Type parameters ​

Name
S

_ActionsTree ​

Ƭ _ActionsTree: Record<string, _Method>

Type of an object of Actions. For internal usage only. For internal use only


_Awaited ​

Ƭ _Awaited<T>: T extends null | undefined ? T : T extends object & { then: (onfulfilled: F) => any } ? F extends (value: infer V, ...args: any) => any ? _Awaited<V> : never : T

Type parameters ​

Name
T

_DeepPartial ​

Ƭ _DeepPartial<T>: { [K in keyof T]?: _DeepPartial<T[K]> }

Recursive Partial<T>. Used by ['$patch'].

For internal use only

Type parameters ​

Name
T

_ExtractActionsFromSetupStore ​

Ƭ _ExtractActionsFromSetupStore<SS>: SS extends undefined | void ? {} : _ExtractActionsFromSetupStore_Keys<SS> extends keyof SS ? Pick<SS, _ExtractActionsFromSetupStore_Keys<SS>> : never

For internal use only

Type parameters ​

Name
SS

_ExtractActionsFromSetupStore_Keys ​

Ƭ _ExtractActionsFromSetupStore_Keys<SS>: keyof { [K in keyof SS as SS[K] extends _Method ? K : never]: any }

Type that enables refactoring through IDE. For internal use only

Type parameters ​

Name
SS

_ExtractGettersFromSetupStore ​

Ƭ _ExtractGettersFromSetupStore<SS>: SS extends undefined | void ? {} : _ExtractGettersFromSetupStore_Keys<SS> extends keyof SS ? Pick<SS, _ExtractGettersFromSetupStore_Keys<SS>> : never

For internal use only

Type parameters ​

Name
SS

_ExtractGettersFromSetupStore_Keys ​

Ƭ _ExtractGettersFromSetupStore_Keys<SS>: keyof { [K in keyof SS as SS[K] extends ComputedRef ? K : never]: any }

Type that enables refactoring through IDE. For internal use only

Type parameters ​

Name
SS

_ExtractStateFromSetupStore ​

Ƭ _ExtractStateFromSetupStore<SS>: SS extends undefined | void ? {} : _ExtractStateFromSetupStore_Keys<SS> extends keyof SS ? _UnwrapAll<Pick<SS, _ExtractStateFromSetupStore_Keys<SS>>> : never

For internal use only

Type parameters ​

Name
SS

_ExtractStateFromSetupStore_Keys ​

Ƭ _ExtractStateFromSetupStore_Keys<SS>: keyof { [K in keyof SS as SS[K] extends _Method | ComputedRef ? never : K]: any }

Type that enables refactoring through IDE. For internal use only

Type parameters ​

Name
SS

_GettersTree ​

Ƭ _GettersTree<S>: Record<string, (state: UnwrapRef<S> & UnwrapRef<PiniaCustomStateProperties<S>>) => any | () => any>

Type of an object of Getters that infers the argument. For internal usage only. For internal use only

Type parameters ​

NameType
Sextends StateTree

_MapActionsObjectReturn ​

Ƭ _MapActionsObjectReturn<A, T>: { [key in keyof T]: A[T[key]] }

For internal use only

Type parameters ​

NameType
AA
Textends Record<string, keyof A>

_MapActionsReturn ​

Ƭ _MapActionsReturn<A>: { [key in keyof A]: A[key] }

For internal use only

Type parameters ​

Name
A

_MapStateObjectReturn ​

Ƭ _MapStateObjectReturn<Id, S, G, A, T>: { [key in keyof T]: Function }

For internal use only

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
Textends Record<string, keyof S | keyof G | (store: Store<Id, S, G, A>) => any> = {}

_MapStateReturn ​

Ƭ _MapStateReturn<S, G, Keys>: { [key in Keys]: Function }

For internal use only

Type parameters ​

NameType
Sextends StateTree
Gextends _GettersTree<S>
Keysextends keyof S | keyof G = keyof S | keyof G

_MapWritableStateObjectReturn ​

Ƭ _MapWritableStateObjectReturn<S, T>: { [key in keyof T]: Object }

For internal use only

Type parameters ​

NameType
Sextends StateTree
Textends Record<string, keyof S>

_MapWritableStateReturn ​

Ƭ _MapWritableStateReturn<S>: { [key in keyof S]: Object }

For internal use only

Type parameters ​

NameType
Sextends StateTree

_Method ​

Ƭ _Method: (...args: any[]) => any

Type declaration ​

▸ (...args): any

Generic type for a function that can infer arguments and return type

For internal use only

Parameters ​
NameType
...argsany[]
Returns ​

any


_Spread ​

Ƭ _Spread<A>: A extends [infer L, ...(infer R)] ? _StoreObject<L> & _Spread<R> : unknown

For internal use only.

Type parameters ​

NameType
Aextends readonly any[]

_StoreObject ​

Ƭ _StoreObject<S>: S extends StoreDefinition<infer Ids, infer State, infer Getters, infer Actions> ? { [Id in `${Ids}${MapStoresCustomization extends Record<"suffix", infer Suffix> ? Suffix : "Store"}`]: Function } : {}

For internal use only.

Type parameters ​

Name
S

_StoreWithActions ​

Ƭ _StoreWithActions<A>: { [k in keyof A]: A[k] extends Function ? Function : never }

Store augmented for actions. For internal usage only. For internal use only

Type parameters ​

Name
A

_StoreWithGetters ​

Ƭ _StoreWithGetters<G>: { readonly [k in keyof G]: G[k] extends Function ? R : UnwrapRef<G[k]> }

Store augmented with getters. For internal usage only. For internal use only

Type parameters ​

Name
G

_UnwrapAll ​

Ƭ _UnwrapAll<SS>: { [K in keyof SS]: UnwrapRef<SS[K]> }

Type that enables refactoring through IDE. For internal use only

Type parameters ​

Name
SS

Variables ​

PiniaVuePlugin ​

• Const PiniaVuePlugin: Plugin

Vue 2 Plugin that must be installed for pinia to work. Note you don't need this plugin if you are using Nuxt.js. Use the buildModule instead: https://pinia.vuejs.org/ssr/nuxt.html.

Example

js
import Vue from 'vue'
import { PiniaVuePlugin, createPinia } from 'pinia'

Vue.use(PiniaVuePlugin)
const pinia = createPinia()

new Vue({
  el: '#app',
  // ...
  pinia,
})
import Vue from 'vue'
import { PiniaVuePlugin, createPinia } from 'pinia'

Vue.use(PiniaVuePlugin)
const pinia = createPinia()

new Vue({
  el: '#app',
  // ...
  pinia,
})

Param

Vue imported from 'vue'.

Functions ​

acceptHMRUpdate ​

▸ acceptHMRUpdate<Id, S, G, A>(initialUseStore, hot): (newModule: any) => any

Creates an accept function to pass to import.meta.hot in Vite applications.

Type parameters ​

NameType
Idextends string = string
Sextends StateTree = StateTree
Gextends _GettersTree<S> = _GettersTree<S>
A_ActionsTree

Parameters ​

NameTypeDescription
initialUseStoreStoreDefinition<Id, S, G, A>return of the defineStore to hot update
hotanyimport.meta.hot

Returns ​

fn

▸ (newModule): any

Parameters ​
NameType
newModuleany
Returns ​

any

Example

js
const useUser = defineStore(...)
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUser, import.meta.hot))
}
const useUser = defineStore(...)
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUser, import.meta.hot))
}

createPinia ​

▸ createPinia(): Pinia

Creates a Pinia instance to be used by the application

Returns ​

Pinia


defineStore ​

▸ defineStore<Id, S, G, A>(id, options): StoreDefinition<Id, S, G, A>

Creates a useStore function that retrieves the store instance

Type parameters ​

NameType
Idextends string
Sextends StateTree = {}
Gextends _GettersTree<S> = {}
A{}

Parameters ​

NameTypeDescription
idIdid of the store (must be unique)
optionsOmit<DefineStoreOptions<Id, S, G, A>, "id">options to define the store

Returns ​

StoreDefinition<Id, S, G, A>

▸ defineStore<Id, S, G, A>(options): StoreDefinition<Id, S, G, A>

Creates a useStore function that retrieves the store instance

Type parameters ​

NameType
Idextends string
Sextends StateTree = {}
Gextends _GettersTree<S> = {}
A{}

Parameters ​

NameTypeDescription
optionsDefineStoreOptions<Id, S, G, A>options to define the store

Returns ​

StoreDefinition<Id, S, G, A>

▸ defineStore<Id, SS>(id, storeSetup, options?): StoreDefinition<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>

Creates a useStore function that retrieves the store instance

Type parameters ​

NameType
Idextends string
SSSS

Parameters ​

NameTypeDescription
idIdid of the store (must be unique)
storeSetup() => SSfunction that defines the store
options?DefineSetupStoreOptions<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>extra options

Returns ​

StoreDefinition<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>


disposePinia ​

▸ disposePinia(pinia): void

Dispose a Pinia instance by stopping its effectScope and removing the state, plugins and stores. This is mostly useful in tests, with both a testing pinia or a regular pinia and in applications that use multiple pinia instances.

Parameters ​

NameTypeDescription
piniaPiniapinia instance

Returns ​

void


getActivePinia ​

▸ getActivePinia(): undefined | Pinia

Get the currently active pinia if there is any.

Returns ​

undefined | Pinia


mapActions ​

▸ mapActions<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapActionsObjectReturn<A, KeyMapper>

Allows directly using actions from your store without using the composition API (setup()) by generating an object to be spread in the methods field of a component. The values of the object are the actions while the keys are the names of the resulting methods.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
KeyMapperextends Record<string, keyof A>

Parameters ​

NameTypeDescription
useStoreStoreDefinition<Id, S, G, A>store to map from
keyMapperKeyMapperobject to define new names for the actions

Returns ​

_MapActionsObjectReturn<A, KeyMapper>

Example

js
export default {
  methods: {
    // other methods properties
    // useCounterStore has two actions named `increment` and `setCount`
    ...mapActions(useCounterStore, { moar: 'increment', setIt: 'setCount' })
  },

  created() {
    this.moar()
    this.setIt(2)
  }
}
export default {
  methods: {
    // other methods properties
    // useCounterStore has two actions named `increment` and `setCount`
    ...mapActions(useCounterStore, { moar: 'increment', setIt: 'setCount' })
  },

  created() {
    this.moar()
    this.setIt(2)
  }
}

▸ mapActions<Id, S, G, A>(useStore, keys): _MapActionsReturn<A>

Allows directly using actions from your store without using the composition API (setup()) by generating an object to be spread in the methods field of a component.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA

Parameters ​

NameTypeDescription
useStoreStoreDefinition<Id, S, G, A>store to map from
keyskeyof A[]array of action names to map

Returns ​

_MapActionsReturn<A>

Example

js
export default {
  methods: {
    // other methods properties
    ...mapActions(useCounterStore, ['increment', 'setCount'])
  },

  created() {
    this.increment()
    this.setCount(2) // pass arguments as usual
  }
}
export default {
  methods: {
    // other methods properties
    ...mapActions(useCounterStore, ['increment', 'setCount'])
  },

  created() {
    this.increment()
    this.setCount(2) // pass arguments as usual
  }
}

mapGetters ​

▸ mapGetters<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapStateObjectReturn<Id, S, G, A, KeyMapper>

Alias for mapState(). You should use mapState() instead.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
KeyMapperextends Record<string, keyof S | keyof G | (store: Store<Id, S, G, A>) => any>

Parameters ​

NameType
useStoreStoreDefinition<Id, S, G, A>
keyMapperKeyMapper

Returns ​

_MapStateObjectReturn<Id, S, G, A, KeyMapper>

Deprecated

use mapState() instead.

▸ mapGetters<Id, S, G, A, Keys>(useStore, keys): _MapStateReturn<S, G, Keys>

Alias for mapState(). You should use mapState() instead.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
Keysextends string | number | symbol

Parameters ​

NameType
useStoreStoreDefinition<Id, S, G, A>
keysreadonly Keys[]

Returns ​

_MapStateReturn<S, G, Keys>

Deprecated

use mapState() instead.


mapState ​

▸ mapState<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapStateObjectReturn<Id, S, G, A, KeyMapper>

Allows using state and getters from one store without using the composition API (setup()) by generating an object to be spread in the computed field of a component. The values of the object are the state properties/getters while the keys are the names of the resulting computed properties. Optionally, you can also pass a custom function that will receive the store as its first argument. Note that while it has access to the component instance via this, it won't be typed.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
KeyMapperextends Record<string, keyof S | keyof G | (store: Store<Id, S, G, A>) => any>

Parameters ​

NameTypeDescription
useStoreStoreDefinition<Id, S, G, A>store to map from
keyMapperKeyMapperobject of state properties or getters

Returns ​

_MapStateObjectReturn<Id, S, G, A, KeyMapper>

Example

js
export default {
  computed: {
    // other computed properties
    // useCounterStore has a state property named `count` and a getter `double`
    ...mapState(useCounterStore, {
      n: 'count',
      triple: store => store.n * 3,
      // note we can't use an arrow function if we want to use `this`
      custom(store) {
        return this.someComponentValue + store.n
      },
      doubleN: 'double'
    })
  },

  created() {
    this.n // 2
    this.doubleN // 4
  }
}
export default {
  computed: {
    // other computed properties
    // useCounterStore has a state property named `count` and a getter `double`
    ...mapState(useCounterStore, {
      n: 'count',
      triple: store => store.n * 3,
      // note we can't use an arrow function if we want to use `this`
      custom(store) {
        return this.someComponentValue + store.n
      },
      doubleN: 'double'
    })
  },

  created() {
    this.n // 2
    this.doubleN // 4
  }
}

▸ mapState<Id, S, G, A, Keys>(useStore, keys): _MapStateReturn<S, G, Keys>

Allows using state and getters from one store without using the composition API (setup()) by generating an object to be spread in the computed field of a component.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
Keysextends string | number | symbol

Parameters ​

NameTypeDescription
useStoreStoreDefinition<Id, S, G, A>store to map from
keysreadonly Keys[]array of state properties or getters

Returns ​

_MapStateReturn<S, G, Keys>

Example

js
export default {
  computed: {
    // other computed properties
    ...mapState(useCounterStore, ['count', 'double'])
  },

  created() {
    this.count // 2
    this.double // 4
  }
}
export default {
  computed: {
    // other computed properties
    ...mapState(useCounterStore, ['count', 'double'])
  },

  created() {
    this.count // 2
    this.double // 4
  }
}

mapStores ​

▸ mapStores<Stores>(...stores): _Spread<Stores>

Allows using stores without the composition API (setup()) by generating an object to be spread in the computed field of a component. It accepts a list of store definitions.

Type parameters ​

NameType
Storesextends any[]

Parameters ​

NameTypeDescription
...stores[...Stores[]]list of stores to map to an object

Returns ​

_Spread<Stores>

Example

js
export default {
  computed: {
    // other computed properties
    ...mapStores(useUserStore, useCartStore)
  },

  created() {
    this.userStore // store with id "user"
    this.cartStore // store with id "cart"
  }
}
export default {
  computed: {
    // other computed properties
    ...mapStores(useUserStore, useCartStore)
  },

  created() {
    this.userStore // store with id "user"
    this.cartStore // store with id "cart"
  }
}

mapWritableState ​

▸ mapWritableState<Id, S, G, A, KeyMapper>(useStore, keyMapper): _MapWritableStateObjectReturn<S, KeyMapper>

Same as mapState() but creates computed setters as well so the state can be modified. Differently from mapState(), only state properties can be added.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
KeyMapperextends Record<string, keyof S>

Parameters ​

NameTypeDescription
useStoreStoreDefinition<Id, S, G, A>store to map from
keyMapperKeyMapperobject of state properties

Returns ​

_MapWritableStateObjectReturn<S, KeyMapper>

▸ mapWritableState<Id, S, G, A, Keys>(useStore, keys): { [K in Keys]: Object }

Allows using state and getters from one store without using the composition API (setup()) by generating an object to be spread in the computed field of a component.

Type parameters ​

NameType
Idextends string
Sextends StateTree
Gextends _GettersTree<S>
AA
Keysextends string | number | symbol

Parameters ​

NameTypeDescription
useStoreStoreDefinition<Id, S, G, A>store to map from
keysreadonly Keys[]array of state properties

Returns ​

{ [K in Keys]: Object }


setActivePinia ​

▸ setActivePinia(pinia): Pinia

Sets or unsets the active pinia. Used in SSR and internally when calling actions and getters

Parameters ​

NameTypeDescription
piniaPiniaPinia instance

Returns ​

Pinia

▸ setActivePinia(pinia): undefined

Sets or unsets the active pinia. Used in SSR and internally when calling actions and getters

Parameters ​

NameTypeDescription
piniaundefinedPinia instance

Returns ​

undefined

▸ setActivePinia(pinia): undefined | Pinia

Sets or unsets the active pinia. Used in SSR and internally when calling actions and getters

Parameters ​

NameTypeDescription
piniaundefined | PiniaPinia instance

Returns ​

undefined | Pinia


setMapStoreSuffix ​

▸ setMapStoreSuffix(suffix): void

Changes the suffix added by mapStores(). Can be set to an empty string. Defaults to "Store". Make sure to extend the MapStoresCustomization interface if you are using TypeScript.

Parameters ​

NameTypeDescription
suffixstringnew suffix

Returns ​

void


skipHydrate ​

▸ skipHydrate<T>(obj): T

Tells Pinia to skip the hydration process of a given object. This is useful in setup stores (only) when you return a stateful object in the store but it isn't really state. e.g. returning a router instance in a setup store.

Type parameters ​

NameType
Tany

Parameters ​

NameTypeDescription
objTtarget object

Returns ​

T

obj


storeToRefs ​

▸ storeToRefs<SS>(store): StoreToRefs<SS>

Creates an object of references with all the state, getters, and plugin-added state properties of the store. Similar to toRefs() but specifically designed for Pinia stores so methods and non reactive properties are completely ignored.

Type parameters ​

NameType
SSextends StoreGeneric

Parameters ​

NameTypeDescription
storeSSstore to extract the refs from

Returns ​

StoreToRefs<SS>

Released under the MIT License.