Zustand – Minimalist State Management

Simple, fast, and scalable state management without the boilerplate

When to Use

Use Zustand when you need:

• Global state shared across multiple components
• Simple API without boilerplate (no providers, actions, reducers)
• Performance with fine-grained subscriptions
• TypeScript support with excellent type inference
• Middleware for persistence, devtools, or immer
• Lightweight solution (small bundle size)

Choose alternatives when:

• Component-local state is sufficient (use useState)
• You need server state management (use React Query, SWR)
• Complex state machines required (use XState)
• Team strongly prefers Redux patterns

Critical Patterns

Pattern 1: Selective Subscriptions for Performance

// ✅ Good: Subscribe to specific state slices
const count = useStore((state) => state.count);
const increment = useStore((state) => state.increment);

// Component only re-renders when count changes
export function Counter() {
  const count = useStore((state) => state.count);
  const increment = useStore((state) => state.increment);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>+</button>
    </div>
  );
}

// ✅ Good: Multiple values with shallow comparison
import { shallow } from 'zustand/shallow';

const { user, isLoading } = useUserStore(
  (state) => ({ user: state.user, isLoading: state.isLoading }),
  shallow
);

// ❌ Bad: Subscribing to entire store
const store = useStore(); // Re-renders on ANY state change!

// ❌ Bad: Creating new object without shallow
const { count, total } = useStore((state) => ({
  count: state.count,
  total: state.total,
})); // New object every render, always re-renders

Why: Selective subscriptions prevent unnecessary re-renders; shallow comparison for multiple values avoids performance issues.

Pattern 2: Actions with setState Patterns

// ✅ Good: Update state immutably with function form
interface CounterStore {
  count: number;
  increment: () => void;
  incrementBy: (value: number) => void;
  reset: () => void;
}

export const useCounterStore = create<CounterStore>((set) => ({
  count: 0,
  
  increment: () => set((state) => ({ count: state.count + 1 })),
  
  incrementBy: (value) => set((state) => ({ count: state.count + value })),
  
  reset: () => set({ count: 0 }), // Direct object when not using previous state
}));

// ✅ Good: Complex updates with get
export const useCartStore = create<CartStore>((set, get) => ({
  items: [],
  total: 0,
  
  addItem: (item) => set((state) => {
    const newItems = [...state.items, item];
    const newTotal = newItems.reduce((sum, i) => sum + i.price, 0);
    
    return { items: newItems, total: newTotal };
  }),
  
  removeItem: (id) => set((state) => ({
    items: state.items.filter(item => item.id !== id),
  })),
  
  getItemCount: () => get().items.length, // Access state without subscribing
}));

// ❌ Bad: Mutating state directly
increment: () => {
  const state = get();
  state.count++; // MUTATION!
  set(state);
}

// ❌ Bad: Not using function form when depending on previous state
increment: () => set({ count: get().count + 1 }); // Race condition possible

Why: Immutable updates prevent bugs; function form ensures correct updates with concurrent actions; get() allows reading state in actions.

Pattern 3: Organizing Large Stores with Slices

// ✅ Good: Split large stores into slices
import { StateCreator } from 'zustand';

export interface UserSlice {
  user: User | null;
  setUser: (user: User) => void;
  clearUser: () => void;
}

export const createUserSlice: StateCreator<StoreState, [], [], UserSlice> = (set) => ({
  user: null,
  setUser: (user) => set({ user }),
  clearUser: () => set({ user: null }),
});

// Combine slices
type StoreState = UserSlice & SettingsSlice;
export const useStore = create<StoreState>()((...a) => ({
  ...createUserSlice(...a),
  ...createSettingsSlice(...a),
}));

// ❌ Bad: One massive store object with 50+ fields

Why: Slices improve maintainability and separate concerns. For full slice patterns, see references/patterns.md.

Pattern 4: Async Actions with Proper Loading States

// ✅ Good: Track loading and error states
interface UserStore {
  user: User | null;
  isLoading: boolean;
  error: string | null;
  fetchUser: (id: string) => Promise<void>;
  clearError: () => void;
}

export const useUserStore = create<UserStore>((set, get) => ({
  user: null,
  isLoading: false,
  error: null,

  fetchUser: async (id) => {
    set({ isLoading: true, error: null });

    try {
      const response = await fetch(`/api/users/${id}`);
      
      if (!response.ok) {
        throw new Error('Failed to fetch user');
      }
      
      const user = await response.json();
      set({ user, isLoading: false });
    } catch (error) {
      set({
        error: error instanceof Error ? error.message : 'Unknown error',
        isLoading: false,
        user: null,
      });
    }
  },

  clearError: () => set({ error: null }),
}));

