Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 38 ยท Stores and State

State Basics

Learn how Pinia state works: define it as a function, read and write it from components, use arrays and objects, understand reactivity rules and add new state safely.

State is the heart of a store: the data your app is about. In Pinia, state is defined in a function, becomes reactive automatically, and can be read and changed from anywhere you have the store. This lesson covers the rules and the traps, so your state behaves the way you expect.

Defining state

State is an arrow function that returns an object. Each property is a piece of state, and its initial value defines its type if you use TypeScript:

JavaScript
export const useSettingsStore = defineStore("settings", {
  state: () => ({
    theme: "light",
    fontSize: 16,
    notifications: { email: true, push: false },
    recentSearches: [],
    user: null,
  }),
});

Two points:

  • Declare every property up front, even when its value is null or an empty array. Pinia tracks properties that exist when the state is created. A property you invent later by assignment is not part of the state definition (see "adding new state" below).
  • Initial values are copied for every app instance, because state is a function. Never write state: { ... } as a plain object.

Reading state

The store is a reactive object, so you read state as properties:

VUE
<script setup>
import { useSettingsStore } from "@/stores/settings";
const settings = useSettingsStore();
</script>

<template>
  <p>Theme: {{ settings.theme }}</p>
  <p>Email alerts: {{ settings.notifications.email ? "on" : "off" }}</p>
</template>

Reading in a template or in a computed or watch tracks the property. Vue re-runs those when the value changes. Reading it once in plain code, such as const t = settings.theme, just copies the value at that moment.

Writing state

You can assign directly:

JavaScript
settings.theme = "dark";
settings.notifications.push = true;
settings.recentSearches.push("pinia");

Direct assignment is allowed on purpose. Pinia removed Vuex's mutations, so any code with access to the store can change state. For small changes that is convenient. For anything with business rules, such as "a cart cannot have a negative quantity", put the rule in an action so that it lives in one place (Actions). A good guideline: components may toggle simple UI fields directly, and anything that matters goes through an action.

Try it. The inputs below write straight into state with v-model, while the checkbox and the nested object show that deep changes are reactive too.

Reading and writing state

Arrays and objects

State is deeply reactive: nested objects and arrays are tracked, and array methods such as push, splice and sort all trigger updates. You can replace a whole value too:

JavaScript
store.items = store.items.filter((item) => !item.done);
store.user = { id: 7, name: "Grace" };

Replacing a reference is fine because the store is a reactive object, and the property holds the new value reactively.

Adding new state later

If you add a property that was never declared in state(), it is not part of the store state. It will not appear in pinia.state.value, in DevTools, in SSR payloads, or after a reset. Declare everything in state(), using null for "not loaded yet":

JavaScript
state: () => ({
  profile: null,   // later: { name: "...", ... }
  loaded: false,
}),

Do not do store.extra = 123 for something you want to keep. It might work in a component for a moment, but it is invisible to the rest of Pinia. Declare the field in state() instead.

State typed as nullable

A common pattern: data that is missing until a request finishes. Use null and check for it in the template:

State that starts as null

Access to the whole state

Every store exposes store.$state, an object with all state properties. It is handy for debugging, serializing or replacing the state wholesale:

JavaScript
console.log(JSON.stringify(store.$state));
store.$state = { theme: "dark", fontSize: 18, notifications: { email: false, push: false }, recentSearches: [] };

Assigning to $state does not replace the object; Pinia patches each property. See Patching and Resetting State for better tools than assignment.

Do not destructure

Pulling a value out of a store copies it and breaks the link:

JavaScript
const { theme } = useSettingsStore(); // theme is just a string now

Use storeToRefs() to destructure safely: that is the topic of the next lesson.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is state a function in Pinia?

    A function returns a new object each time, avoiding shared mutable state between apps and requests.
  2. 2. What happens to a property you add with store.extra = 1 that was not declared in state()?

    Only properties returned by state() are part of the state. Declare every field up front.
  3. 3. Is changing state directly from a component allowed in Pinia?

    Pinia has no mutations, so direct writes work. Put business rules in actions to keep them in one place.
  4. 4. Which is the best initial value for data that is loaded later?

    Declaring it with null makes the property part of the state, and templates can check for it.

Summary

  • state is a function returning an object; declare every property up front.
  • State is deeply reactive: assign, push and splice all update the UI.
  • Direct writes are allowed; use actions for rules that matter.
  • Properties added later are not tracked state; use null placeholders.
  • store.$state holds the whole state; never destructure the store directly.

Next: Destructuring Stores with storeToRefs