useRef — o que é, o hook de referências e trabalho com o DOM no React

O que é useRef no React

useRef é um hook adicionado no React 16.8 que retorna um objeto ref mutável com uma única propriedade .current. O valor inicial é atribuído a .current na montagem do componente. A principal diferença de uma variável comum é que o objeto ref sobrevive às re-renderizações: em renderizações subsequentes o React não recria o ref, mas retorna o mesmo objeto.

Internamente, useRef usa o mesmo mecanismo que useState e useEffect — uma lista ligada de hooks no nó fiber. No entanto, ao contrário do useState, o React não rastreia alterações no objeto ref, não enfileira atualizações nem agenda re-renderizações. Isto torna useRef um hook extremamente leve, sem impacto no desempenho mesmo sob alterações frequentes.

De acordo com a Equipa React — Hooks FAQ (2025), useRef é essencialmente uma “caixa” que armazena um valor. Açúcar sintático: const ref = useRef(valorInicial) equivale a const ref = { current: valorInicial } com a diferença de que o React garante que o objeto ref será o mesmo em cada renderização. Sem magia — apenas uma referência estável gerida pelo React.

import { useRef } from 'react';

function Component() {
    const countRef = useRef(0);
    // countRef.current = 0 inicialmente
    // countRef.current = 5 após mutação
    // Nenhuma re-renderização acontece!
}

Acesso a elementos DOM com useRef

O caso de uso mais comum do useRef é obter acesso direto a um elemento DOM. O React atribui a elementRef.current uma referência ao nó DOM após a montagem do componente. Isto é necessário para focar um input, medir dimensões de elementos, integrar com bibliotecas de animação e bibliotecas que não usam a renderização do React.

O React gere automaticamente as referências ref ao DOM: na montagem atribui o nó DOM real, na desmontagem anula (torna null). Isto garante que .current tenha sempre o valor atualizado e previne fugas de memória através de referências pendentes a elementos removidos. Não é necessária limpeza manual.

function AutoFocusInput() {
    const inputRef = useRef(null);

    useEffect(() => {
        // Focar o input após montar o componente
        inputRef.current?.focus();
    }, []);

    return <input ref={inputRef} type="text" />;
}

De acordo com a Documentação React — Refs e DOM (2025), não use ref para operações declarativas — abrir/fechar modais, gerir visibilidade. Para esses fins existem state e props. As refs destinam-se a operações imperativas que não podem ser expressas declarativamente: foco, seleção de texto, integração com bibliotecas de terceiros.

Armazenamento de valores mutáveis sem re-renderizações

O segundo caso de uso mais importante é o armazenamento de valores arbitrários que precisam persistir entre renderizações mas cujas alterações não devem provocar uma re-renderização. Exemplos típicos: identificadores de temporizadores (setInterval/setTimeout), flags de cancelamento de pedidos, valores anteriores de props para comparação e quaisquer dados que não afetem a saída da UI.

Isto é especialmente útil no useEffect: useRef armazena o identificador do temporizador e o cleanup limpa-o. Se timerId fosse armazenado em useState, cada chamada a setTimerId provocaria uma re-renderização desnecessária que não é necessária nem para a lógica nem para a UI. useRef resolve este problema sem sobrecarga e sem re-renderizações desnecessárias.

function Timer() {
    const intervalRef = useRef(null);

    const start = () => {
        intervalRef.current = setInterval(() => {
            console.log('tique');
        }, 1000);
    };

    const stop = () => {
        clearInterval(intervalRef.current);
    };

    useEffect(() => stop, []);

    return <><button onClick={start}>Start</button><button onClick={stop}>Stop</button></>;
}

useRef vs useState: quando usar cada um

O principal dilema — escolher entre useRef e useState — resolve-se com uma pergunta: “É necessária uma re-renderização quando o valor muda?”. Se sim — useState. Se não — useRef. useState armazena o estado que afeta a saída do componente; useRef armazena dados necessários para a lógica interna mas que não afetam a UI.

Na prática, os programadores usam frequentemente useRef para armazenar callbacks e evitar problemas com closures. Por exemplo, se useEffect subscreve um evento e o callback precisa do estado atual — armazene o callback em useRef. Em cada renderização, atualize ref.current com uma nova função, e o efeito invocará sempre o callback fresco sem necessidade de ressubscrever.

Existe um anti-padrão: usar useRef para dados necessários em JSX cujas alterações não devem causar re-renderização. Isto leva à dessincronização — a UI mostra dados antigos enquanto ref.current já é novo. Se o valor é exibido na UI — use useState. Se usado apenas internamente — useRef.

useRef em combinação com useEffect

A combinação useRef + useEffect é o padrão para rastrear valores anteriores de props. Armazene o valor anterior em ref, compare com o valor atual no useEffect e tome decisões com base na diferença. Isto é especialmente útil em animações quando precisa de saber qual era o valor antes da alteração.

function PriceDisplay({ price }) {
    const prevPriceRef = useRef(price);

    useEffect(() => {
        const prevPrice = prevPriceRef.current;
        if (price > prevPrice) {
            animateUp();
        } else if (price < prevPrice) {
            animateDown();
        }
        prevPriceRef.current = price;
    }, [price]);

    return <span>${price}</span>;
}

De acordo com a Documentação React — Hooks FAQ (2025), este padrão é chamado de “padrão de valor anterior”. Funciona porque useRef preserva o valor entre renderizações, e useEffect executa-se após a confirmação das alterações. Primeiro o DOM é atualizado com o novo price, depois useEffect compara-o com o anterior (ainda em ref) e atualiza ref.current para o valor atual.

Erros comuns com useRef

O erro mais frequente é ler ref.current durante a fase de renderização para calcular JSX. Como alterar ref.current não provoca re-renderização, o componente pode usar um valor desatualizado. Se .current participa na saída da UI — use useState. Se precisar de sincronizar ref e state, use useEffect para atualizar o state a partir do ref.

• Ref em JSX — ler ref.current dentro de uma função de renderização leva à dessincronização entre UI e dados.
• Ref como dependência de useEffect — ref.current não deve estar no array de dependências; o React não rastreia as suas alterações.
• Verificação de null esquecida — na desmontagem ref.current torna-se null; verifique antes de aceder.
• Armazenar funções em ref — atualize ref.current em cada renderização se usar o padrão de callback fresco.

// ❌ Não leia ref.current durante a renderização para exibição
function BadComponent() {
    const valRef = useRef(0);
    return <p>{valRef.current}</p>; // NÃO será atualizado na mutação
}

// ✅ Use state para exibição, ref para lógica
function GoodComponent() {
    const [val, setVal] = useState(0);
    const valRef = useRef(0);
    return <p>{val}</p>;
}

Outro erro comum é usar useRef como única forma de armazenar estado num componente quando os dados afetam realmente a UI. Os programadores escolhem useRef para evitar re-renderizações “desnecessárias”, mas acabam com uma UI que não atualiza. A abordagem correta: use useState para dados de UI e useRef apenas para valores auxiliares que não participam na renderização.