React useCallback Guide

The useCallback hook returns a memoized callback function that only changes when dependencies change, helping optimize performance.

Basic Usage#

import { useCallback, useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  // Without useCallback - new function every render
  const increment = () => setCount(c => c + 1);

  // With useCallback - same function reference unless deps change
  const incrementMemoized = useCallback(() => {
    setCount(c => c + 1);
  }, []);

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

With Dependencies#

import { useCallback, useState } from 'react';

function SearchComponent() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  // Recreates when query changes
  const handleSearch = useCallback(async () => {
    const response = await fetch(`/api/search?q=${query}`);
    const data = await response.json();
    setResults(data);
  }, [query]);

  // Multiple dependencies
  const [sortBy, setSortBy] = useState('name');
  const [order, setOrder] = useState('asc');

  const sortResults = useCallback((items) => {
    return [...items].sort((a, b) => {
      const compare = a[sortBy].localeCompare(b[sortBy]);
      return order === 'asc' ? compare : -compare;
    });
  }, [sortBy, order]);

  return (
    <div>
      <input
        value={query}
        onChange={e => setQuery(e.target.value)}
      />
      <button onClick={handleSearch}>Search</button>
    </div>
  );
}

Passing to Child Components#

import { useCallback, useState, memo } from 'react';

// Memoized child component
const ExpensiveList = memo(function ExpensiveList({ items, onItemClick }) {
  console.log('ExpensiveList rendered');
  return (
    <ul>
      {items.map(item => (
        <li key={item.id} onClick={() => onItemClick(item.id)}>
          {item.name}
        </li>
      ))}
    </ul>
  );
});

function Parent() {
  const [items, setItems] = useState([
    { id: 1, name: 'Item 1' },
    { id: 2, name: 'Item 2' }
  ]);
  const [selectedId, setSelectedId] = useState(null);

  // Without useCallback, ExpensiveList re-renders on every parent render
  // because onItemClick is a new function reference
  const handleItemClick = useCallback((id) => {
    setSelectedId(id);
    console.log('Item clicked:', id);
  }, []);

  return (
    <div>
      <ExpensiveList items={items} onItemClick={handleItemClick} />
      <p>Selected: {selectedId}</p>
    </div>
  );
}

Event Handlers#

import { useCallback, useState } from 'react';

function Form() {
  const [values, setValues] = useState({
    name: '',
    email: '',
    message: ''
  });

  // Single handler for multiple inputs
  const handleChange = useCallback((e) => {
    const { name, value } = e.target;
    setValues(prev => ({
      ...prev,
      [name]: value
    }));
  }, []);

  const handleSubmit = useCallback((e) => {
    e.preventDefault();
    console.log('Submitting:', values);
  }, [values]);

  // Handler with parameters
  const handleFieldBlur = useCallback((fieldName) => {
    return () => {
      console.log(`${fieldName} lost focus`);
    };
  }, []);

  return (
    <form onSubmit={handleSubmit}>
      <input
        name="name"
        value={values.name}
        onChange={handleChange}
        onBlur={handleFieldBlur('name')}
      />
      <input
        name="email"
        value={values.email}
        onChange={handleChange}
        onBlur={handleFieldBlur('email')}
      />
      <textarea
        name="message"
        value={values.message}
        onChange={handleChange}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

With useEffect#

import { useCallback, useEffect, useState } from 'react';

function DataFetcher({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(false);

  // Memoize fetch function
  const fetchUser = useCallback(async () => {
    setLoading(true);
    try {
      const response = await fetch(`/api/users/${userId}`);
      const data = await response.json();
      setUser(data);
    } finally {
      setLoading(false);
    }
  }, [userId]);

  // Use in effect
  useEffect(() => {
    fetchUser();
  }, [fetchUser]);

  // Expose refetch capability
  return (
    <div>
      {loading ? 'Loading...' : user?.name}
      <button onClick={fetchUser}>Refresh</button>
    </div>
  );
}

Debounced Callbacks#

import { useCallback, useRef, useEffect } from 'react';

// Custom hook for debounced callback
function useDebouncedCallback(callback, delay) {
  const timeoutRef = useRef(null);

  const debouncedCallback = useCallback((...args) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }

    timeoutRef.current = setTimeout(() => {
      callback(...args);
    }, delay);
  }, [callback, delay]);

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);

  return debouncedCallback;
}

// Usage
function SearchInput() {
  const [query, setQuery] = useState('');

  const search = useCallback((searchTerm) => {
    console.log('Searching for:', searchTerm);
    // API call here
  }, []);

  const debouncedSearch = useDebouncedCallback(search, 300);

  const handleChange = (e) => {
    const value = e.target.value;
    setQuery(value);
    debouncedSearch(value);
  };

  return <input value={query} onChange={handleChange} />;
}

useCallback vs useMemo#

import { useCallback, useMemo } from 'react';

function Comparison() {
  // useCallback returns memoized function
  const memoizedCallback = useCallback(() => {
    return 'result';
  }, []);

  // useMemo returns memoized value
  const memoizedValue = useMemo(() => {
    return 'result';
  }, []);

  // These are equivalent:
  const fn1 = useCallback(someFunction, [dep]);
  const fn2 = useMemo(() => someFunction, [dep]);

  // When to use which:
  // useCallback - for functions passed to children
  // useMemo - for expensive calculations
}

