Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 38 ยท Getting Started

What Is Pinia?

Learn what Pinia is, what problem a store solves, how shared state differs from local component state, and see a real Pinia store run live in the browser.

Every Vue app starts with state that lives inside one component: a counter, the text in an input, a flag that opens a menu. That is fine until two distant components need the same data. The shopping cart badge in the header and the "Add to cart" button three levels down both need the cart. The login name shown in the navbar and the settings page both need the current user.

Pinia is the official state management library for Vue 3. It gives your app a place to keep shared data, called a store, and a small, predictable set of tools to read and change it. You define a store once, and any component can use it.

This lesson explains the problem Pinia solves, shows what a store is made of, and runs a real Pinia store in the browser so that you can see it work before you learn the details.

The problem: state that must be shared

Vue components talk to each other in two directions. Parents pass data down with props. Children tell parents about things with events that go up. For siblings and distant relatives, you end up routing everything through the nearest common ancestor.

flowchart TD
    A["App (owns the cart)"] --> B["Header"]
    A --> C["ProductList"]
    C --> D["ProductCard"]
    D --> E["AddToCartButton"]
    B --> F["CartBadge"]
    E -. "event up, event up, event up" .-> A
    A -. "prop down" .-> B
    B -. "prop down" .-> F

Without a shared store, the button must emit through every layer to reach the owner of the cart, and the badge must receive the cart through props.

Passing props through components that do not use them is called prop drilling. It makes components harder to reuse and every refactor touches many files. A store breaks the chain: both the button and the badge talk to the same store directly.

flowchart TD
    S[("Cart store")]
    E["AddToCartButton"] -->|"calls addItem()"| S
    S -->|"count"| F["CartBadge"]

With a store, components read and write one shared source of truth. They do not need to know about each other.

What a store contains

A Pinia store has three kinds of members. If you know Vue's Options API they will feel familiar:

Part What it is Vue equivalent
state The data the store holds data / ref
getters Values calculated from state computed
actions Functions that change state or do work methods

State is reactive, so whenever a component reads store.count in its template, Vue re-renders it when the value changes. Getters are cached like computed properties. Actions can be asynchronous, so they are the natural home for API calls.

There is no separate "mutations" layer as in the older Vuex library. You can change state directly from an action, or even from a component. Pinia compared with Vuex and other options discusses that choice.

A first live example

The example below is a complete working app using the real Pinia library. Do not worry about every line yet. Notice three things: defineStore creates a store, a component calls useCounterStore() to get it, and the template reads counter.count and calls counter.increment().

The small localStorage script at the top is explained in Installing and Setting Up Pinia. Press Run and click the button.

A store with state, a getter and an action

The same store works in any number of components. The next example mounts two separate components, a display and a button, that never mention each other. They only share the store.

Two components, one store

Click the buttons: the badge updates even though AddButtons never passes anything to it.

When you need Pinia (and when you do not)

Not every piece of data belongs in a store. A good rule: start with local state (ref inside the component), lift it into a composable if several components share logic, and move it to Pinia when several unrelated components need the same instance of the data.

Good candidates for a store:

  • The signed-in user and their permissions
  • A shopping cart or a wishlist
  • Application settings such as theme and language
  • Data fetched once and used on several pages
  • Notifications or a global loading indicator

Poor candidates: the text of a single input, whether one dropdown is open, or anything that is reset every time its component is created. Keeping these local makes components simpler.

If you have not met ref, reactive and computed yet, read Reactive State with ref and Computed Properties first. A store is mostly those three ideas in a shared container.

What you get beyond a hand-made store

You can build a shared store yourself with a module-level reactive object (see Building a Simple Store). Pinia adds the parts that become painful at scale:

  • Vue DevTools integration: inspect state, time-travel and edit values live.
  • Hot module replacement: edit a store and see the change without reloading the page.
  • Server-side rendering support: one set of stores per request, with state transfer to the browser.
  • Plugins: add behavior to every store, such as saving to local storage.
  • TypeScript support: types flow from your store definition without extra annotations.
  • A tiny footprint: around 1.5 KB gzipped for the core ideas, and it is tree-shakable.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What problem does a store mainly solve?

    A store is a shared source of truth, so distant components can read and change the same data without prop drilling.
  2. 2. Which three parts make up a Pinia store?

    State holds data, getters derive values from it, and actions are functions that change it or do work.
  3. 3. Where should the text of a single search input that only one component uses live?

    Local state keeps simple components simple. Move data to a store only when several unrelated components share the same instance.
  4. 4. Which Vuex concept does Pinia not need?

    Pinia has no mutations. Actions, or even direct assignment, change the state.

Summary

  • Pinia is the official Vue 3 library for shared, reactive state.
  • A store has state, getters and actions, and any component can use it.
  • Stores remove prop drilling: unrelated components share one source of truth.
  • Keep truly local data in components; use a store when many components need the same instance.
  • Pinia adds DevTools, HMR, SSR support, plugins and TypeScript types on top of a hand-made store.

Next: Installing and Setting Up Pinia