state-management

Manage client-side state with Zustand. Use when building shopping cart, user preferences, theme toggle, UI state, or any cross-component shared state with localStorage persist.

⭐3stars🔀0forks📁View on GitHub🕐Updated Dec 30, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for implementing efficient client-side state management using Zustand. It focuses on best practices for React and Next.js applications, including domain-driven store architecture, localStorage persistence, and performance optimization through granular selectors. By following these guidelines, developers can build scalable frontend states that are easy to maintain and highly performant.

Use Cases

  • E-commerce Shopping Carts: Managing complex cart logic, item quantities, and price calculations with persistence across browser sessions.
  • User Preferences & Personalization: Implementing theme toggles (light/dark mode) and language settings that stay consistent via localStorage.
  • Cross-Component State Sharing: Synchronizing data between deeply nested or decoupled components without the overhead of prop drilling or complex Context API setups.
  • Performance-Critical UI State: Utilizing shallow selectors and domain-specific stores to minimize unnecessary re-renders in high-frequency UI updates.
namestate-management
descriptionManage client-side state with Zustand. Use when building shopping cart, user preferences, theme toggle, UI state, or any cross-component shared state with localStorage persist.

This skill guides implementation of client-side state management using Zustand.

The user needs to share state between components, persist data to localStorage, or manage complex UI state like shopping carts or theme preferences.

Before You Start

Zustand is the preferred state management library:

  • File location: lib/stores/<name>-store.ts
  • Function: Use create from zustand (NOT createStore)
  • Components: Must have 'use client' to use stores

CRITICAL: Keep stores small and focused. Create one store per domain (cart, theme, user preferences) rather than one large store.

Basic Store

// lib/stores/cart-store.ts
import { create } from 'zustand';

interface CartItem {
  id: string;
  name: string;
  price: number;
  quantity: number;
}

interface CartStore {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  updateQuantity: (id: string, quantity: number) => void;
  clearCart: () => void;
  total: () => number;
}

export const useCartStore = create<CartStore>((set, get) => ({
  items: [],
  
  addItem: (item) =>
    set((state) => {
      const existing = state.items.find((i) => i.id === item.id);
      if (existing) {
        return {
          items: state.items.map((i) =>
            i.id === item.id ? { ...i, quantity: i.quantity + item.quantity } : i
          ),
        };
      }
      return { items: [...state.items, item] };
    }),
    
  removeItem: (id) =>
    set((state) => ({
      items: state.items.filter((i) => i.id !== id),
    })),
    
  updateQuantity: (id, quantity) =>
    set((state) => ({
      items: state.items.map((i) => (i.id === id ? { ...i, quantity } : i)),
    })),
    
  clearCart: () => set({ items: [] }),
  
  total: () => get().items.reduce((sum, i) => sum + i.price * i.quantity, 0),
}));

Store with localStorage Persistence

Use the persist middleware for data that should survive page refresh:

import { create } from 'zustand';
import { persist } from 'zustand/middleware';

interface ThemeStore {
  theme: 'light' | 'dark';
  setTheme: (theme: 'light' | 'dark') => void;
  toggleTheme: () => void;
}

export const useThemeStore = create<ThemeStore>()(
  persist(
    (set) => ({
      theme: 'light',
      setTheme: (theme) => set({ theme }),
      toggleTheme: () =>
        set((state) => ({ theme: state.theme === 'light' ? 'dark' : 'light' })),
    }),
    { name: 'theme-storage' }  // localStorage key
  )
);

Using Stores in Components

Always use selectors to prevent unnecessary re-renders:

'use client';
import { useCartStore } from '@/lib/stores/cart-store';

export function CartButton() {
  // Selector - only re-renders when items.length changes
  const count = useCartStore((state) => state.items.length);
  return <button>Cart ({count})</button>;
}

export function CartTotal() {
  const total = useCartStore((state) => state.total());
  return <span>${total.toFixed(2)}</span>;
}

Multiple Selectors with useShallow

When selecting multiple values, use useShallow to prevent re-renders if values haven't changed:

'use client';
import { useShallow } from 'zustand/react/shallow';
import { useCartStore } from '@/lib/stores/cart-store';

export function CartSummary() {
  const { items, total } = useCartStore(
    useShallow((state) => ({
      items: state.items,
      total: state.total(),
    }))
  );

  return (
    <div>
      <p>{items.length} items</p>
      <p>Total: ${total.toFixed(2)}</p>
    </div>
  );
}

Accessing Actions

Actions don't cause re-renders, so you can select them directly:

'use client';
import { useCartStore } from '@/lib/stores/cart-store';

export function AddToCartButton({ product }) {
  const addItem = useCartStore((state) => state.addItem);
  
  return (
    <button onClick={() => addItem({ ...product, quantity: 1 })}>
      Add to Cart
    </button>
  );
}

NEVER:

  • Use createStore (use create instead)
  • Select the entire store without selectors (causes unnecessary re-renders)
  • Forget 'use client' in components using stores
  • Create one giant store (split by domain)
  • Access stores in Server Components

IMPORTANT: Zustand stores are client-side only. For server-side state, use Server Components with direct database queries.