usePrevious — Sigue el valor anterior de cualquier estado o prop

Receta

import { useRef, useEffect } from "react";
 
/**
 * usePrevious
 * Devuelve el valor del render anterior.
 * Devuelve `undefined` en el primer render.
 */
function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T | undefined>(undefined);
 
  useEffect(() => {
    ref.current = value;
  }, [value]);
 
  return ref.current;
}
 
/**
 * usePreviousDistinct
 * Solo se actualiza cuando el valor realmente cambia
 * (omite re-renders donde el valor permanece igual).
 */
function usePreviousDistinct<T>(
  value: T,
  isEqual: (a: T, b: T) => boolean = (a, b) => a === b
): T | undefined {
  const prevRef = useRef<T | undefined>(undefined);
  const currentRef = useRef<T>(value);
 
  if (!isEqual(currentRef.current, value)) {
    prevRef.current = currentRef.current;
    currentRef.current = value;
  }
 
  return prevRef.current;
}

Cuándo usarlo: Necesitas comparar valores actuales y anteriores para detectar la dirección del cambio, desencadenar animaciones, implementar deshacer u omitir efectos secundarios redundantes.

Ejemplo funcional

"use client";
 
import { useState } from "react";
 
// Detecta la dirección de la animación
function Counter() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);
 
  const direction =
    prevCount === undefined
      ? "inicial"
      : count > prevCount
        ? "arriba"
        : count < prevCount
          ? "abajo"
          : "igual";
 
  return (
    <div>
      <p>
        Contador: {count} (fue: {prevCount ?? "N/D"})
      </p>
      <p>Dirección: {direction}</p>
      <button onClick={() => setCount((c) => c + 1)}>+1</button>
      <button onClick={() => setCount((c) => c - 1)}>-1</button>
    </div>
  );
}
 
// Detecta cambios de ruta
function RouteChangeDetector({ pathname }: { pathname: string }) {
  const prevPathname = usePrevious(pathname);
 
  useEffect(() => {
    if (prevPathname && prevPathname !== pathname) {
      console.log(`Navegado de ${prevPathname} a ${pathname}`);
      // Rastrear vista de página, desplazarse hacia arriba, etc.
    }
  }, [pathname, prevPathname]);
 
  return null;
}
 
// Deshacer simple para una entrada de texto
function UndoableInput() {
  const [text, setText] = useState("");
  const prevText = usePrevious(text);
 
  const undo = () => {
    if (prevText !== undefined) {
      setText(prevText);
    }
  };
 
  return (
    <div>
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Escribe algo..."
      />
      <button onClick={undo} disabled={prevText === undefined}>
        Deshacer
      </button>
      <p style={{ color: "#999" }}>Anterior: {prevText ?? "ninguno"}</p>
    </div>
  );
}

Lo que esto demuestra:

• Dirección del contador: Compara el contador actual y anterior para determinar si aumentó, disminuyó o permaneció igual
• Cambios de ruta: Detecta navegación comparando la prop pathname en renders
• Deshacer de un nivel: Restaura el valor anterior de una entrada de texto

Análisis profundo

Cómo funciona

• Temporización de ref: useRef persiste en renders sin causar re-renders. El useEffect se ejecuta después del render, por lo que durante el render ref.current aún contiene el valor del render anterior.
• Ciclo de render: En el render N, ref.current contiene el valor del render N-1. Después de que se completa el render N, el efecto actualiza ref.current al valor del render N.
• Primer render: En el render inicial, ref.current es undefined porque aún no existe ningún valor anterior.
• usePreviousDistinct: Compara valores durante el render (no en un efecto) para omitir actualizaciones cuando el valor no ha cambiado realmente. Útil cuando un componente padre se re-renderiza sin cambiar la prop.

Parámetros y valores devueltos

usePrevious

usePreviousDistinct

Variaciones

Con valor inicial: Evita undefined en el primer render:

function usePrevious<T>(value: T, initialValue: T): T {
  const ref = useRef<T>(initialValue);
  useEffect(() => {
    ref.current = value;
  }, [value]);
  return ref.current;
}

Pila de historial: Rastrear múltiples valores anteriores para deshacer de varios niveles:

function usePreviousValues<T>(value: T, maxHistory: number = 10): T[] {
  const historyRef = useRef<T[]>([]);
 
  useEffect(() => {
    historyRef.current = [value, ...historyRef.current].slice(0, maxHistory);
  }, [value, maxHistory]);
 
  return historyRef.current.slice(1); // Excluir valor actual
}

Comparación de objetos: Para objetos, usa una función de comparación profunda:

const prevUser = usePreviousDistinct(user, (a, b) =>
  JSON.stringify(a) === JSON.stringify(b)
);

Notas de TypeScript

• El tipo de retorno T | undefined obliga al consumidor a manejar el caso del primer render. Usa la variación "con valor inicial" para evitar esto.
• El genérico T se infiere del argumento, por lo que normalmente no se necesita un parámetro de tipo explícito.
• usePreviousDistinct acepta un comparador personalizado tipado como (a: T, b: T) => boolean.

Problemas

• Un render atrás — El valor devuelto es siempre del render anterior, no de la actualización de estado anterior. Si múltiples actualizaciones de estado ocurren en un render (por lotes), solo se captura el valor final renderizado. Solución: Esto es por diseño; el hook rastrea renders, no transiciones de estado.
• Referencias de objetos — Para objetos y arrays, "anterior" cambia en cada render si se crea una nueva referencia cada vez. Solución: Usa usePreviousDistinct con una comparación profunda, o memoriza el valor antes.
• Ambigüedad de undefined — En el primer render, se devuelve undefined. Si undefined es un valor válido para tus datos, no puedes distinguir "sin anterior" de "anterior era undefined". Solución: Usa la variación "con valor inicial" o envuelve en un objeto { hasPrevious, value }.
• Deshacer es de un nivel — usePrevious solo rastrea un paso atrás. Solución: Usa la variación de pila de historial para deshacer de varios niveles.
• Temporización del efecto con Strict Mode — En React 18 Strict Mode, los efectos se ejecutan dos veces en desarrollo. La ref se actualiza correctamente porque el segundo efecto sobrescribe el primero. Solución: No se requiere ninguna acción; el comportamiento de producción es correcto.

Alternativas

Preguntas frecuentes

function usePreviousValues<T>(value: T, max = 10): T[] {
  const historyRef = useRef<T[]>([]);
  useEffect(() => {
    historyRef.current = [value, ...historyRef.current].slice(0, max);
  }, [value, max]);
  return historyRef.current.slice(1);
}

function usePrevious<T>(value: T, initialValue: T): T {
  const ref = useRef<T>(initialValue);
  useEffect(() => { ref.current = value; }, [value]);
  return ref.current;
}

const prev = usePrevious(42);
// prev es number | undefined

const prevUser = usePreviousDistinct(user, (a, b) =>
  a.id === b.id && a.name === b.name
);

Relacionado

• useRef — la primitiva subyacente
• useEffect — temporización de la actualización de ref
• useLocalStorage — persistir estado para deshacer entre sesiones