useImperativeHandle

Définition

Hook qui personnalise la valeur exposée par la ref d'un composant, pour n'exposer que quelques méthodes (focus, reset) au parent. Depuis React 19 (5 décembre 2024), la ref arrive comme une prop ordinaire : forwardRef n'est plus nécessaire et sera déprécié.

Analogie

Comme un interphone d'immeuble : tu choisis quels boutons exposer, pas toutes les clés de l'appartement.

Exemple de code

// React 19 : `ref` est une prop, plus besoin de forwardRef
function FancyInput({ ref, ...props }) {
  const inputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current.focus(),
    clear: () => { inputRef.current.value = ''; },
  }), []);
  return <input ref={inputRef} {...props} />;
}
// Parent
const ref = useRef(null);
<FancyInput ref={ref} />; ref.current.focus();

Cas d'usage

Exposer une API impérative limitée a un composant enfant (focus, scroll, reset).

Anti-pattern

Termes liés

Sources

• react.dev/blog/2024/12/05/react-19
• react.dev/reference/react/forwardRef