Section courante

A propos

Section administrative du site

useImperativeHandle

 Utilise un gestionnaire impératif
React

Syntaxe

useImperativeHandle(ref, createHandle, dependencies?)

Description

useImperativeHandle est un crochet React vous permettant de personnaliser le descripteur exposé en tant que référence.

Référence

useImperativeHandle(ref, createHandle, dependencies?)

Appelez useImperativeHandle au niveau supérieur de votre composante pour personnaliser le descripteur de référence qu'il expose :

  1. import { useImperativeHandle } from 'react';
  2.  
  3. function MyInput({ ref }) {
  4.   useImperativeHandle(ref, () => {
  5.     return {
  6.       // ... vos méthodes ...
  7.     };
  8.   }, []);
  9.   // ...

Paramètres

Nom Description
ref la référence que vous avez reçue comme propriété de composante MyInput.
createHandle une fonction qui ne prend aucun argument et renvoie le descripteur de la référence à exposer. Ce descripteur peut être de n'importe quel type. En général, vous renverrez un objet avec les méthodes à exposer.
dependencies facultatives : la liste de toutes les valeurs réactives référencées dans le code createHandle. Les valeurs réactives incluent les propriétés, l'état et toutes les variables et fonctions déclarées directement dans le corps du composant. Si votre linter est configuré pour React, il vérifiera que chaque valeur réactive est correctement spécifiée comme dépendance. La liste des dépendances doit comporter un nombre constant d'éléments et être écrite en ligne, comme [dep1, dep2, dep3]. React comparera chaque dépendance à sa valeur précédente grâce à la comparaison Object.is. Si un nouveau rendu entraîne une modification d'une dépendance, ou si vous avez omis cet argument, votre fonction createHandle se réexécutera et le descripteur nouvellement créé sera assigné à la référence.

Remarque

À partir de React 19, ref est disponible en tant que prop. Dans React 18 et les versions antérieures, il était nécessaire d'obtenir la ref depuis forwardRef.

Renvoie

useImperativeHandle renvoie undefined.

Utilisation

Exposer un descripteur de ref personnalisé aux composantes parent

Pour exposer un noeud DOM à l'élément parent, transmettez la prop ref au noeud.

  1. function MyInput({ ref }) {
  2.   return <input ref={ref} />;
  3. };

Avec le code ci-dessus, une référence à MyInput recevra le noeud DOM <input>. Cependant, vous pouvez exposer une valeur personnalisée. Pour personnaliser le descripteur exposé, appelez useImperativeHandle au niveau supérieur de votre composante :

  1. import { useImperativeHandle } from 'react';
  2.  
  3. function MyInput({ ref }) {
  4.   useImperativeHandle(ref, () => {
  5.     return {
  6.       // ... vos méthodes ...
  7.     };
  8.   }, []);
  9.  
  10.   return <input />;
  11. };

Notez que dans le code ci-dessus, la référence n'est plus transmise à l'élément <input>.

Par exemple, supposons que vous ne souhaitiez pas exposer l'intégralité du noeud DOM <input>, mais que vous souhaitiez exposer deux de ses méthodes : focus et scrollIntoView. Pour ce faire, conservez le DOM du navigateur réel dans une référence distincte. Utilisez ensuite useImperativeHandle pour exposer un descripteur contenant uniquement les méthodes que la composante parent doit appeler :

  1. import { useRef, useImperativeHandle } from 'react';
  2.  
  3. function MyInput({ ref }) {
  4.   const inputRef = useRef(null);
  5.  
  6.   useImperativeHandle(ref, () => {
  7.     return {
  8.       focus() {
  9.         inputRef.current.focus();
  10.       },
  11.       scrollIntoView() {
  12.         inputRef.current.scrollIntoView();
  13.       },
  14.     };
  15.   }, []);
  16.  
  17.   return <input ref={inputRef} />;
  18. };

Désormais, si la composante parente obtient une référence à MyInput, il pourra appeler les méthodes focus et scrollIntoView. Cependant, il n'aura pas un accès complet au noeud DOM <input> sous-jacent.

Dernière mise à jour : Mercredi, le 10 septembre 2025