// Practical example
function DataProcessor({ data, onProcess }) {
  // useMemo for computed value
  const processedData = useMemo(() => {
    return data.map(item => ({
      ...item,
      computed: expensiveComputation(item)
    }));
  }, [data]);

  // useCallback for event handler
  const handleClick = useCallback(() => {
    onProcess(processedData);
  }, [onProcess, processedData]);

  return (
    <button onClick={handleClick}>
      Process {processedData.length} items
    </button>
  );
}

Avoiding Common Pitfalls#

import { useCallback, useState } from 'react';

function PitfallExamples() {
  const [count, setCount] = useState(0);
  const [name, setName] = useState('');

  // Pitfall 1: Missing dependencies
  // BAD - stale count value
  const badIncrement = useCallback(() => {
    setCount(count + 1);  // Uses stale count
  }, []);  // Missing count dependency

  // GOOD - use functional update
  const goodIncrement = useCallback(() => {
    setCount(c => c + 1);  // Always current
  }, []);

  // Pitfall 2: Unnecessary useCallback
  // BAD - no benefit, component doesn't pass this to children
  const handleLocalClick = useCallback(() => {
    console.log('clicked');
  }, []);

  // GOOD - just use regular function
  const handleLocalClick2 = () => {
    console.log('clicked');
  };

  // Pitfall 3: Inline object in dependencies
  // BAD - object recreated every render
  const config = { threshold: 10 };
  const badCallback = useCallback(() => {
    return count > config.threshold;
  }, [count, config]);  // config changes every render!

  // GOOD - stable reference
  const threshold = 10;
  const goodCallback = useCallback(() => {
    return count > threshold;
  }, [count, threshold]);

  return <div>{count}</div>;
}

With Context#

import { createContext, useContext, useCallback, useState } from 'react';

const TodoContext = createContext();

function TodoProvider({ children }) {
  const [todos, setTodos] = useState([]);

  const addTodo = useCallback((text) => {
    setTodos(prev => [
      ...prev,
      { id: Date.now(), text, completed: false }
    ]);
  }, []);

  const toggleTodo = useCallback((id) => {
    setTodos(prev =>
      prev.map(todo =>
        todo.id === id
          ? { ...todo, completed: !todo.completed }
          : todo
      )
    );
  }, []);

  const deleteTodo = useCallback((id) => {
    setTodos(prev => prev.filter(todo => todo.id !== id));
  }, []);

  const value = {
    todos,
    addTodo,
    toggleTodo,
    deleteTodo
  };

  return (
    <TodoContext.Provider value={value}>
      {children}
    </TodoContext.Provider>
  );
}

function TodoItem({ todo }) {
  const { toggleTodo, deleteTodo } = useContext(TodoContext);

  // These are stable references from context
  return (
    <li>
      <input
        type="checkbox"
        checked={todo.completed}
        onChange={() => toggleTodo(todo.id)}
      />
      {todo.text}
      <button onClick={() => deleteTodo(todo.id)}>Delete</button>
    </li>
  );
}

Custom Hooks with useCallback#

import { useCallback, useState, useEffect } from 'react';

// Fetch hook with memoized functions
function useFetch(url) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const execute = useCallback(async () => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch(url);
      if (!response.ok) throw new Error('Request failed');
      const result = await response.json();
      setData(result);
      return result;
    } catch (err) {
      setError(err);
      throw err;
    } finally {
      setLoading(false);
    }
  }, [url]);

  const reset = useCallback(() => {
    setData(null);
    setError(null);
    setLoading(false);
  }, []);

  return { data, loading, error, execute, reset };
}

// Toggle hook
function useToggle(initialValue = false) {
  const [value, setValue] = useState(initialValue);

  const toggle = useCallback(() => setValue(v => !v), []);
  const setTrue = useCallback(() => setValue(true), []);
  const setFalse = useCallback(() => setValue(false), []);

  return { value, toggle, setTrue, setFalse };
}

// Usage
function Component() {
  const { data, loading, execute } = useFetch('/api/data');
  const { value: isOpen, toggle, setFalse: close } = useToggle();

  return (
    <div>
      <button onClick={execute}>Fetch Data</button>
      <button onClick={toggle}>Toggle Modal</button>
      {isOpen && <Modal onClose={close} />}
    </div>
  );
}

Best Practices#

When to use useCallback:
✓ Passing callbacks to memoized children
✓ Callbacks used in useEffect dependencies
✓ Expensive callbacks that shouldn't recreate
✓ Functions exposed from custom hooks

When NOT to use:
✗ Every function (adds overhead)
✗ Functions not passed to children
✗ Simple components without memo
✗ Handlers for native elements only

Dependencies:
✓ Include all used values
✓ Use functional updates to avoid deps
✓ Keep dependencies minimal
✓ Use stable references

Performance:
✓ Pair with React.memo for children
✓ Profile before optimizing
✓ Don't prematurely optimize
✓ Measure actual performance gains

useCallback memoizes callback functions to maintain stable references between renders. Use it when passing callbacks to memoized child components, when callbacks are useEffect dependencies, or when building custom hooks. Pair with React.memo for optimal performance. Avoid overusing it—only add useCallback when you have a demonstrated performance need, as unnecessary memoization adds overhead without benefit.