Vue

Use TanStack Store in Vue applications

TanStack Store provides Vue support through the @tanstack/vue-store package, which integrates with Vue’s reactivity system using composables. It supports both Vue 2.7+ and Vue 3.

Installation

Install the Vue adapter package:

npm

npm install @tanstack/vue-store

The @tanstack/vue-store package re-exports everything from @tanstack/store, so you only need to install the Vue package.

Vue Version Compatibility

The package uses vue-demi to support multiple Vue versions:

• Vue 3.x (recommended)
• Vue 2.7+
• Vue 2.6 with @vue/composition-api

Basic Usage

The primary way to use TanStack Store in Vue is through the useStore composable:

<script setup lang="ts">
import { createStore, useStore } from '@tanstack/vue-store'

// Create a store
const counterStore = createStore({
  count: 0,
})

// Subscribe to the store
const count = useStore(counterStore, (state) => state.count)

const increment = () => {
  counterStore.setState((prev) => ({ count: prev.count + 1 }))
}
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button @click="increment">Increment</button>
  </div>
</template>

The useStore Composable

The useStore composable subscribes your component to store updates and returns a readonly ref that automatically updates.

Signature

function useStore<TState, TSelected>(
  store: Atom<TState> | ReadonlyAtom<TState>,
  selector?: (state: TState) => TSelected,
  options?: { equal?: (a: TSelected, b: TSelected) => boolean }
): Readonly<Ref<TSelected>>

Parameters

• store - The store instance to subscribe to
• selector - (Optional) A function that selects which part of the state you need. Defaults to returning the entire state
• options.equal - (Optional) A custom equality function. Defaults to shallow

Return Value

Returns a readonly Vue Ref containing the selected state. Use .value to access the state value in script, or directly in templates.

Selector Optimization

The selector function allows you to subscribe to only the parts of state you need:

<script setup lang="ts">
import { createStore, useStore } from '@tanstack/vue-store'

const appStore = createStore({
  user: { name: 'Alice', age: 30 },
  settings: { theme: 'dark', notifications: true },
})

// Only updates when user.name changes
const userName = useStore(appStore, (state) => state.user.name)

// Only updates when settings change
const settings = useStore(appStore, (state) => state.settings)
</script>

<template>
  <div>
    <h1>Welcome, {{ userName }}!</h1>
    <div>
      <p>Theme: {{ settings.theme }}</p>
      <p>Notifications: {{ settings.notifications ? 'On' : 'Off' }}</p>
    </div>
  </div>
</template>

Custom Equality Functions

For complex state selections, provide a custom equality function:

<script setup lang="ts">
import { createStore, useStore } from '@tanstack/vue-store'

const todoStore = createStore({
  todos: [
    { id: 1, text: 'Buy groceries', completed: false },
    { id: 2, text: 'Walk the dog', completed: true },
  ],
})

function deepEqual<T>(a: T, b: T): boolean {
  return JSON.stringify(a) === JSON.stringify(b)
}

// Use deep equality for array comparison
const activeTodos = useStore(
  todoStore,
  (state) => state.todos.filter((todo) => !todo.completed),
  { equal: deepEqual }
)
</script>

<template>
  <ul>
    <li v-for="todo in activeTodos" :key="todo.id">
      {{ todo.text }}
    </li>
  </ul>
</template>

Shallow Equality

The package exports a shallow utility for shallow object comparison (this is the default):

<script setup lang="ts">
import { createStore, useStore, shallow } from '@tanstack/vue-store'

const userStore = createStore({
  profile: { name: 'Alice', email: '[e-mail]' },
  preferences: { theme: 'dark' },
})

// Explicitly use shallow comparison (this is the default)
const profile = useStore(
  userStore,
  (state) => state.profile,
  { equal: shallow }
)
</script>

<template>
  <div>
    <h2>{{ profile.name }}</h2>
    <p>{{ profile.email }}</p>
  </div>
</template>

Complete Example: Todo App

Here’s a complete Todo application using Vue 3 Composition API:

<script setup lang="ts">
import { ref } from 'vue'
import { createStore, useStore } from '@tanstack/vue-store'

interface Todo {
  id: number
  text: string
  completed: boolean
}

interface TodoState {
  todos: Todo[]
  filter: 'all' | 'active' | 'completed'
}

const todoStore = createStore<TodoState>({
  todos: [],
  filter: 'all',
})

// Actions
const addTodo = (text: string) => {
  todoStore.setState((state) => ({
    ...state,
    todos: [
      ...state.todos,
      { id: Date.now(), text, completed: false },
    ],
  }))
}

