HTMLDialogElement : méthode requestClose()

Baseline 2025

Nouvellement disponible

Depuis May 2025, cette fonctionnalité fonctionne sur les appareils et les versions de navigateur les plus récents. Elle peut ne pas fonctionner sur les appareils ou navigateurs plus anciens.

La méthode requestClose() de l'interface HTMLDialogElement demande la fermeture de l'élément HTML <dialog>. Une chaîne de caractères optionnelle peut être passée en argument, ce qui met à jour la propriété returnValue de la boîte de dialogue.

Cette méthode diffère de HTMLDialogElement.close() car elle déclenche d'abord un événement cancel, puis l'événement close. Les auteur·ice·s peuvent appeler Event.preventDefault() dans le gestionnaire de l'événement cancel pour empêcher la fermeture de la boîte de dialogue.

Cette méthode expose le même comportement que le mécanisme interne de surveillance de fermeture (close watcher en anglais) du dialogue.

Dans cet article

Syntaxe

js
requestClose()
requestClose(returnValue)

Paramètres

returnValue Facultatif

Chaîne de caractères représentant la nouvelle valeur de HTMLDialogElement.returnValue de la boîte de dialogue.

Valeur de retour

Aucune (undefined).

Exemples

Utilisation de requestClose()

L'exemple suivant montre un simple bouton qui, lorsqu'il est cliqué, ouvre un élément <dialog> contenant un formulaire via la méthode showModal(). Une fois ouvert, vous pouvez cliquer sur le bouton X pour demander la fermeture de la boîte de dialogue (via la méthode HTMLDialogElement.requestClose()), ou soumettre le formulaire avec le bouton Valider.

HTML

html
<!-- Boîte de dialogue simple contenant un formulaire -->
<dialog id="favDialog">
  <form method="dialog">
    <button type="button" id="close" aria-label="fermer" formnovalidate>
      X
    </button>
    <section>
      <p>
        <label for="favAnimal">Animal préféré&nbsp;:</label>
        <select id="favAnimal" name="favAnimal">
          <option></option>
          <option>Crevette de saumure</option>
          <option>Panda roux</option>
          <option>Singe-araignée</option>
        </select>
      </p>
    </section>
    <menu>
      <li>
        <button type="reset">Réinitialiser</button>
      </li>
      <li>
        <button type="submit">Valider</button>
      </li>
    </menu>
  </form>
</dialog>

<button id="updateDetails">Mettre à jour les informations</button>

JavaScript

js
const updateButton = document.getElementById("updateDetails");
const closeButton = document.getElementById("close");
const dialog = document.getElementById("favDialog");

// Le bouton de mise à jour ouvre la boîte de dialogue modale
updateButton.addEventListener("click", () => {
  dialog.showModal();
});

// Le bouton de fermeture du formulaire demande la fermeture de la boîte de dialogue
closeButton.addEventListener("click", () => {
  dialog.requestClose("animalNonChoisi");
});

function dialogShouldNotClose() {
  // Ajouter la logique pour décider si la boîte de dialogue doit se fermer.
  // Fermeture empêchée par défaut
  return true;
}

dialog.addEventListener("cancel", (event) => {
  if (!event.cancelable) return;
  if (dialogShouldNotClose()) {
    console.log("Fermeture empêchée");
    event.preventDefault();
  }
});

Si le bouton « X » avait été de type="submit", la boîte de dialogue se serait fermée sans nécessiter de JavaScript. La soumission d'un formulaire ferme la balise <dialog> dans laquelle il est imbriqué si la méthode du formulaire est dialog, donc aucun bouton « close » n'est requis.

L'élément HTML implémentant cette interface : <dialog>

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 3 déc. 2025 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu

API HTML DOM
HTMLDialogElement
Propriétés d'instance
Méthodes d'instance
Évènements
1. cancel
2. close
Héritage
Pages liées à HTML DOM
Guides
1. Utiliser les microtâches en JavaScript avec queueMicrotask()
2. Aller plus loin : Les microtâches et l'environnement d'exécution JavaScript