forwardRef: Expondo Referências do DOM aos Componentes Pai

Uma referência é uma forma de manter uma referência a um nó do DOM ou a uma instância de componente que persiste entre renderizações sem provocar novas renderizações. Você a associa usando o atributo de referência, e o React preenche sua propriedade current depois de confirmar as alterações no DOM.

O problema é que não é possível associar uma referência a um componente de função da mesma forma que a uma div. Por padrão, o pai não tem como alcançar o nó do DOM que vive dentro de um componente filho, porque as referências não são transmitidas como propriedades comuns.

React.forwardRef permite que um componente receba uma referência do pai e a encaminhe para um de seus próprios elementos. Ele encapsula a função do componente e altera a assinatura da função para que a referência chegue como um segundo argumento, junto com as propriedades.

Esse é o mecanismo oficial para expor um nó do DOM interno a um componente chamador, transformando um filho que, de outra forma, seria opaco em um elemento que o pai pode referenciar diretamente.

A função encapsulada recebe dois parâmetros: (props, ref). O primeiro é o objeto usual de propriedades, e o segundo é a referência encaminhada. Em seguida, você distribui ou associa essa referência ao elemento que deseja expor, como em ref={ref} em um campo de entrada interno.

Lembre-se de que somente componentes encapsulados com forwardRef recebem esse segundo argumento. Um componente de função comum que liste ref como segundo parâmetro simplesmente receberá undefined.

O exemplo clássico é um componente reutilizável de campo de texto cujo campo de entrada interno você deseja que o pai possa focalizar. Ao encapsular o campo com forwardRef e associar a referência encaminhada ao elemento de entrada subjacente, o pai pode chamar diretamente o método de foco desse elemento.

Isso mantém o componente de campo reutilizável e, ao mesmo tempo, concede acesso imperativo controlado exatamente onde ele é necessário, como para focalizar o primeiro campo de um formulário na montagem.

As referências encaminhadas também permitem fazer medições. O pai pode ler offsetWidth e offsetHeight ou chamar getBoundingClientRect em um elemento filho recebido por meio de forwardRef.

Isso é útil para dicas de ferramentas, popovers e cálculos de layout nos quais o pai precisa saber o tamanho ou a posição exatos do elemento interno renderizado antes de decidir como posicionar algo em relação a ele.

Como a referência encaminhada aponta para um nó real do DOM, o pai pode invocar métodos nativos do DOM nele. Chamar scrollIntoView em um item de lista encaminhado faz com que ele apareça suavemente na tela, e chamar scrollTo em um contêiner de rolagem encaminhado reposiciona o conteúdo.

Essas são ações imperativas que não têm uma alternativa declarativa adequada, exatamente o tipo de interação para o qual as referências foram criadas.

Às vezes, o elemento que você deseja expor está enterrado em várias camadas de componentes. Você pode encadear forwardRef para que cada camada intermediária encaminhe a referência recebida para a próxima, até que ela finalmente chegue ao nó do DOM desejado.

Cada encapsulador da cadeia precisa usar forwardRef e passar a referência adiante, pois um componente comum no meio interromperia a conexão.

forwardRef e React.memo podem ser combinados para obter tanto o encaminhamento de referências quanto a memoização das renderizações. A ordem usual é memo(forwardRef(Component)), encapsulando o resultado de forwardRef para que a comparação da memoização continue sendo aplicada.

Esse padrão aparece em sistemas de componentes sensíveis ao desempenho, nos quais um componente renderizado com frequência precisa expor seu nó e evitar novas renderizações desnecessárias.

No React DevTools, um componente forwardRef aparece com um rótulo ForwardRef envolvendo o nome do seu componente. Isso facilita confirmar rapidamente que um componente participa do encaminhamento de referências.

Você pode dar um nome à função interna ou definir um displayName para tornar a entrada no DevTools mais clara do que um rótulo ForwardRef anônimo e genérico.

forwardRef serve para expor nós do DOM e identificadores imperativos, não para transmitir dados. Se o pai precisar influenciar um filho, prefira propriedades e estado comuns em vez de acessá-lo por meio de uma referência.

O uso excessivo de referências cria um acoplamento forte entre os componentes e ignora o fluxo de dados do React, tornando o comportamento mais difícil de acompanhar. Use forwardRef somente quando uma propriedade declarativa realmente não puder expressar a interação.

forwardRef continua sendo a ferramenta padrão para expor referências em bibliotecas de componentes e campos de entrada reutilizáveis. As versões mais recentes do React estão avançando para permitir que a referência seja transmitida como uma propriedade comum, mas forwardRef ainda é amplamente usado e continua importante compreendê-lo.

Conhecê-lo bem prepara você tanto para bases de código existentes quanto para os mecanismos subjacentes sobre os quais qualquer sintaxe futura de referência como propriedade será construída.

Teste sua compreensão de como um componente forwardRef recebe sua referência.

forwardRef resolve a limitação de o pai não conseguir alcançar o nó do DOM de um componente filho ao fornecer ao componente um segundo argumento de referência que ele pode encaminhar para um elemento interno. Isso permite focalizar, medir e rolar elementos filhos.

Ele pode ser combinado com memo, encadeado por várias camadas e aparece como ForwardRef no DevTools. Use-o para acesso imperativo ao DOM, não para transmitir dados, tarefa para a qual as propriedades são mais adequadas.