Pinia

API Documentation / pinia

Module: pinia

Enumerations

Interfaces

Type aliases

PiniaStorePlugin

Ƭ PiniaStorePlugin: PiniaPlugin

Plugin to extend every store.

deprecated use PiniaPlugin instead

Defined in

packages/pinia/src/rootStore.ts:149

StateTree

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

Generic state of a Store

Defined in

packages/pinia/src/types.ts:13

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{}

Defined in

packages/pinia/src/types.ts:463

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

Defined in

packages/pinia/src/store.ts:744

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.

Defined in

packages/pinia/src/types.ts:482

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

Defined in

packages/pinia/src/store.ts:757

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

Defined in

packages/pinia/src/types.ts:236

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

Defined in

packages/pinia/src/types.ts:220

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

Defined in

packages/pinia/src/store.ts:770

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

Defined in

packages/pinia/src/types.ts:148

SubscriptionCallbackMutation

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

Context object passed to a subscription callback.

Type parameters

Name
S

Defined in

packages/pinia/src/types.ts:140

_ActionsTree

Ƭ _ActionsTree: Record<string, _Method>

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

Defined in

packages/pinia/src/types.ts:548

_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

Defined in

packages/pinia/src/types.ts:164

_DeepPartial

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

Recursive Partial<T>. Used by {@link Store.$patch}.

For internal use only

Type parameters

Name
T

Defined in

packages/pinia/src/types.ts:35

_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

Defined in

packages/pinia/src/types.ts:592

_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

Defined in

packages/pinia/src/types.ts:562

_ExtractGettersFromSetupStore

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

For internal use only

Type parameters

Name
SS

Defined in

packages/pinia/src/types.ts:601

_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

Defined in

packages/pinia/src/types.ts:570

_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

Defined in

packages/pinia/src/types.ts:583

_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

Defined in

packages/pinia/src/types.ts:554

_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

Defined in

packages/pinia/src/types.ts:538

_MapActionsObjectReturn

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

For internal use only

Type parameters

NameType
AA
Textends Record<string, keyof A>

Defined in

packages/pinia/src/mapHelpers.ts:297

_MapActionsReturn

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

For internal use only

Type parameters

Name
A

Defined in

packages/pinia/src/mapHelpers.ts:290

_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> = {}

Defined in

packages/pinia/src/mapHelpers.ts:141

_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

Defined in

packages/pinia/src/mapHelpers.ts:125

_MapWritableStateObjectReturn

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

For internal use only

Type parameters

NameType
Sextends StateTree
Textends Record<string, keyof S>

Defined in

packages/pinia/src/mapHelpers.ts:422

_MapWritableStateReturn

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

For internal use only

Type parameters

NameType
Sextends StateTree

Defined in

packages/pinia/src/mapHelpers.ts:412

_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

Defined in

packages/pinia/src/types.ts:432

_Spread

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

For internal use only.

Type parameters

NameType
Aextends readonly any[]

Defined in

packages/pinia/src/mapHelpers.ts:53

_StoreObject

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

For internal use only.

Type parameters

Name
S

Defined in

packages/pinia/src/mapHelpers.ts:25

_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

Defined in

packages/pinia/src/types.ts:444

_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

Defined in

packages/pinia/src/types.ts:454

_UnwrapAll

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

Type that enables refactoring through IDE. For internal use only

Type parameters

Name
SS

Defined in

packages/pinia/src/types.ts:578

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

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'.

Defined in

packages/pinia/src/vue2-plugin.ts:28

Functions

acceptHMRUpdate

▸ acceptHMRUpdate(initialUseStore, hot): (newModule: any) => any

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

example

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

Parameters

NameTypeDescription
initialUseStoreStoreDefinition<string, StateTree, _GettersTree<StateTree>, _ActionsTree>return of the defineStore to hot update
hotanyimport.meta.hot

Returns

fn

▸ (newModule): any

Parameters
NameType
newModuleany
Returns

any

Defined in

packages/pinia/src/hmr.ts:73

createPinia

▸ createPinia(): Pinia

Creates a Pinia instance to be used by the application

Returns

Pinia

Defined in

packages/pinia/src/createPinia.ts:10

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>

Defined in

packages/pinia/src/store.ts:793

▸ 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>

Defined in

packages/pinia/src/store.ts:809

▸ 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>>

Defined in

packages/pinia/src/store.ts:824

getActivePinia

▸ getActivePinia(): undefined | Pinia

Get the currently active pinia if there is any.

Returns

undefined | Pinia

Defined in

packages/pinia/src/rootStore.ts:39

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.

example

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)
  }
}

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>

Defined in

packages/pinia/src/mapHelpers.ts:326

▸ 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.

example

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

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

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>

Defined in

packages/pinia/src/mapHelpers.ts:359

mapGetters

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

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

deprecated 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>

Defined in

packages/pinia/src/mapHelpers.ts:285

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

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

deprecated 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>

Defined in

packages/pinia/src/mapHelpers.ts:285

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.

example

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
  }
}

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>

Defined in

packages/pinia/src/mapHelpers.ts:194

▸ 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.

example

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

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

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>

Defined in

packages/pinia/src/mapHelpers.ts:231

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.

example

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

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

Type parameters

NameType
Storesextends any[]

Parameters

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

Returns

_Spread<Stores>

Defined in

packages/pinia/src/mapHelpers.ts:96

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>

Defined in

packages/pinia/src/mapHelpers.ts:440

▸ mapWritableState<Id, S, G, A>(useStore, keys): _MapWritableStateReturn<S>

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

Parameters

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

Returns

_MapWritableStateReturn<S>

Defined in

packages/pinia/src/mapHelpers.ts:458

setActivePinia

▸ 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

Defined in

packages/pinia/src/rootStore.ts:33

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

Defined in

packages/pinia/src/mapHelpers.ts:66

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

Defined in

packages/pinia/src/store.ts:94

storeToRefs

▸ storeToRefs<SS>(store): ToRefs<StoreState<SS> & StoreGetters<SS> & PiniaCustomStateProperties<StoreState<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 _StoreWithState<string, StateTree, _GettersTree<StateTree>, _ActionsTree, SS> & StateTree & _StoreWithGetters<_GettersTree<StateTree>> & PiniaCustomProperties<string, StateTree, _GettersTree<StateTree>, _ActionsTree, SS> & PiniaCustomStateProperties<StateTree, SS>

Parameters

NameTypeDescription
storeSSstore to extract the refs from

Returns

ToRefs<StoreState<SS> & StoreGetters<SS> & PiniaCustomStateProperties<StoreState<SS>>>

Defined in

packages/pinia/src/storeToRefs.ts:21