Como funciona o useRef do React JS? Aprenda com exemplos práticos

Você já precisou acessar um campo de formulário diretamente, guardar um valor entre renderizações ou controlar um cronômetro sem provocar atualizações na tela? É exatamente em situações assim que o useRef do React pode ajudar. Neste artigo, você vai aprender o que ele é, como funciona por trás dos panos e como utilizá-lo passo a passo, mesmo que esteja começando agora.

1. O que é o useRef no React?

O useRef é um Hook do React que permite guardar um valor entre as renderizações de um componente. Ele também permite acessar elementos reais da página, como campos de texto, botões e caixas de seleção.

Mas o que significa guardar um valor entre renderizações?

Primeiro, imagine que seu componente React é como uma folha de papel que pode ser desenhada novamente quando alguma informação muda. Cada vez que o React renderiza o componente, ele calcula como a tela deve aparecer.

O useRef funciona como um pequeno caderno que o componente mantém consigo. Você pode escrever um valor nesse caderno e consultá-lo novamente na próxima renderização.

Uma regra importante

O useRef guarda informações, mas alterar o valor de uma referência não provoca uma nova renderização.

Já o useState serve para guardar informações que, quando mudam, normalmente precisam atualizar a tela.

Você pode importar o useRef assim:

import { useRef } from 'react';

A primeira linha importa o Hook da biblioteca React para que você possa utilizá-lo no componente.

2. Para que serve o useRef?

Existem três situações muito comuns em que o useRef é útil.

1. Acessar elementos HTML

Você pode acessar um campo de texto para colocar o cursor nele automaticamente, sem precisar que o usuário clique no campo.

2. Guardar valores entre renderizações

Você pode guardar o identificador de um temporizador, o valor anterior de uma variável ou outra informação que precisa continuar disponível.

3. Guardar valores sem atualizar a tela

Você pode modificar uma referência sem solicitar que o React desenhe o componente novamente.

Atenção: se um valor precisa aparecer atualizado na tela, normalmente o useState é a melhor escolha. O useRef não substitui o estado do componente.

3. Como funciona a sintaxe do useRef?

Vamos começar com a forma mais simples de usar esse Hook.

Exemplo 1 — Criando uma referência

Objetivo: criar uma referência que começa guardando o número zero.

import { useRef } from 'react';

function MeuComponente() {
  const contadorRef = useRef(0);

  return (
    <p>Confira o console do navegador.</p>
  );
}

export default MeuComponente;

Entendendo cada parte

useRef(0): cria uma referência cujo valor inicial é zero.
contadorRef: é o nome que escolhemos para guardar essa referência.
contadorRef.current: é o lugar onde o valor guardado pode ser acessado ou modificado.
return: define o que será exibido pelo componente.

Pense no objeto retornado pelo useRef como uma pequena caixa com uma etiqueta chamada current.

contadorRef.current = 10;

console.log(contadorRef.current);

Resultado esperado no console: 10.

A primeira linha coloca o número 10 dentro da referência. A segunda linha lê o valor guardado e o mostra no console.

Por que isso funciona?

O React mantém o mesmo objeto de referência entre as renderizações do componente. Por isso, o valor de current pode continuar disponível mesmo quando o componente renderiza novamente.

4. O que é current no useRef?

A propriedade current é o lugar onde o valor da referência fica guardado.

O useRef não entrega diretamente o número ou o texto que você colocou nele. Ele entrega um objeto que possui a propriedade current.

const nomeRef = useRef('Maria');

console.log(nomeRef.current);

nomeRef.current = 'João';

console.log(nomeRef.current);

Resultado esperado:

Maria
João

Primeiro, a referência começa com o texto "Maria". Depois, mudamos seu conteúdo para "João". Quando consultamos current novamente, recebemos o novo valor.

Essa mudança, sozinha, não faz o React renderizar o componente novamente.

5. Como o useRef funciona por trás dos panos?

Para entender o useRef de verdade, precisamos entender o que é uma renderização.

Uma renderização acontece quando o React executa o componente para descobrir qual deve ser a aparência da interface.

Imagine que um componente seja uma receita. O React lê essa receita para descobrir quais elementos precisam aparecer na tela. Quando o estado muda, ele pode executar a receita novamente.

Agora compare duas situações:

Ação	O que acontece?
Alterar um estado com useState	O React agenda uma nova renderização do componente.
Alterar ref.current	O valor muda, mas essa alteração não provoca uma nova renderização.
Atualizar uma referência e depois alterar um estado	A alteração do estado pode provocar uma renderização, durante a qual o componente poderá ler o valor atual da referência.

O segredo está na diferença entre guardar um valor e pedir para a tela ser atualizada.

O useRef faz a primeira coisa. O useState é a ferramenta habitual para a segunda.

6. useRef versus useState: qual é a diferença?

Os dois Hooks guardam informações, mas são usados com objetivos diferentes.

Característica	useRef	useState
Guarda valores entre renderizações	Sim	Sim
Alterar o valor provoca renderização	Não	Normalmente, sim, quando o novo estado é diferente do anterior.
Ideal para atualizar textos na tela	Não, normalmente	Sim
Ideal para acessar um campo HTML	Sim	Não é a finalidade principal
Exemplo de uso	Focar um campo ou guardar um identificador	Contar cliques ou controlar um formulário

Exemplo 2 — Comparando useRef e useState

Objetivo: observar que modificar uma referência não atualiza automaticamente o texto exibido na tela.

import { useRef, useState } from 'react';

function Comparacao() {
  const [contador, setContador] = useState(0);
  const cliquesRef = useRef(0);

  function aumentar() {
    cliquesRef.current++;
    setContador(contador + 1);
  }

  return (
    <div>
      <p>Estado: {contador}</p>
      <button onClick={aumentar}>
        Aumentar
      </button>
    </div>
  );
}

export default Comparacao;

O que acontece ao clicar?

O React executa a função aumentar.
cliquesRef.current++ aumenta o valor guardado na referência.
setContador atualiza o estado e agenda uma renderização.
O texto na tela passa a mostrar o novo valor de contador.

Se você clicar três vezes, o texto do estado mostrará 3. A referência também guardará 3, mas ela não está sendo exibida na tela.

Importante:

Neste exemplo, a renderização acontece por causa do useState. Não acontece por causa da referência. Para atualizar o estado a partir do valor anterior, uma forma mais segura é usar setContador(valorAnterior => valorAnterior + 1).

7. Como usar useRef para acessar um elemento HTML

Uma das aplicações mais conhecidas do useRef é acessar elementos reais da página, como um campo de texto.

Imagine que você tem um formulário. Ao abrir a página, deseja que o cursor já esteja dentro do campo de nome, pronto para digitar.

Para isso, precisamos aprender duas coisas:

Criar uma referência com useRef.
Conectar essa referência ao elemento usando a propriedade ref.

Exemplo 3 — Focar automaticamente um campo

Objetivo: colocar o cursor no campo de nome assim que o componente for exibido.

import { useEffect, useRef } from 'react';

function Formulario() {
  const nomeRef = useRef(null);

  useEffect(() => {
    nomeRef.current?.focus();
  }, []);

  return (
    <div>
      <label htmlFor="nome">
        Seu nome:
      </label>

      <input
        id="nome"
        ref={nomeRef}
        type="text"
        placeholder="Digite seu nome"
      />
    </div>
  );
}

export default Formulario;

Entendendo o código passo a passo

Passo 1 — Criar a referência

const nomeRef = useRef(null);

Começamos com null porque o campo HTML ainda não foi associado à referência.

Passo 2 — Conectar ao campo

<input ref={nomeRef} />

Quando o React cria o campo e o coloca na página, ele atribui o elemento à propriedade nomeRef.current.

Passo 3 — Colocar o cursor no campo

nomeRef.current?.focus();

O método focus() coloca o foco no campo. O símbolo ?. evita tentar chamar o método se a referência ainda for null.

Passo 4 — Entender o useEffect

O useEffect permite executar um efeito depois que o React atualiza a interface. Com a lista vazia [], esse efeito é executado na montagem inicial, embora no modo Strict Mode do React possa haver um ciclo adicional de configuração e limpeza durante o desenvolvimento.

Resultado esperado:

Quando o formulário aparece, o campo de nome recebe o foco automaticamente. O usuário pode começar a digitar sem precisar clicar nele primeiro.

8. Segundo exemplo prático: contar cliques sem atualizar a tela

Agora vamos usar o useRef para guardar quantas vezes um botão foi clicado, sem exibir esse número e sem provocar renderizações por causa dessa contagem.

