Événement submit et méthode submit() en JavaScript

La gestion des soumissions de formulaires est l'une des tâches les plus courantes en JavaScript front-end. Les formulaires permettent aux utilisateurs d'envoyer des données à un serveur — connexion, inscription, recherche, commande — et vous souhaitez presque toujours avoir la possibilité de valider, transformer ou confirmer ces données avant qu'elles ne quittent la page.

Il existe deux outils liés mais distincts pour cela :

• L'événement submit — déclenché par le navigateur lorsque l'utilisateur tente de soumettre un formulaire (en cliquant sur un bouton de soumission ou en appuyant sur Entrée dans un champ). C'est ici que vous exécutez la validation et décidez d'autoriser ou d'annuler l'envoi.
• La méthode form.submit() — soumet le formulaire par programmation depuis votre code, sans aucune action de l'utilisateur.

Un piège important qui surprend de nombreux développeurs : ces deux outils ne sont pas symétriques. Appeler form.submit() ne déclenche pas l'événement submit et ignore entièrement la validation des contraintes. Nous verrons pourquoi, et ce qu'il faut utiliser à la place.

Comprendre l'événement submit

L'événement submit se déclenche lorsqu'un formulaire est sur le point d'envoyer ses données. Il est annulable : appeler event.preventDefault() dans le gestionnaire empêche le navigateur de naviguer ailleurs, ce qui vous permet de maintenir l'utilisateur sur la page pour valider les entrées, afficher des erreurs ou envoyer les données avec fetch à la place.

L'événement se déclenche lorsque :

• L'utilisateur clique sur un <button type="submit"> ou un <input type="submit"> dans le formulaire.
• L'utilisateur appuie sur Entrée alors qu'il est dans un champ texte d'un formulaire possédant un bouton de soumission.

Il ne se déclenche pas lorsque vous appelez form.submit() depuis JavaScript (voir ci-dessous).

Exemple : validation du formulaire avant soumission

Ce script empêche la soumission du formulaire si les champs ne sont pas correctement remplis, en affichant un message d'erreur à l'utilisateur. Il s'appuie sur la validation des contraintes intégrée du navigateur (l'attribut required et type="email") via checkValidity().

<div>
  <form style="display: flex; justify-content: center; gap: 2px; align-items: center; flex-direction: column;" id="registrationForm">
    Username: <input type="text" name="username" required />
    Email: <input type="email" name="email" required />
    <button type="submit">Register</button>
  </form>
  <div id="message" style="margin-top: 10px; text-align:center;"></div> <!-- Message container for feedback -->
  <script>
    const form = document.getElementById('registrationForm');
    form.addEventListener('submit', function(event) {
      event.preventDefault(); // Prevent actual form submission to a server
      const messageDiv = document.getElementById('message');
      if (!this.checkValidity()) {
        messageDiv.textContent = 'Please fill all required fields correctly.';
        messageDiv.style.color = 'red'; // Display the message in red for errors
      } else {
        messageDiv.textContent = 'The form was successfully submitted.';
        messageDiv.style.color = 'green'; // Display the message in green for success
        form.reset(); // Reset the form fields after successful submission
      }
    });
  </script>
</div>

Fonctionnalité JavaScript :

• Écouteur d'événement : Un écouteur d'événement est attaché au formulaire, il se déclenche lorsque l'utilisateur tente de soumettre le formulaire.
• Vérification de la validation : La fonction checkValidity() est utilisée ici. C'est une méthode HTML intégrée des formulaires qui vérifie toutes les entrées du formulaire par rapport à leurs règles de validation (comme l'attribut required dans ce cas). Si un champ ne respecte pas sa règle de validation, la fonction retourne false.
• Empêcher la soumission : Si checkValidity() retourne false (signifiant que le formulaire contient des champs requis invalides ou vides), le script empêche la soumission du formulaire au serveur. À la place, il affiche un message demandant à l'utilisateur de remplir correctement tous les champs requis.
• Gestion de la soumission : Si tous les champs sont valides, le formulaire affiche un message de succès au lieu d'afficher une page vide ou de soumettre à un serveur. Dans une application réelle, c'est ici que vous appelleriez fetch() pour envoyer les données.

Lecture des données soumises

Dans le gestionnaire, vous souhaitez généralement récupérer les valeurs saisies par l'utilisateur. La méthode la plus propre est l'objet FormData, qui collecte tous les contrôles nommés en une seule étape :

const form = document.getElementById("registrationForm");
form.addEventListener("submit", (event) => {
  event.preventDefault();
  const data = Object.fromEntries(new FormData(form));
  console.log(data.username, data.email);
  // data is a plain object: { username: "...", email: "..." }
});

Identifier le bouton cliqué

Lorsqu'un formulaire comporte plusieurs boutons de soumission (par exemple « Enregistrer » et « Supprimer »), l'événement submit vous indique lequel a déclenché la soumission via event.submitter :

form.addEventListener("submit", (event) => {
  event.preventDefault();
  // event.submitter is the button element that caused submission
  console.log("Submitted via:", event.submitter?.value);
});

Utiliser la méthode .submit()