const toggleTodo = (id: number) => {
  todoStore.setState((state) => ({
    ...state,
    todos: state.todos.map((todo) =>
      todo.id === id ? { ...todo, completed: !todo.completed } : todo
    ),
  }))
}

const setFilter = (filter: TodoState['filter']) => {
  todoStore.setState((state) => ({ ...state, filter }))
}

// Component state
const input = ref('')

// Subscribe to store
const filter = useStore(todoStore, (state) => state.filter)
const todos = useStore(todoStore, (state) => {
  const { todos, filter } = state
  if (filter === 'active') return todos.filter((t) => !t.completed)
  if (filter === 'completed') return todos.filter((t) => t.completed)
  return todos
})

const handleSubmit = () => {
  if (input.value.trim()) {
    addTodo(input.value)
    input.value = ''
  }
}
</script>

<template>
  <div>
    <h1>Todo App</h1>
    
    <form @submit.prevent="handleSubmit">
      <input
        v-model="input"
        placeholder="What needs to be done?"
      />
      <button type="submit">Add</button>
    </form>

    <div>
      <button @click="setFilter('all')">All</button>
      <button @click="setFilter('active')">Active</button>
      <button @click="setFilter('completed')">Completed</button>
    </div>

    <ul>
      <li v-for="todo in todos" :key="todo.id">
        <input
          type="checkbox"
          :checked="todo.completed"
          @change="toggleTodo(todo.id)"
        />
        <span :style="{ textDecoration: todo.completed ? 'line-through' : 'none' }">
          {{ todo.text }}
        </span>
      </li>
    </ul>
  </div>
</template>

Options API Support

While the Composition API is recommended, you can use stores with the Options API:

<script lang="ts">
import { defineComponent } from 'vue'
import { createStore, useStore } from '@tanstack/vue-store'

const counterStore = createStore({ count: 0 })

export default defineComponent({
  setup() {
    const count = useStore(counterStore, (state) => state.count)
    
    return {
      count,
      increment: () => counterStore.setState((prev) => ({ count: prev.count + 1 }))
    }
  },
})
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button @click="increment">Increment</button>
  </div>
</template>

Vue-Specific Considerations

Reactivity System Integration

The Vue adapter integrates deeply with Vue’s reactivity system:

• Uses watch to subscribe to store changes
• Returns readonly refs to prevent accidental mutations
• Automatically cleans up subscriptions when components unmount

Server-Side Rendering (SSR)

TanStack Store works with Vue SSR. Create stores at module level and initialize them with server data:

import { createStore } from '@tanstack/vue-store'

// Create store at module level
export const appStore = createStore({
  data: null,
  isLoading: false,
})

// Initialize with SSR data
export function initializeStore(initialData: any) {
  appStore.setState({ data: initialData, isLoading: false })
}

Nuxt Integration

For Nuxt 3, create a plugin to initialize stores:

// plugins/store.ts
import { appStore } from '~/stores/app'

export default defineNuxtPlugin(() => {
  // Initialize your stores here if needed
})

Performance Tips

1. Use selective subscriptions: Subscribe only to the state you need
2. Leverage the default shallow equality: It works well for most cases
3. Create focused stores: Multiple small stores perform better than one large store
4. Use computed refs: For derived state within components, use Vue’s computed

Derived Stores

Create derived stores that react to other stores:

<script setup lang="ts">
import { createStore, useStore } from '@tanstack/vue-store'

const countStore = createStore(0)
const doubleStore = createStore(() => ({ value: countStore.state * 2 }))

const count = useStore(countStore, (state) => state)
const double = useStore(doubleStore, (state) => state.value)

const increment = () => {
  countStore.setState((prev) => prev + 1)
}
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double: {{ double }}</p>
    <button @click="increment">Increment</button>
  </div>
</template>

API Reference

For detailed API documentation, see:

• • useStore - Vue composable for subscribing to stores
• • shallow - Shallow equality comparison utility
• createStore - Core store creation API

TypeScript Support

The Vue adapter provides full TypeScript support:

<script setup lang="ts">
import { createStore, useStore } from '@tanstack/vue-store'

interface AppState {
  user: { name: string; id: number }
  isAuthenticated: boolean
}

const store = createStore<AppState>({
  user: { name: '', id: 0 },
  isAuthenticated: false,
})

// TypeScript infers the correct types
const userName = useStore(store, (state) => state.user.name)
// userName is Readonly<Ref<string>>
</script>

<template>
  <div>{{ userName }}</div>
</template>