Construire une modale React accessible est plus difficile qu’il n’y paraît

Avant d’écrire du JSX, décrivez ce qui doit se produire du point de vue de l’utilisateur.

• L’activation du déclencheur ouvre la modale et déplace le focus vers un emplacement choisi à l’intérieur.
• Tab et Maj+Tab restent dans la modale active tant que celle-ci est modale.
• Échap ferme uniquement la modale fermable située au sommet de la pile.
• La fermeture rend le focus à l’élément qui a ouvert la modale, ou à une solution de repli pertinente si cet élément n’existe plus.
• La modale possède un nom, ainsi qu’une description facultative, que les technologies d’assistance peuvent annoncer.
• Le contenu d’arrière-plan est visuellement masqué et indisponible à l’interaction.
• La page derrière la modale ne défile pas, tandis qu’un contenu long dans la modale reste utilisable.
• Une modale imbriquée prend temporairement le contrôle sans corrompre l’état ni l’historique de focus de sa parente.

Cette liste constitue le composant. Le voile, le panneau arrondi et l’animation ne sont que sa présentation.

« Placer le focus sur le premier élément » paraît raisonnable jusqu’à ce que ce premier élément soit un bouton destructif ou un champ qui ouvre le clavier virtuel sur un téléphone.

Choisissez le focus initial selon le rôle et la forme de la modale :

• Pour un formulaire court, placez le focus sur le premier champ uniquement si la saisie immédiate est l’action suivante attendue.
• Pour une confirmation destructive, placez-le sur l’action la moins destructive, généralement Annuler.
• Pour une modale longue ou fortement structurée, placez-le sur un titre statique ou un élément d’introduction avec `tabIndex={-1}` afin que la lecture commence en haut sans ignorer de contenu.
• Pour un choix simple, privilégiez l’action sûre la plus probable.
• Lorsque l’ouverture vient d’une interaction tactile, vérifiez si le focus sur un champ masquerait un contexte important avec le clavier virtuel.

L’API du composant a donc besoin de plus qu’un booléen `open`. Elle doit permettre à la fonctionnalité qui utilise la modale de désigner la bonne cible initiale.

type ModalProps = {
  initialFocusRef?: RefObject<HTMLElement | null>;
  open: boolean;
  onDismiss: () => void;
  triggerRef?: RefObject<HTMLElement | null>;
};

useLayoutEffect(() => {
  if (!open) return;

  const frame = requestAnimationFrame(() => {
    const target = initialFocusRef?.current ?? dialogRef.current;
    target?.focus();
  });

  return () => cancelAnimationFrame(frame);
}, [initialFocusRef, open]);

Cette solution de repli place le focus sur le conteneur de la modale, qui possède `tabIndex={-1}`. Elle est plus sûre que de laisser le focus derrière le voile, mais elle ne remplace pas le choix de la bonne cible pour un vrai parcours.

La prise en charge d’Échap est simple avec une modale et facile à casser avec deux. Si chaque modale ouverte attache son propre écouteur au document, une seule frappe peut fermer toute la pile.

Chaque modale a besoin d’une identité, et un gestionnaire de couches partagé doit savoir quelle identité se trouve actuellement au sommet.

const modalStack: symbol[] = [];

export function pushModal(id: symbol) {
  modalStack.push(id);
}

export function removeModal(id: symbol) {
  const index = modalStack.lastIndexOf(id);
  if (index >= 0) modalStack.splice(index, 1);
}

export function isTopModal(id: symbol) {
  return modalStack.at(-1) === id;
}

Le gestionnaire clavier peut alors ignorer les événements qui appartiennent à une couche supérieure.

useEffect(() => {
  if (!open) return;

  function onKeyDown(event: KeyboardEvent) {
    const dialog = dialogRef.current;
    if (!dialog || !isTopModal(layerId.current)) return;

    if (event.key === "Escape") {
      event.preventDefault();
      event.stopPropagation();
      onDismiss();
      return;
    }

    keepTabInside(event, dialog);
  }

  document.addEventListener("keydown", onKeyDown, true);
  return () => document.removeEventListener("keydown", onKeyDown, true);
}, [onDismiss, open]);

Échap n’est qu’une sortie parmi d’autres. Chaque modale doit aussi contenir un contrôle visible pour fermer, annuler ou terminer. Une personne qui utilise un lecteur d’écran tactile ne peut pas dépendre d’une touche Échap physique.

Certains parcours doivent protéger un travail non enregistré. Ne désactivez pas silencieusement Échap en laissant l’utilisateur piégé. Laissez Échap demander la fermeture, puis présentez un chemin de confirmation compréhensible avec une action explicite pour rester ou partir.

