Skip to main content

​
Quickstart Guide

Get up and running with TanStack Store in minutes. This guide walks you through creating your first store and integrating it with your framework.

​
Your First Store

Let’s create a simple counter application to demonstrate the core concepts.
1

Install TanStack Store

First, install the appropriate package for your framework:
npm install @tanstack/react-store
2

Create a Store

Create a store to manage your application state. Stores can be created inside or outside of components:
import { Store } from '@tanstack/react-store'

// Create a store with initial state
export const store = new Store({
  dogs: 0,
  cats: 0,
})
Stores can be instantiated outside of components and shared across your entire application.
3

Read Store State

Use the framework adapter’s hook/composable to read from the store. Only the specific data you select will trigger re-renders:
import { useStore } from '@tanstack/react-store'
import { store } from './store'

function Display({ animal }: { animal: 'dogs' | 'cats' }) {
  // This component only re-renders when state[animal] changes
  const count = useStore(store, (state) => state[animal])
  
  return <div>{animal}: {count}</div>
}
The selector function enables fine-grained subscriptions. Components only re-render when their selected data changes, not when any part of the store updates.
4

Update Store State

Update the store state using setState. Updates are immutable and trigger subscriptions:
import { store } from './store'

function Increment({ animal }: { animal: 'dogs' | 'cats' }) {
  const updateCount = () => {
    store.setState((state) => ({
      ...state,
      [animal]: state[animal] + 1,
    }))
  }

  return (
    <button onClick={updateCount}>
      My Friend Likes {animal}
    </button>
  )
}
5

Compose Your Application

Bring it all together in your application:
function App() {
  return (
    <div>
      <h1>How many of your friends like cats or dogs?</h1>
      <p>
        Press one of the buttons to add a counter of how many of your friends
        like cats or dogs
      </p>
      <Increment animal="dogs" />
      <Display animal="dogs" />
      <Increment animal="cats" />
      <Display animal="cats" />
    </div>
  )
}

​
Core Concepts

Now that you’ve built your first store, let’s explore the key concepts:

​
Creating Stores

You can create stores with values or functions: 
import { createStore } from '@tanstack/store'

// Store with a value
const countStore = createStore(0)

// Store with an object
const userStore = createStore({
  name: 'John',
  age: 30,
})

​
Derived Stores

Create stores that compute values from other stores: 
const count = createStore(5)

// Derived store automatically updates when count changes
const double = createStore(() => count.state * 2)

console.log(double.state) // 10
count.setState(() => 10)
console.log(double.state) // 20
You can access the previous computed value: 
const count = createStore(1)

const sum = createStore<number>((prev) => {
  return count.state + (prev ?? 0)
})

console.log(sum.state) // 1
count.setState(() => 2)
console.log(sum.state) // 3

​
Subscriptions

Subscribe to store changes for side effects: 
const count = createStore(0)

const { unsubscribe } = count.subscribe((state) => {
  console.log('Count changed to:', state)
})

count.setState(() => 5) // Logs: "Count changed to: 5"

// Cleanup
unsubscribe()

​
Batched Updates

Batch multiple updates to trigger subscribers only once: 
import { batch } from '@tanstack/store'

const countStore = createStore(0)

// Subscribers will only trigger once with the final value
batch(() => {
  countStore.setState(() => 1)
  countStore.setState(() => 2)
})

console.log(countStore.state) // 2

​
Framework-Specific Examples

​
React Complete Example

Here’s the complete React example from the source code: 
import ReactDOM from 'react-dom/client'
import { Store, useStore } from '@tanstack/react-store'

// Create store outside of components
export const store = new Store({
  dogs: 0,
  cats: 0,
})

// Display component with fine-grained subscriptions
const Display = ({ animal }: { animal: 'dogs' | 'cats' }) => {
  const count = useStore(store, (state) => state[animal])
  return <div>{`${animal}: ${count}`}</div>
}

// Update helper
const updateState = (animal: 'dogs' | 'cats') => {
  store.setState((state) => ({
    ...state,
    [animal]: state[animal] + 1,
  }))
}

// Increment component
const Increment = ({ animal }: { animal: 'dogs' | 'cats' }) => (
  <button onClick={() => updateState(animal)}>
    My Friend Likes {animal}
  </button>
)

function App() {
  return (
    <div>
      <h1>How many of your friends like cats or dogs?</h1>
      <Increment animal="dogs" />
      <Display animal="dogs" />
      <Increment animal="cats" />
      <Display animal="cats" />
    </div>
  )
}

const root = ReactDOM.createRoot(document.getElementById('root')!)
root.render(<App />)

​
Vue Complete Example

<!-- store.ts -->
<script lang="ts">
import { Store } from '@tanstack/vue-store'

export const store = new Store({
  dogs: 0,
  cats: 0,
})

export function updateState(animal: 'dogs' | 'cats') {
  store.setState((state) => ({
    ...state,
    [animal]: state[animal] + 1,
  }))
}
</script>

<!-- Display.vue -->
<script setup>
import { useStore } from '@tanstack/vue-store'
import { store } from './store'

const props = defineProps({ animal: String })
const count = useStore(store, (state) => state[props.animal])
</script>

<template>
  <div>{{ animal }}: {{ count }}</div>
</template>

<!-- App.vue -->
<script setup>
import Increment from './Increment.vue'
import Display from './Display.vue'
</script>

<template>
  <h1>How many of your friends like cats or dogs?</h1>
  <Increment animal="dogs" />
  <Display animal="dogs" />
  <Increment animal="cats" />
  <Display animal="cats" />
</template>

​
Solid Complete Example

import { Store, useStore } from '@tanstack/solid-store'
import { render } from 'solid-js/web'

// Create store outside of components
export const store = new Store({
  cats: 0,
  dogs: 0,
})

// Display component
export const Display = (props: { animals: 'dogs' | 'cats' }) => {
  const count = useStore(store, (state) => state[props.animals])
  return <div>{props.animals}: {count()}</div>
}

// Button component
export const Button = (props: { animals: 'dogs' | 'cats' }) => {
  return (
    <button
      onClick={() => {
        store.setState((state) => ({
          ...state,
          [props.animals]: state[props.animals] + 1,
        }))
      }}
    >
      Increment
    </button>
  )
}

const App = () => {
  return (
    <div>
      <h1>How many of your friends like cats or dogs?</h1>
      <Button animals="dogs" />
      <Display animals="dogs" />
      <Button animals="cats" />
      <Display animals="cats" />
    </div>
  )
}

const root = document.getElementById('root')
render(() => <App />, root!)

​
Next Steps

You’ve successfully created your first TanStack Store! Here’s what to explore next:

Core Concepts

Deep dive into stores, atoms, and reactivity

API Reference

Explore the complete API documentation

Framework Guides

Framework-specific patterns and best practices

Examples

Browse example applications and patterns