English 中文 العربية 日本語 Português

forwardRef Encaminhamento de Refs

Última atualização: 2026-11-03

forwardRef Encaminhamento de Refs

Componentes de função não recebem um ref por padrão. forwardRef encaminha o ref passado pelo pai para um nó do DOM dentro do componente, para que componentes encapsulados como uma entrada personalizada ou um botão possam ser focados e medidos como um elemento nativo. O React 19 aceita uma prop ref diretamente, mas versões anteriores precisam de forwardRef. O ref precisa parar em um elemento DOM real, porque encaminhá-lo para um componente comum que não encaminha de novo deixa o pai sem nada.

GrupoEfeitos e Desempenho
TipoAPI
DesdeReact 16.3

ℹ️ Informação O editor transpila JSX para JavaScript e renderiza a UI real na sandbox; os componentes são montados automaticamente — sem render manual.

📝 Sintaxe

const FancyInput = forwardRef(function FancyInput(props, ref) {
  return <input ref={ref} {...props} />   // attach it to the real DOM
})

// usage: <FancyInput ref={inputRef} />

⚙️ Parâmetros

render functionUma função no formato (props, ref) => JSX. O segundo argumento é o ref passado pelo pai, e deve ser anexado a um nó DOM real ou a um componente que o encaminhe adiante.

Retorna：Retorna um novo componente capaz de encaminhar um ref: ref.current no pai apontará para o nó ao qual a função de renderização o anexou.

▶ Exemplo

O exemplo roda direto: renderiza automaticamente ao expandir e edições valem na hora.

Saída：

Após o clique, a entrada com borda azul é focada e seu conteúdo é limpo — o ref atravessou a embalagem do FancyInput e alcançou o input real dentro dela.
▶ Experimente

💡 Pontos-chave

💡 Dica No React 19 um componente de função pode receber uma prop ref diretamente, então forwardRef não é mais necessário; versões anteriores exigem-no.
ℹ️ Informação O argumento ref deve ser anexado a um elemento DOM real; anexá-lo a um componente comum que não encaminha significa que o pai não recebe nada.
⚠️ Aviso Não abuse de refs encaminhados para mexer dentro de um componente filho — prefira props declarativas, e combine useImperativeHandle com ele quando precisar de uma interface imperativa mais rica.
useref ref-container component usestate
Mais casos em breve.

📚 Tutoriais Relacionados

useRef e o DOM
Lição 10: forwardRef faz componentes encapsulados também poderem ser focados.

❓ Perguntas Frequentes

P Por que um componente de função não pode receber um ref diretamente?
R Um componente de função não tem instância para um ref se anexar; React 18 e anteriores mantiveram o ref fora de props, então forwardRef teve de encaminhá-lo explicitamente.
P O que mudou no React 19?
R O ref virou uma prop comum, então um componente de função pode simplesmente escrever function Cmp({ ref }), e forwardRef não é mais obrigatório (embora ainda funcione).
P Como useImperativeHandle difere do encaminhamento direto?
R O encaminhamento direto expõe o nó DOM inteiro; useImperativeHandle deixa você definir o conjunto de métodos expostos (focus, clear, …) e esconder a implementação.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%