Les portails React permettent à une modale d’échapper aux ancêtres dotés de `overflow: hidden`, de transformations et de contextes d’empilement locaux. La modale peut être rendue sous un conteneur stable proche du body du document tout en restant un enfant du même arbre React.

if (!open) return null;

return createPortal(
  <div className="modal-layer" role="presentation">
    <div className="modal-backdrop" />
    <div
      aria-labelledby={titleId}
      aria-modal="true"
      ref={dialogRef}
      role="dialog"
      tabIndex={-1}
    >
      {children}
    </div>
  </div>,
  document.body,
);

La position physique dans le DOM change, mais pas la relation React. Le contexte continue de fonctionner, et les événements issus du portail remontent toujours dans l’arbre React. Un clic dans la modale peut donc atteindre un gestionnaire React ancêtre même lorsque les nœuds DOM sont éloignés. La fermeture par clic sur le voile et les gestionnaires de clic parents nécessitent des frontières d’événements délibérées.

Un portail ne rend pas non plus l’arrière-plan inerte. Pour une modale ARIA personnalisée, le gestionnaire doit désactiver tout le contenu situé hors de la couche active tout en préservant les états `inert` ou `aria-hidden` préexistants. Cette comptabilité devient plus difficile quand plusieurs racines React, overlays tiers ou modales imbriquées partagent la page.

Imaginez une modale de modification du profil qui en ouvre une deuxième pour confirmer l’abandon des changements. Tant que cette confirmation est ouverte :

• La confirmation est la seule modale active.
• Le focus est piégé dans la confirmation, pas dans la parente.
• Échap ferme uniquement la confirmation.
• La parente reste montée, mais n’est pas interactive.
• Le défilement de la page reste verrouillé après la fermeture de la confirmation.
• Le focus revient au contrôle de la parente qui a ouvert la confirmation.
• La fermeture ultérieure de la parente restaure le focus vers le déclencheur initial de la page.

Ce comportement exige une pile de portées de focus, d’identités de couche, de régions inertes et de verrous de défilement. Le z-index établit uniquement l’ordre de peinture. Deux composants de modale indépendants peuvent sembler correctement empilés tout en écoutant tous les deux Échap, en se disputant la restauration du focus et en croyant chacun posséder les styles du body.

Évitez les modales imbriquées lorsque l’interaction peut devenir un seul parcours plus clair. Une confirmation peut parfois remplacer le contenu de la modale parente, ou un avertissement en ligne peut conserver la décision dans son contexte. Lorsque l’imbrication exprime une vraie hiérarchie, utilisez un seul système d’overlays qui coordonne toutes les couches.

Construire la version pédagogique est utile, car elle révèle le contrat. Livrer cette version comme infrastructure partagée constitue une autre décision.

Une bibliothèque de composants accessibles et établie est généralement plus sûre lorsque l’application présente l’une des conditions suivantes :

• Plusieurs modales ou plusieurs équipes consomment la primitive.
• Des modales imbriquées, des menus qui ouvrent des modales, des popovers dans des modales ou d’autres combinaisons d’overlays existent.
• Le rendu serveur, l’hydratation, les animations de sortie ou les portails vers des conteneurs personnalisés font partie du système.
• Des formulaires complexes comportent des champs dynamiques, de la validation, des états asynchrones ou des actions destructives.
• Safari mobile, les lecteurs d’écran tactiles, les mises en page zoomées ou les claviers virtuels font partie de la matrice de support.
• Un design system doit assurer un comportement modal cohérent dans plusieurs produits.
• Aucune capacité dédiée ne peut maintenir durablement le focus, l’inertie, le défilement et les cas limites des navigateurs.

Des bibliothèques comme React Aria Components, Radix Primitives, Base UI et Ariakit ont déjà investi dans les portées de focus, la fermeture, les portails et la coordination des overlays. Les critères de sélection importants ne sont ni les captures d’écran ni les styles par défaut. Examinez le contrat clavier, l’API de nom accessible, le comportement des overlays imbriqués, la stratégie de défilement, le support du rendu serveur, l’historique de maintenance, le poids du bundle et la facilité d’appliquer vos propres tokens de design sémantiques.

Une bibliothèque ne rend pas à elle seule la fonctionnalité finale accessible. L’équipe doit toujours fournir un titre utile, choisir les bons focus initial et restauré, conserver des contrôles de fermeture visibles, écrire des messages de validation compréhensibles et vérifier le contenu réel. La bibliothèque prend en charge l’infrastructure difficile ; l’équipe produit reste propriétaire du sens.