Construire des formulaires plus fluides avec HTMX dans Drupal 11

Article rédigé par Brahim - Lead Dev Drupal 

Introduction

HTMX est une bibliothèque moderne qui permet de créer des interfaces web interactives directement en HTML en utilisant des attributs simples, sans écrire de JavaScript complexe.

Son principe fondamental est d'étendre le HTML au lieu de le remplacer. Plutôt que d'écrire des dizaines de lignes de JavaScript pour effectuer des requêtes AJAX, mettre à jour le DOM et gérer les erreurs, HTMX permet de déclarer le comportement souhaité de manière déclarative :

<button hx-post="/mon-url" hx-target="#ma-div">

    Cliquez-moi !

</button>

Ce bouton enverra une requête POST à /mon-url et insérera la réponse directement dans l'élément ayant l'ID #ma-div

L’intégration de HTMX dans Drupal 11

Depuis mi-2025, Drupal a intégré dans son subsystem AJAX des éléments de support pour HTMX.

Cette évolution signifie que :

• Le module ou composant AJAX classique peut être complété ou remplacé par des attributs HTMX
• Ce support natif permet d'utiliser directement HTMX dans le core, améliorant ainsi l'interopérabilité et la maintenance
• Les mises à jour deviennent plus fiables grâce à l'intégration officielle

Une proposition vise à remplacer progressivement l'ancienne API AJAX (souvent couplée à jQuery) par une approche plus déclarative via HTMX.

Des tickets sont également en cours pour supporter dynamiquement les formulaires (form build ID, etc.), afin que les changements côté serveur soient correctement pris en compte lors des mises à jour partielles de formulaires avec HTMX.

Pour plus d'informations, consultez l'issue d'Intégration de HTMLX dans l'écosystème AJAX de Drupal.

HTMX dans Drupal 11.3 : L'approche native

Drupal 11.3 introduit une classe Htmx dédiée dans le namespace Drupal\Core\Htmx, offrant une intégration PHP fluide pour configurer les attributs HTMX.

À noter : La sortie de la version 11.3 est prévue pour la semaine du 8 décembre 2025, mais il est possible d'installer la version 11.3-dev pour tester ces fonctionnalités dès maintenant.

Exemple avec Drupal 11.3

<?php



namespace Drupal\exemple_htmx\Form;



use Drupal\Core\Form\FormBase;

use Drupal\Core\Form\FormStateInterface;

use Drupal\Core\Htmx\Htmx;

use Drupal\Core\Url;



class HtmxForm extends FormBase {

  public function getFormId() {

   return 'exemple_htmx_form';

 }



 public function buildForm(array $form, FormStateInterface $form_state) {

  

   $form['email'] = [

     '#type' => 'email',

     '#title' => "Votre email",

     '#required' => TRUE,

   ];



   $url = Url::fromRoute('exemple_htmx.request');

  

   // Application des attributs HTMX avec classe Htmx

   (new Htmx())

     ->post($url)              // POST sur la route 

     ->target('#htmx-result')  // Cible le div de résultat

     ->swap('outerHTML')       // Remplace complètement la cible

     ->applyTo($form['email']); // Ajoute les data-attributes sur le champ 'email'



   $form['#prefix'] = '<div id="htmx-result">';

   $form['#suffix'] = '</div>';



   return $form;

 }



 public function submitForm(array &$form, FormStateInterface $form_state) {

   // Non utilisé, tout passe par la route AJAX/HTMX

 }

}

Pour les versions antérieures de Drupal 11

Si vous utilisez une version de Drupal 11 antérieure à la 11.3, vous devrez inclure manuellement la bibliothèque HTMX.

Exemple pour versions antérieures

<?php



namespace Drupal\exemple_htmx\Form;



use Drupal\Core\Form\FormBase;

use Drupal\Core\Form\FormStateInterface;



class HtmxForm extends FormBase {

  public function getFormId() {

   return 'exemple_htmx_form';

 }



 public function buildForm(array $form, FormStateInterface $form_state) {

   // Inclusion manuelle de la bibliothèque HTMX

   $form['#attached']['library'][] = 'exemple_htmx/htmx';



   $form['email'] = [

     '#type' => 'email',

     '#title' => "Votre email",

     '#required' => TRUE,

     '#attributes' => [

       'hx-post' => '/exemple-htmx-request',

       'hx-target' => '#htmx-result',

       'hx-swap' => 'outerHTML',

     ],

   ];



   $form['#prefix'] = '<div id="htmx-result">';

   $form['#suffix'] = '</div>';



   return $form;

 }



 public function submitForm(array &$form, FormStateInterface $form_state) {

   // Non utilisé, tout passe par la route AJAX/HTMX

 }

}

Fichier de bibliothèque (exemple_htmx.libraries.yml)

htmx:
 version: 1.x
 js:
   https://unpkg.com/htmx.org@1.9.10: { type: external }

Contrôleur pour les deux cas: 

<?php


namespace Drupal\exemple_htmx\Controller;


use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;


class HtmxController {
 public function request(Request $request) {
   $email = $request->get('email', '');
   $output = "<div id='htmx-result'>Merci pour votre inscription : <strong>" . htmlspecialchars($email) . "</strong></div>";
   return new Response($output);
 }
}


exemple_htmx.form:
 path: '/exemple-htmx-form'
 defaults:
   _form: '\Drupal\exemple_htmx\Form\HtmxForm'
   _title: 'Formulaire HTMX'
 requirements:
   _permission: 'access content'


exemple_htmx.request:
 path: '/exemple-htmx-request'
 defaults:
   _controller: '\Drupal\exemple_htmx\Controller\HtmxController::request'
 requirements:
   _permission: 'access content'

Conclusion

Le duo Drupal 11 et HTMX est extrêmement puissant. Il permet aux développeurs back-end et aux intégrateurs familiarisés avec le rendu côté serveur de Drupal de créer des expériences front-end modernes et interactives sans avoir à adopter un framework JavaScript lourd.

HTMX respecte la philosophie de Drupal : il améliore le HTML sans s'y substituer. Cette approche vous permet de délivrer une expérience utilisateur exceptionnelle sur vos formulaires, et bien au-delà, tout en gardant votre codebase simple, maintenable et accessible.

Contactez un expert pour échanger sur votre projet
> Je souhaite en savoir plus sur Drupal