Hook useRef no React: Referências ao DOM & Valores Persistentes
📑 Índice do Conteúdo
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:
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 = novoValorNUNCA 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:
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:
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`!
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.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground 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