// Usage in component
export function UserProfile({ userId }: { userId: string }) {
  const { user, isLoading, error, fetchUser } = useUserStore(
    (state) => ({
      user: state.user,
      isLoading: state.isLoading,
      error: state.error,
      fetchUser: state.fetchUser,
    }),
    shallow
  );

  useEffect(() => {
    fetchUser(userId);
  }, [userId, fetchUser]);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!user) return <div>No user found</div>;

  return <div>{user.name}</div>;
}

// ❌ Bad: No loading or error states
export const useUserStore = create<UserStore>((set) => ({
  user: null,
  
  fetchUser: async (id) => {
    const response = await fetch(`/api/users/${id}`);
    const user = await response.json();
    set({ user }); // No indication of loading or errors
  },
}));

Why: Loading states provide UX feedback; error handling improves reliability; clear error makes debugging easier.

Pattern 5: Middleware Usage

For data persistence, debugging, and state immutability, see Middleware & Advanced.

Anti-Patterns

Anti-Pattern 1: Using Zustand for Server State

// ❌ Problem: Managing server data with Zustand
export const usePostsStore = create<PostsStore>((set) => ({
  posts: [],
  isLoading: false,
  
  fetchPosts: async () => {
    set({ isLoading: true });
    const posts = await fetch('/api/posts').then(r => r.json());
    set({ posts, isLoading: false });
  },
  
  updatePost: async (id, data) => {
    await fetch(`/api/posts/${id}`, { method: 'PUT', body: JSON.stringify(data) });
    // Manual cache invalidation...
  },
}));

Why it’s wrong: Manual cache management; no automatic refetching; cache invalidation is hard; missing features like background refetch, deduplication.

Solution:

// ✅ Use React Query for server state
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

export function usePosts() {
  return useQuery({
    queryKey: ['posts'],
    queryFn: () => fetch('/api/posts').then(r => r.json()),
  });
}

export function useUpdatePost() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: (data) => fetch(`/api/posts/${data.id}`, {
      method: 'PUT',
      body: JSON.stringify(data),
    }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['posts'] }); // Auto refresh
    },
  });
}

// ✅ Use Zustand for UI/client state only
export const useUIStore = create((set) => ({
  sidebarOpen: false,
  theme: 'light',
  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
}));

Anti-Pattern 2: Not Memoizing Selectors

// ❌ Problem: Creating new selectors on every render
const completedTodos = useStore((state) =>
  state.todos.filter(todo => todo.completed) // New array every time
);

// ✅ Solution: Use shallow comparison
import { shallow } from 'zustand/shallow';
const completedTodos = useStore(
  (state) => state.todos.filter(todo => todo.completed),
  shallow
);

Why it’s wrong: Component re-renders even when filtered result is the same.

Anti-Pattern 3: Overusing Global State

// ❌ Problem: Form state in global store
export const useFormStore = create((set) => ({
  email: '', password: '',
  setEmail: (email) => set({ email }),
}));

// ✅ Solution: Use local state for component-specific data
export function LoginForm() {
  const [email, setEmail] = useState('');
  return <input value={email} onChange={(e) => setEmail(e.target.value)} />;
}

Why it’s wrong: Unnecessary global state; harder to test; overkill for component-scoped data.

For more anti-patterns and solutions, see references/patterns.md.

What This Skill Covers

• Store creation with TypeScript
• React integration with hooks
• Middleware (persist, devtools, immer)
• Async actions and selectors

For middleware, advanced patterns, and testing, see references/.

Basic Store

import { create } from 'zustand';

interface CounterStore {
  count: number;
  increment: () => void;
  decrement: () => void;
  reset: () => void;
}

export const useCounterStore = create<CounterStore>((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
  decrement: () => set((state) => ({ count: state.count - 1 })),
  reset: () => set({ count: 0 }),
}));

Usage in Component

'use client';

import { useCounterStore } from '@/stores/counter';

export function Counter() {
  const count = useCounterStore((state) => state.count);
  const increment = useCounterStore((state) => state.increment);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>+</button>
    </div>
  );
}

For async actions, selectors, and advanced patterns, see references/patterns.md.

Quick Reference

// Create store
const useStore = create<Store>((set, get) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}));

// Use in component
const count = useStore((state) => state.count);

// Get state outside React
const count = useStore.getState().count;

// Set state outside React
useStore.setState({ count: 5 });

// Subscribe to changes
const unsubscribe = useStore.subscribe(
  (state) => state.count,
  (count) => console.log(count)
);

Learn More

• Middleware & Advanced: references/middleware.md – Persist, devtools, immer, slices pattern
• Performance & Testing: references/performance.md – Optimization, SSR, testing patterns

External References

• Zustand Documentation
• Zustand GitHub

Maintained by dsmj-ai-toolkit