Exemplo 4 — Guardando uma contagem interna

Objetivo: aumentar um valor interno e consultar o resultado no console.

import { useRef } from 'react';

function ContadorInterno() {
  const cliquesRef = useRef(0);

  function registrarClique() {
    cliquesRef.current++;

    console.log(
      'Total de cliques:',
      cliquesRef.current
    );
  }

  return (
    <button onClick={registrarClique}>
      Registrar clique
    </button>
  );
}

export default ContadorInterno;

O que acontece?

O usuário clica no botão.
A função registrarClique é executada.
O valor de cliquesRef.current aumenta em um.
O console mostra a contagem atualizada.
O componente não é renderizado novamente por causa da mudança na referência.

Resultado esperado no console:

Total de cliques: 1
Total de cliques: 2
Total de cliques: 3

O botão continua funcionando porque o evento de clique executa a função. A referência guarda a contagem, mas não precisa atualizar o conteúdo visual da página.

Quando não usar essa abordagem?

Se você precisa mostrar a contagem na tela, utilize useState. O useRef é adequado aqui porque o valor serve apenas para registro interno.

9. Como usar useRef para guardar um temporizador

Outro exemplo comum é guardar o identificador de um temporizador. Esse identificador permite cancelar o temporizador depois.

Vamos usar o setTimeout, uma função do JavaScript que executa outra função depois de determinado tempo.

Exemplo 5 — Iniciar e cancelar um temporizador

import { useRef } from 'react';

function Temporizador() {
  const timerRef = useRef(null);

  function iniciar() {
    clearTimeout(timerRef.current);

    timerRef.current = setTimeout(() => {
      console.log('Tempo encerrado!');
    }, 3000);
  }

  function cancelar() {
    clearTimeout(timerRef.current);
    timerRef.current = null;
  }

  return (
    <div>
      <button onClick={iniciar}>
        Iniciar
      </button>

      <button onClick={cancelar}>
        Cancelar
      </button>
    </div>
  );
}

export default Temporizador;

Como esse exemplo funciona?

timerRef guarda o identificador do temporizador.
setTimeout agenda a mensagem para aparecer depois de três segundos.
clearTimeout cancela um temporizador que ainda não terminou.
O identificador fica na referência, então pode ser acessado pelas duas funções.

Repare que o temporizador não atualiza a interface. A mensagem aparece no console do navegador. Se você quiser exibir uma mensagem na página, utilize useState para guardar o texto que deve aparecer.

Boa prática:

Em um componente real, se um temporizador puder continuar ativo quando o componente for removido da tela, faça a limpeza apropriada. Para temporizadores iniciados por eventos, você pode usar um efeito de limpeza ou outra estratégia que garanta o cancelamento ao desmontar o componente.

10. Erros comuns ao utilizar useRef

Erro 1 — Esquecer de usar .current

Veja este código:

const nomeRef = useRef('Maria');

console.log(nomeRef);

Esse código mostra o objeto da referência, e não apenas o texto guardado nele.

A forma correta para acessar o valor é:

console.log(nomeRef.current);

Erro 2 — Esperar que a tela seja atualizada

Alterar ref.current não faz o React renderizar novamente o componente. Portanto, se o valor precisa aparecer atualizado na tela, use useState.

Erro 3 — Acessar uma referência HTML antes de ela existir

Quando uma referência está conectada a um elemento HTML, seu valor pode ser null antes da montagem ou depois que o elemento for removido.

Por isso, você pode verificar a referência antes de utilizá-la:

if (nomeRef.current) {
  nomeRef.current.focus();
}

Erro 4 — Modificar a referência durante a renderização

Evite alterar ref.current durante a execução normal do componente para tentar controlar a interface. Prefira modificar a referência em eventos, efeitos ou outros momentos apropriados.

Ler e escrever referências durante a renderização tem casos específicos, mas exige cuidado. Modificações imprevisíveis podem gerar comportamentos difíceis de entender.

Erro 5 — Usar useRef para tudo

O useRef não deve substituir o useState em todos os casos. Escolha a ferramenta conforme o objetivo.

Se você quer...	Use
Atualizar o número de curtidas na tela	useState
Colocar o cursor em um campo	useRef
Guardar um identificador de temporizador	useRef
Mostrar se um formulário foi enviado	useState

11. Boas práticas com useRef

