forwardRef : exposer les références DOM aux composants parents

Une référence, ou ref, permet de conserver une référence vers un nœud DOM ou une instance de composant. Elle persiste d’un rendu à l’autre sans provoquer de nouveaux rendus. Vous l’attachez avec l’attribut ref, puis React renseigne sa propriété current après avoir validé les modifications dans le DOM.

Le problème est que vous ne pouvez pas attacher une référence à un composant fonctionnel comme vous le feriez à un div. Par défaut, un parent ne dispose d’aucun moyen d’atteindre le nœud DOM situé à l’intérieur d’un composant enfant, car les références ne sont pas transmises comme des props ordinaires.

React.forwardRef permet à un composant de recevoir une référence de son parent et de la transmettre à l’un de ses propres éléments. Il encapsule votre fonction de composant et modifie sa signature afin que la référence arrive comme second argument, en plus des props.

C’est le mécanisme officiel permettant d’exposer un nœud DOM interne à un composant appelant : un enfant autrement opaque devient un composant dont le parent peut référencer directement l’élément.

La fonction encapsulée reçoit deux paramètres : (props, ref). Le premier est l’objet props habituel et le second est la référence transmise. Vous étalez ensuite cette référence sur l’élément que vous souhaitez exposer ou vous l’y attachez, par exemple avec ref={ref} sur un champ de saisie interne.

Souvenez-vous que seuls les composants encapsulés avec forwardRef reçoivent ce second argument. Un composant fonctionnel ordinaire qui déclare ref comme second paramètre reçoit simplement undefined.

L’exemple classique est celui d’un composant de champ de texte réutilisable dont le parent doit pouvoir donner le focus au champ de saisie interne. En encapsulant le champ avec forwardRef et en attachant la référence transmise à l’élément de saisie sous-jacent, le parent peut appeler focus directement dessus.

Le composant de champ reste ainsi réutilisable tout en offrant un accès impératif contrôlé exactement là où il est nécessaire, par exemple pour donner le focus au premier champ d’un formulaire lors de son montage.

Les références transmises permettent également d’effectuer des mesures. Un parent peut lire offsetWidth ou offsetHeight, ou appeler getBoundingClientRect sur un élément enfant reçu par l’intermédiaire de forwardRef.

C’est utile pour les info-bulles, les fenêtres contextuelles et les calculs de mise en page lorsque le parent doit connaître la taille ou la position exactes d’un élément interne rendu avant de décider où placer un autre élément par rapport à lui.

Comme la référence transmise pointe vers un véritable nœud DOM, le parent peut appeler ses méthodes DOM natives. L’appel de scrollIntoView sur un élément de liste dont la référence a été transmise l’amène progressivement dans la zone visible, tandis que scrollTo sur un conteneur de défilement dont la référence a été transmise repositionne son contenu.

Ce sont des actions impératives qui n’ont pas d’équivalent déclaratif satisfaisant, ce qui correspond exactement au type d’interaction que les références sont destinées à gérer.

L’élément que vous souhaitez exposer est parfois enfoui plusieurs composants plus bas. Vous pouvez chaîner forwardRef afin que chaque couche intermédiaire transmette la référence reçue à la suivante, jusqu’à ce qu’elle atteigne finalement le nœud DOM cible.

Chaque encapsulation de la chaîne doit elle-même utiliser forwardRef et transmettre la référence, car un composant ordinaire au milieu interromprait la connexion.

forwardRef et React.memo peuvent être combinés pour obtenir à la fois la transmission des références et la mémorisation des rendus. L’ordre habituel est memo(forwardRef(Component)) : le résultat de forwardRef est encapsulé afin que la comparaison de mémorisation continue de s’appliquer.

Ce modèle apparaît dans les systèmes de conception sensibles aux performances, lorsqu’un composant rendu fréquemment doit à la fois exposer son nœud et éviter les rendus inutiles.

Dans React DevTools, un composant forwardRef apparaît avec l’étiquette ForwardRef qui encapsule le nom de votre composant. Cela permet de vérifier immédiatement qu’un composant participe à la transmission des références.

Vous pouvez donner un nom à la fonction interne ou définir un displayName afin de rendre l’entrée de DevTools plus explicite qu’une étiquette ForwardRef anonyme et générique.

forwardRef sert à exposer des nœuds DOM et des poignées impératives, pas à transmettre des données. Si un parent doit agir sur un enfant, privilégiez les props et l’état ordinaires plutôt que d’y accéder au moyen d’une référence.

L’utilisation excessive des références couple étroitement les composants et contourne le flux de données de React, ce qui rend le comportement plus difficile à suivre. Utilisez forwardRef uniquement lorsqu’une prop déclarative ne peut véritablement pas exprimer l’interaction.

forwardRef reste l’outil standard pour exposer des références dans les bibliothèques de composants et les champs de saisie réutilisables. Les versions plus récentes de React évoluent vers la possibilité de transmettre ref comme une prop ordinaire, mais forwardRef est toujours largement utilisé et reste important à comprendre.

Une bonne maîtrise de cet outil vous prépare à travailler aussi bien sur les bases de code existantes que sur les mécanismes sous-jacents des futures syntaxes ref-as-prop.

Vérifiez votre compréhension de la manière dont un composant forwardRef reçoit sa référence.

forwardRef résout la limitation qui empêche un parent d’atteindre le nœud DOM d’un composant enfant en donnant au composant un second argument ref qu’il peut transmettre à un élément interne. Cela permet de donner le focus aux éléments enfants, de les mesurer et de les faire défiler.

Il se compose avec memo, peut être chaîné à travers plusieurs niveaux et apparaît sous le nom ForwardRef dans DevTools. Utilisez-le pour accéder impérativement au DOM, et non pour transmettre des données, ce que les props permettent de faire plus efficacement.