Hook useRef no React: DOM e Valores Mutáveis
⚡ Curso de React.js • Web-ZoneWare

Hook useRef no React: Referências ao DOM & Valores Persistentes

Lição 21 de 50

Hook useRef no React: Referências ao DOM & Valores Persistentes

1. O Que É o useRef e Qual a Sua Anatomia?

O hook useRef é frequentemente apresentado como a “ponte de fuga” do React para acessar elementos do DOM real. No entanto, seu poder na engenharia de software vai muito além disso: ele é uma ferramenta essencial para reter qualquer valor mutável entre renderizações sem disparar re-renders.

A sua declaração básica é extremamente simples:

CODE 3 linhas
import { useRef } from 'react';
 
const minhaRef = useRef(valorInicial);

O useRef retorna um objeto JavaScript simples com uma única propriedade mutável chamada current:

Estrutura do Objeto de Referência

minhaRef = {
  current: valorInicial
}
    

A característica fundamental que diferencia o useRef do useState é a seguinte:

A Regra de Ouro do useRef: Modificar a propriedade minhaRef.current = novoValor NUNCA dispara um novo ciclo de renderização no React! O valor é atualizado de forma síncrona na memória heap e retido com fidelidade pelo Fiber Node durante toda a vida útil do componente.


2. Caso de Uso 1: Acesso Direto e Imperativo a Nós do DOM

O React opera de maneira declarativa: você descreve o JSX e o motor do React cuida de manipular o DOM. No entanto, o navegador possui APIs nativas essenciais que exigem manipulação imperativa direta de nós HTML:

  • Gerenciamento de Foco: Mover o cursor para um campo específico de input (`inputRef.current.focus()`).
  • Controle de Mídias HTML5: Disparar métodos imperativos como `videoRef.current.play()` ou `audioRef.current.pause()`.
  • Geometria e Scroll: Medir dimensões com `getBoundingClientRect()` ou rolar a página suavemente com `elementoRef.current.scrollIntoView({ behavior: ‘smooth’ })`.
  • Desenho em Canvas 2D / WebGL: Obter o contexto gráfico do elemento ``.

Como Conectar a Ref ao Elemento JSX

Basta passar o objeto retornado por useRef para o atributo reservado ref de qualquer elemento HTML no seu JSX:

CODE 16 linhas
function CampoBuscaAutoFoco() {
  const inputRef = useRef(null); // Inicia como null
 
  function focarNoInput() {
    // Quando o componente monta, o React atribui o nó DOM real a 'inputRef.current'
    inputRef.current.focus();
    inputRef.current.select(); // Seleciona todo o texto existente
  }
 
  return (
    <div>
      <input ref={inputRef} type="text" placeholder="Pesquisar..." />
      <button onClick={focarNoInput}>🔍 Focar no Campo</button>
    </div>
  );
}

3. Caso de Uso 2: Variável Mutável Persistente (Sem Re-render)

Nem toda informação relevante em um componente precisa ser renderizada visualmente no JSX. Se você colocar um dado no useState, cada atualização forçará o componente e todos os seus filhos a re-executarem desnecessariamente.

Utilizamos useRef como uma variável de instância persistente em cenários como:

Armazenar IDs de Timers e Sockets

O ID retornado por setInterval ou instâncias de conexões WebSocket não afetam a UI diretamente. Guardá-los em timerRef.current permite limpá-los a qualquer momento sem custos de re-render.

Armazenar o Valor Anterior (Previous Value)

Comparar o estado atual com o estado imediatamente anterior para detectar variações (ex: saber se um preço subiu ou desceu em relação ao render passado).

Veja o exemplo clássico de um cronômetro com useRef:

CODE 27 linhas
function Cronometro() {
  const [segundos, setSegundos] = useState(0);
  
  // Guardamos o ID do timer em uma ref: NÃO dispara re-render ao mudar!
  const timerIdRef = useRef(null);
 
  function iniciar() {
    if (timerIdRef.current !== null) return; // Já está rodando
 
    timerIdRef.current = setInterval(() => {
      setSegundos(prev => prev + 1);
    }, 1000);
  }
 
  function pausar() {
    clearInterval(timerIdRef.current);
    timerIdRef.current = null;
  }
 
  return (
    <div>
      <h1>Tempo: {segundos}s</h1>
      <button onClick={iniciar}>Iniciar</button>
      <button onClick={pausar}>Pausar</button>
    </div>
  );
}

4. Tabela Definitiva: useState vs useRef vs Variável Comum (let)

Mecanismo Persiste Entre Renders? Altera Dispara Re-render? Finalidade Principal
Variável Comum (let x) ❌ Não (reinicializada do zero a cada render) ❌ Não Cálculos temporários e efêmeros durante o render puro.
useState ✔ Sim (retido pelo Fiber Node) ✔ SIM (Dispara Re-render) Dados que afetam diretamente o que o usuário vê na tela.
useRef ✔ Sim (retido pelo Fiber Node) ❌ NÃO (Silencioso na UI) Acesso a nós do DOM, IDs de timers e dados de bastidores.

5. Cuidados Essenciais: Onde NUNCA Ler ou Escrever em ref.current

🚨 Regra de Integridade: Não Mute Refs Durante a Renderização

NUNCA leia ou altere o valor de ref.current durante a execução pura do corpo do componente (por exemplo: const cont = ref.current++ dentro do JSX).

O React espera que a fase de renderização seja uma função pura. Se você mutar refs durante o render, a concorrência do React 18 e o Strict Mode produzirão comportamentos imprevisíveis.

Mute refs APENAS dentro de manipuladores de eventos (`onClick`, `onChange`) ou dentro do `useEffect`!

🛠️ Laboratório Prático & Prática Imediata

Aplique o que você aprendeu nesta lição

Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground Web Online

Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.

⚡ Codificar no Playground IDE
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima