usePrevious - Acompanhe o valor anterior de qualquer estado ou prop

Receita

import { useRef, useEffect } from "react";
 
/**
 * usePrevious
 * Retorna o valor da renderização anterior.
 * Retorna `undefined` na primeira renderização.
 */
function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T | undefined>(undefined);
 
  useEffect(() => {
    ref.current = value;
  }, [value]);
 
  return ref.current;
}
 
/**
 * usePreviousDistinct
 * Atualiza apenas quando o valor realmente muda
 * (pula re-renderizações onde o valor permanece o mesmo).
 */
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;
}

Quando usar isso: Você precisa comparar os valores atuais e anteriores para detectar a direção da mudança, acionar animações, implementar desfazer ou pular efeitos redundantes.

Exemplo Funcional

"use client";
 
import { useState } from "react";
 
// Detectar direção da animação
function Counter() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);
 
  const direction =
    prevCount === undefined
      ? "initial"
      : count > prevCount
        ? "up"
        : count < prevCount
          ? "down"
          : "same";
 
  return (
    <div>
      <p>
        Contador: {count} (era: {prevCount ?? "N/A"})
      </p>
      <p>Direção: {direction}</p>
      <button onClick={() => setCount((c) => c + 1)}>+1</button>
      <button onClick={() => setCount((c) => c - 1)}>-1</button>
    </div>
  );
}
 
// Detectar alterações de rota
function RouteChangeDetector({ pathname }: { pathname: string }) {
  const prevPathname = usePrevious(pathname);
 
  useEffect(() => {
    if (prevPathname && prevPathname !== pathname) {
      console.log(`Navegou de ${prevPathname} para ${pathname}`);
      // Rastrear visualização de página, rolar para o topo, etc.
    }
  }, [pathname, prevPathname]);
 
  return null;
}
 
// Desfazer simples para um campo 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="Digite algo..."
      />
      <button onClick={undo} disabled={prevText === undefined}>
        Desfazer
      </button>
      <p style={{ color: "#999" }}>Anterior: {prevText ?? "nenhum"}</p>
    </div>
  );
}

O que isso demonstra:

• Direção do contador: Compara a contagem atual e anterior para determinar se aumentou, diminuiu ou permaneceu a mesma
• Alterações de rota: Detecta navegação comparando a prop pathname entre renderizações
• Desfazer de nível único: Restaura o valor anterior de um campo de texto

Mergulho Profundo

Como Funciona

• Tempo de Ref: useRef persiste entre as renderizações sem causar re-renderizações. O useEffect é executado após a renderização, então durante a renderização ref.current ainda contém o valor da renderização anterior.
• Ciclo de Renderização: Na renderização N, ref.current contém o valor da renderização N-1. Após a conclusão da renderização N, o efeito atualiza ref.current para o valor da renderização N.
• Primeira Renderização: Na renderização inicial, ref.current é undefined porque nenhum valor anterior existe ainda.
• usePreviousDistinct: Compara valores durante a renderização (não em um efeito) para pular atualizações quando o valor não mudou de fato. Útil quando um componente pai re-renderiza sem alterar a prop.

Parâmetros e Valores de Retorno

usePrevious

usePreviousDistinct

Variações

Com valor inicial: Evite undefined na primeira renderização:

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

Pilha de histórico: Rastreie múltiplos valores anteriores para desfazer em vários níveis:

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); // Exclui o valor atual
}

Comparação de objetos: Para objetos, use uma função de comparação profunda:

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

Notas TypeScript

• O tipo de retorno T | undefined faz com que o consumidor lide com o caso da renderização inicial. Use a variação "com valor inicial" para evitar isso.
• O genérico T é inferido do argumento, portanto, um parâmetro de tipo explícito geralmente não é necessário.
• usePreviousDistinct aceita um comparador personalizado tipado como (a: T, b: T) => boolean.

Armadilhas

• Um render atrasado - O valor retornado é sempre do render anterior, não da atualização de estado anterior. Se várias atualizações de estado ocorrerem em uma renderização (agrupamento), apenas o valor final renderizado será capturado. Correção: Isso é intencional; o hook rastreia renderizações, não transições de estado.
• Referências de objetos - Para objetos e arrays, "anterior" muda a cada renderização se uma nova referência for criada a cada vez. Correção: Use usePreviousDistinct com uma comparação profunda ou memoize o valor upstream.
• Ambiguidade de undefined - Na primeira renderização, undefined é retornado. Se undefined for um valor válido para seus dados, você não poderá distinguir "sem valor anterior" de "o valor anterior era undefined". Correção: Use a variação "com valor inicial" ou envolva em um objeto { hasPrevious, value }.
• Desfazer é de nível único - usePrevious rastreia apenas um passo para trás. Correção: Use a variação de pilha de histórico para desfazer em vários níveis.
• Tempo de efeito com Strict Mode - No React 18 Strict Mode, os efeitos são executados duas vezes em desenvolvimento. O ref é atualizado corretamente porque o segundo efeito sobrescreve o primeiro. Correção: Nenhuma ação necessária; o comportamento de produção está correto.

Alternativas

FAQs

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 é number | undefined

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

Relacionado

• useRef - o primitivo subjacente
• useEffect - tempo da atualização do ref
• useLocalStorage - persistir estado para desfazer entre sessões