La méthode .submit() initie la soumission d'un formulaire par programmation — directement depuis votre code, sans clic de l'utilisateur. Elle est utile lorsqu'un formulaire doit être envoyé après qu'une condition est remplie (un minuteur, une vérification automatisée réussie, une valeur calculée en JavaScript).

Deux mises en garde font que .submit() se comporte différemment d'une soumission déclenchée par l'utilisateur :

• Elle ne déclenche pas l'événement submit, donc toute validation ou logique que vous avez attachée à cet événement est ignorée.
• Elle n'exécute pas la validation des contraintes du navigateur, donc les règles required et type sont ignorées.

C'est intentionnel — historiquement, .submit() était conçu pour envoyer sans réexécuter le gestionnaire qui l'avait appelé (ce qui créerait sinon une boucle infinie). La plupart du temps, il est préférable d'utiliser form.requestSubmit() à la place (décrit ci-dessous), qui se comporte comme une vraie soumission par l'utilisateur.

Exemple : soumission de formulaire par programmation

L'exemple ci-dessous soumet un formulaire depuis le code dès que la page se charge. Comme le formulaire n'a pas d'attribut action, il renvoie vers la page courante ; l'alerte affiche la valeur du champ caché pour montrer ce qui serait envoyé :

<!DOCTYPE html>
<html>
<head>
  <title>Auto Submit Form Demo</title>
</head>
<body>
  <form id="autoSubmitForm">
    <input type="hidden" name="data" value="Automatic Submission" />
  </form>
  <script>
    function submitFormAutomatically() {
      document.getElementById('autoSubmitForm').submit();
      alert("Form submitted with data: " + document.getElementById('autoSubmitForm').data.value);
    }
    document.addEventListener('DOMContentLoaded', submitFormAutomatically); // Call the function when the DOM is ready
  </script>
</body>
</html>

Notez que document.getElementById('autoSubmitForm').data fonctionne parce que les contrôles de formulaire nommés sont exposés en tant que propriétés sur l'élément de formulaire — form.data retourne l'élément <input name="data">, et .value lit sa valeur.

Préférer requestSubmit() à submit()

form.requestSubmit() est la contrepartie moderne et plus sûre de form.submit(). Contrairement à .submit(), elle :

• déclenche l'événement submit, donc vos gestionnaires de validation s'exécutent ;
• exécute la validation des contraintes du navigateur et affiche les bulles d'erreur natives si un champ est invalide ;
• accepte optionnellement un bouton pour que event.submitter soit défini, par ex. form.requestSubmit(saveButton).

const form = document.getElementById("registrationForm");
// Behaves exactly like a real user click on the submit button:
form.requestSubmit();

Si vous avez vraiment besoin du comportement de contournement de .submit() mais souhaitez tout de même que votre gestionnaire s'exécute, vous pouvez dispatcher l'événement vous-même avec form.dispatchEvent(new Event('submit', { cancelable: true })) — mais dans presque tous les cas, requestSubmit() est le bon choix.

Combiner .submit() avec des écouteurs d'événements

Vous pouvez également conditionner la soumission à vos propres critères : n'envoyer le formulaire que lorsque certaines conditions sont remplies. L'exemple ci-dessous utilise un bouton ordinaire (non de type submit) pour que rien ne se passe tant que JavaScript ne décide pas d'appeler submit().

Exemple : soumission conditionnelle de formulaire

<form id="conditionalForm">
  Accept Terms: <input type="checkbox" id="acceptTerms">
  <button type="button" onclick="checkAndSubmit()">Submit</button>
</form>
<script>
  function checkAndSubmit() {
    var form = document.getElementById('conditionalForm');
    var termsCheckbox = document.getElementById('acceptTerms');
    if (termsCheckbox.checked) {
      form.submit();
    } else {
      alert('You must accept the terms and conditions to proceed.');
    }
  }
</script>

Ce code propose un bouton qui, lorsqu'on clique dessus, vérifie si une case à cocher est cochée avant de soumettre le formulaire. Si les conditions générales ne sont pas acceptées, l'utilisateur reçoit une alerte. Notez que puisque form.submit() est utilisé ici, l'événement submit ne se déclenchera pas — remplacez-le par form.requestSubmit() si vous avez également un écouteur submit que vous souhaitez exécuter.

Événement submit vs. submit() vs. requestSubmit()

Règle de base : écoutez l'événement submit pour valider et intercepter ; appelez requestSubmit() pour déclencher une soumission depuis le code ; utilisez .submit() uniquement lorsque vous avez spécifiquement besoin de contourner vos propres gestionnaires.

Conclusion

L'événement submit vous permet d'intercepter et de valider un formulaire avant qu'il ne quitte la page, tandis que .submit() et requestSubmit() vous permettent de l'envoyer depuis le code. Le point essentiel à retenir est que .submit() ignore silencieusement à la fois l'événement submit et la validation — il est donc préférable d'utiliser requestSubmit() sauf si vous souhaitez délibérément ce contournement. Combinés avec event.preventDefault() et FormData, ces outils vous donnent un contrôle total sur la façon dont les données utilisateur sont collectées et envoyées.

Pour aller plus loin, consultez les propriétés et méthodes de formulaires, l'API de validation des contraintes, les événements change et input pour les réactions en temps réel sur les champs, et focus et blur pour l'interaction au niveau des champs.

Pratique