useWatchFieldArray

Ce hook encapsule useFieldArray et useWatch pour fournir un tableau de champs contrôlés avec les dernières valeurs observées en temps réel. Il est particulièrement utile pour les formulaires dynamiques où vous avez besoin d'accéder aux valeurs actuelles du tableau tout en gérant l'ajout, la suppression et la réorganisation des éléments.

Retour du hook

Le hook retourne un objet contenant :

Propriété	Type	Description
fields	Array<T & Record<string>>	Tableau des champs avec les valeurs à jour en temps réel
append	Function	Ajoute un nouvel élément au tableau
prepend	Function	Ajoute un nouvel élément au début du tableau
insert	Function	Insère un élément à une position spécifique
remove	Function	Supprime un élément du tableau
swap	Function	Échange la position de deux éléments
move	Function	Déplace un élément d'une position à une autre
replace	Function	Remplace tous les éléments du tableau

Utilisation basique

import { useForm } from 'react-hook-form';
import { useWatchFieldArray } from '@/hooks/use-watch-field-array';

interface ContactForm {
  contacts: {
    name: string;
    email: string;
  }[];
}

export function ContactList() {
  const { control } = useForm<ContactForm>({
    defaultValues: {
      contacts: [
        { name: 'John', email: 'john@example.com' },
      ],
    },
  });

  const { fields, append, remove } = useWatchFieldArray({
    control,
    name: 'contacts',
  });

  return (
    <div>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input {...register(`contacts.${index}.name`)} />
          <input {...register(`contacts.${index}.email`)} />
          <button onClick={() => remove(index)}>Supprimer</button>
        </div>
      ))}
      <button onClick={() => append({ name: '', email: '' })}>
        Ajouter un contact
      </button>
    </div>
  );
}

Paramètres

Props

interface UseWatchFieldArrayProps {
  control: Control<FieldValues>;      // Contrôle du formulaire React Hook Form
  name: FieldArrayPath<TFieldValues>; // Chemin du tableau dans le formulaire
  keyName?: string;                   // Nom de la propriété d'identification (par défaut: "id")
  shouldUnregister?: boolean;         // Supprime les champs lors de la suppression (par défaut: false)
}

Fonctionnement

1. Initialisation : useFieldArray gère la structure du tableau et les opérations CRUD
2. Surveillance : useWatch observe les changements en temps réel de tous les champs du tableau
3. Fusion : Les valeurs observées sont fusionnées avec les métadonnées des champs (id, etc.)
4. Retour : Les champs contrôlés sont retournés avec les données actualisées

Cas d'usage courants

1. Affichage des valeurs actuelles

const { fields } = useWatchFieldArray({ control, name: 'items' });

// fields contient les valeurs en temps réel
console.log(fields[0].name); // Valeur actuelle, pas juste la valeur initiale

2. Conditions basées sur les valeurs

const { fields } = useWatchFieldArray({ control, name: 'products' });

{fields.map((field, idx) => (
  <div key={field.id}>
    {field.quantity > 10 && <span>Stock élevé</span>}
    {field.quantity === 0 && <span style={{ color: 'red' }}>Rupture de stock</span>}
  </div>
))}

3. Opérations en lot

const { fields, remove } = useWatchFieldArray({ control, name: 'items' });

const removeCompleted = () => {
  fields.forEach((field, index) => {
    if (field.completed) remove(index);
  });
};

Points importants

• ⚠️ Les valeurs de fields sont toujours à jour grâce à useWatch
• ⚠️ Utilisez field.id comme clé React pour chaque élément du tableau
• ℹ️ Compatible avec tous les validateurs React Hook Form
• ℹ️ Les valeurs observées prennent la priorité sur les valeurs de useFieldArray
• ✅ Parfait pour les formulaires dynamiques complexes
• ✅ Permet d'afficher les valeurs en temps réel sans passer par getValues()

Différences avec useFieldArray standard

Aspect	useFieldArray	useWatchFieldArray
Valeurs à jour	Non, nécessite getValues()	Oui, en temps réel
Performance	Meilleure	Légèrement plus lourd
Cas d'usage	Gestion simple de tableaux	Affichage et gestion avancée
Complexité	Simple	Modérée

Sources

• Documentation react-hook-form : https://react-hook-form.com/
• useFieldArray : https://react-hook-form.com/docs/usefieldarray
• useWatch : https://react-hook-form.com/docs/usewatch