Use useRef para guardar valores que precisam sobreviver às renderizações sem provocar novas renderizações quando mudam.
Use a propriedade current para acessar ou modificar o valor guardado.
Use referências HTML quando precisar realizar uma ação específica em um elemento, como colocar o foco.
Prefira useState para informações que precisam atualizar a interface.
Não espere que uma mudança em current apareça automaticamente na tela.
Verifique se uma referência HTML existe antes de chamar métodos nela.
Não use referências como forma de contornar o fluxo normal de dados do React.
Quando trabalhar com temporizadores ou outros recursos externos, lembre-se de limpar os recursos quando necessário.

12. Exercício prático: focar um campo ao clicar em um botão

Agora é sua vez de praticar. O objetivo é criar um campo de texto e um botão. Quando o usuário clicar no botão, o cursor deverá aparecer dentro do campo.

Passo 1 — Crie o componente

Crie um arquivo chamado CampoFoco.jsx ou CampoFoco.tsx, de acordo com a configuração do seu projeto.

Passo 2 — Importe o Hook

import { useRef } from 'react';

Passo 3 — Crie a referência

const campoRef = useRef(null);

Passo 4 — Conecte a referência ao input

<input ref={campoRef} />

Passo 5 — Crie o botão

<button
  onClick={() => campoRef.current?.focus()}
>
  Focar campo
</button>

Passo 6 — Teste o resultado

Execute o projeto, clique no botão e observe o cursor aparecer no campo de texto.

Desafio extra:

Depois de fazer o exercício funcionar, tente adicionar um segundo campo. Crie uma segunda referência e outro botão para focar o novo campo. Assim, você verá que cada referência pode apontar para um elemento diferente.

13. Perguntas frequentes sobre useRef

O useRef provoca renderização?

Não. Alterar o valor de current não provoca uma nova renderização por si só.

O valor do useRef desaparece quando o componente renderiza novamente?

Não. O React mantém o mesmo objeto de referência entre as renderizações do componente, enquanto essa instância do componente continuar montada.

Posso guardar uma string no useRef?

Sim. Você pode guardar números, textos, objetos, identificadores e outros valores JavaScript.

Posso usar useRef para acessar um botão?

Sim. Você pode conectar uma referência a um botão e, quando ele estiver montado, acessar o elemento por meio de ref.current.

O useRef substitui o useState?

Não. O useRef é indicado para valores que não precisam provocar uma renderização quando mudam. O useState é indicado para dados que controlam o que aparece na tela.

14. Resumo: o que você precisa lembrar

1. O que é:

Um Hook do React que guarda uma referência entre renderizações.

2. Como acessar o valor:

Utilize a propriedade current.

3. O que acontece quando o valor muda:

A referência é atualizada, mas isso não provoca uma nova renderização.

4. Como acessar um elemento HTML:

Crie uma referência e conecte-a ao elemento com a propriedade ref.

5. Quando usar useState:

Quando a mudança de um valor precisa atualizar a interface.

6. Quando usar useRef:

Quando você precisa guardar um valor sem provocar uma renderização ou acessar um elemento da página.

15. Conclusão

O useRef é um dos Hooks mais úteis do React quando você precisa guardar informações que devem continuar disponíveis entre renderizações ou acessar elementos HTML diretamente.

Comece praticando com campos de formulário, botões e valores guardados em current. Depois, experimente utilizá-lo para armazenar identificadores de temporizadores e outras informações internas.

Acima de tudo, lembre-se desta diferença: useRef guarda valores sem provocar uma nova renderização; useState permite guardar valores que participam da atualização da interface.

Quando você entende essa diferença, fica muito mais fácil escolher o Hook certo para cada situação e escrever componentes React mais organizados.

RECURSO RECOMENDADO

Quer continuar aprendendo programação?

Se você deseja ampliar seus conhecimentos e explorar outros assuntos da programação, conheça o curso Torne-se um Programador Fullstack e domine o mercado digital! e avalie se a proposta combina com seus objetivos de estudo.

Antes de se inscrever, consulte a página do curso para verificar o conteúdo, as tecnologias abordadas, as condições de acesso e as informações comerciais disponíveis.

Conhecer o curso →

Transparência: este artigo contém um link de afiliado. Podemos receber uma comissão caso você realize uma compra por meio dele, sem custo adicional para você.

useRef do react js