forwardRef no React: Encaminhando Refs em Componentes Customizados
📑 Índice do Conteúdo
1. O Desafio das Refs em Componentes Customizados
Na Lição 21, aprendemos que passar o atributo ref={minhaRef} para um elemento nativo do HTML (como <input /> ou <button />) faz com que o React anexe automaticamente o nó real do DOM a minhaRef.current.
No entanto, em aplicações corporativas modernas e sistemas de design (Design Systems), raramente usamos tags HTML brutas soltas pelo código. Em vez disso, encapsulamos os elementos em componentes customizados com estilos, rótulos e comportamentos padronizados:
// ❌ TENTATIVA DIRETA: Passando 'ref' para um componente funcional comum
function Formulario() {
const inputRef = useRef(null);
// Tentamos passar a ref para nosso componente estilizado:
return <CampoTexto ref={inputRef} label="E-mail Corporativo" />;
}
function CampoTexto({ label }) {
// O React NÃO repassa a propriedade 'ref' dentro do objeto props!
return (
<div className="campo">
<label>{label}</label>
<input type="text" />
</div>
);
}
Se você executar o código acima no React 16, 17 ou 18, o React emitirá um alerta explícito no console:
“Warning: Function components cannot be given refs. Attempts to access this ref will fail. Did you mean to use React.forwardRef()?”
Por que isso acontece? Porque historicamente no React, ref (assim como key) é uma palavra-chave reservada. O React a consome internamente e não a entrega dentro do objeto props do componente.
2. A Solução Clássica: O Wrapper React.forwardRef
Para permitir que um componente funcional receba uma referência vinda do componente pai e a repasse (“encaminhe”) para um nó interno do DOM, utilizamos o utilitário React.forwardRef:
import { forwardRef } from 'react';
// ✅ COMPONENTE COM REFS ENCAMINHADAS:
const CampoTexto = forwardRef((props, ref) => {
return (
<div className="campo-customizado">
<label>{props.label}</label>
{/* O nó nativo <input> recebe a 'ref' repassada pelo pai: */}
<input ref={ref} type="text" {...props} />
</div>
);
});
// Boa prática para o React DevTools:
CampoTexto.displayName = 'CampoTexto';
Anatomia do forwardRef
Diferente de um componente funcional comum que recebe apenas (props), a função passada para forwardRef recebe dois argumentos distintos:
props: O objeto contendo todas as propriedades convencionais enviadas pelo componente pai (ex:label,placeholder, etc.).ref: A referência específica criada pelo pai viauseRef, pronta para ser anexada ao nó filho que deve ser exposto.
3. Aplicações Vitais em Design Systems e Bibliotecas
O forwardRef é a espinha dorsal de qualquer biblioteca de componentes de produção (como Material UI, Radix UI, Shadcn/UI e Chakra UI):
- Integração com Validação de Formulários: Bibliotecas populares como o
react-hook-formutilizam refs nativas para gerenciar validações e foco automático em campos com erro (via{...register('email')}). SemforwardRef, componentes customizados não funcionam com essas ferramentas. - Bibliotecas de Animação: Ferramentas como GSAP ou Framer Motion exigem medir e animar o elemento físico real do DOM.
- Modais e Menus Flutuantes: Para calcular a posição de tooltips e dropdowns (`getBoundingClientRect`) em relação ao botão disparador.
4. A Evolução no React 19: O Fim Gradual do forwardRef
Uma das simplificações mais comemoradas introduzidas no React 19 foi o tratamento unificado de refs. No React 19+, a propriedade ref deixa de ser tratada como palavra-chave especial e passa a ser entregue diretamente dentro do objeto props:
// 🚀 SINTAXE MODERNA NO REACT 19+:
// Não precisa mais de forwardRef! 'ref' é uma prop comum:
function CampoTexto({ label, ref, ...props }) {
return (
<div className="campo">
<label>{label}</label>
<input ref={ref} {...props} />
</div>
);
}
💡 Por Que Você Ainda Deve Dominar o forwardRef?
Embora o React 19 tenha simplificado a sintaxe, mais de 90% das empresas e bases de código em produção operam em React 16, 17 e 18.
Dominar o forwardRef é requisito obrigatório em entrevistas técnicas e no dia a dia da engenharia de software corporativa.
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