AJAX and HTMX

This content was generated with the assistance of AI and should be verified against the official Drupal documentation before being relied on in production.

This sub-section’s Drupal bibliography lists the reference material consulted while preparing these pages.

Most pages in Drupal are rendered once on the server and sent whole. Two subsystems let a page change after it has loaded without a full reload. The Ajax framework (the Ajax API) is Drupal’s historical mechanism: the browser sends a request through the Drupal.ajax JavaScript object, the server answers with a list of commands in JSON, and the commands change the page. HTMX is the newer mechanism, part of the Ajax subsystem of core since Drupal 11.3: elements carry declarative data-hx- attributes, the server answers with plain HTML, and the htmx library swaps that HTML into the page. This page explains both, shows the same interactions built with each on the Meridian Museum site, and ends with guidance on choosing between them.

This page was checked against the official documentation, the Drupal 11.x API reference and the relevant change records on 2026-10-30. It is written against Drupal 11.4.x, Drush 13 or 14 and PHP 8.3 or later (see Requirements and hosting for the baseline). The examples belong to the fictitious Meridian Museum site from the sub-section index and extend the meridian_collection module with a quick-view dialog, a "show on display" toggle that returns several commands, a custom Ajax command, and a "load more" list built with HTMX. Drupal 10 reaches end of life on 2026-12-09, so new sites should start on Drupal 11. Drupal 12.0.0 is planned for the week of 2026-12-07 and is not yet released; the Drupal 12 remarks describe changes recorded in change records for the 12.0.0 betas and should be re-checked at the final release.

Who uses Ajax and HTMX, and why

The module developer adds interactions to routes, forms and blocks: dialogs, partial updates, inline toggles and "load more" lists.
The site builder meets them without writing code: the Media Library dialog, the Views live preview, the Layout Builder off-canvas tray, dependent form fields and exposed filters that update a Views result in place all run on the Ajax framework.
The themer needs to know that markup replaced by Ajax or HTMX must still carry behaviors (see Libraries and assets) and that classes and wrapper ids are part of the contract.
The administrator needs to know that proxies, CDNs and web application firewalls must let the HTMX request headers through, and that dynamic requests are visible in the logs as ordinary GET and POST requests with a query string.
The security reviewer checks that every endpoint behind a dynamic interaction has an access check, that state-changing routes use CSRF protection, and that swapped HTML is rendered through Drupal’s escaping.

Using the framework is not optional for dynamic behaviour in Drupal. Hand-written fetch() calls that inject HTML skip the asset loading, behavior attachment (Drupal.attachBehaviors), cache metadata, form token handling and access checks that the Ajax subsystem provides, and are the usual cause of "works on the front page, breaks behind the cache" reports.

Version history

Drupal 7 introduced the Ajax framework with command functions. Drupal 8.0 made the response an AjaxResponse object and turned the commands into classes of the Drupal\Core\Ajax namespace.
Drupal 8.7.0 added MessageCommand, which displays messages through the Drupal.Message() object.
Drupal 10.0 removed the core/jquery.form library; the Ajax documentation notes that form callbacks that return an AjaxResponse do not need it.
Drupal 10.1 and later let controllers use constructor injection and autowiring (see Services and dependency injection); Ajax commands themselves did not change.
Drupal 11.2 added the htmx library as a core dependency.
Drupal 11.3 made HTMX a supported part of the Ajax subsystem: the \Drupal\Core\Htmx\Htmx class, the core/drupal.htmx library, HtmxRequestInfoTrait (also added to FormBase), the drupal_htmx wrapper format and the _htmx_route route option, and FormBuilder awareness of HTMX requests. Proxies and CDNs must pass the HTMX headers from this version on.
Drupal 11.5 (the release that follows 11.4) deprecates getHtmxPrompt() and getHtmxTrigger() of HtmxRequestInfoTrait, for removal in Drupal 12.0.0.
Drupal 12 moves core to htmx 4, a rewrite with breaking changes: fetch() replaces XMLHttpRequest, error responses are swapped, event names and several attributes and headers change, and some Htmx methods are renamed or removed. FormBuilderInterface::HTMX_REQUEST is deprecated for removal in Drupal 13. See Drupal 12 and htmx 4.

Older books describe an earlier state. Drupal 10 Development Cookbook (2023) teaches the Form API and #ajax callbacks well as a learning sequence, but it targets Drupal 10.0 on PHP 8.1: it predates HTMX in core, its examples reach services through \Drupal:: calls inside classes (the current pattern is constructor injection, with the static calls kept for procedural code), and its hooks are .module functions, where Drupal 11.1 and later use #[Hook] methods (see Hooks and OOP hooks). Drupal 10 Masterclass (2023) does not cover HTMX, and Modernizing Drupal 10 Theme Development (2023) predates the htmx library in core, so none of the three books mentions Htmx, core/drupal.htmx or the Ajax API to HTMX documentation. Where the books and the current documentation disagree, the documentation described here applies.

How the Ajax framework works

The framework has a client part and a server part.

The client part is core/misc/ajax.js, in the core/drupal.ajax library. A Drupal.ajax object represents one possible request: its URL, the element that triggers it, the event, how to submit data and how to show progress. It sends the request with an extra query parameter, _wrapper_format=drupal_ajax, and runs each command in the JSON array of the response.
The server part is the AjaxResponse class (\Drupal\Core\Ajax\AjaxResponse), a response that holds a list of command objects. Each command implements CommandInterface::render() and returns an array that becomes one JSON entry with a command key. The matching JavaScript function lives in Drupal.AjaxCommands.prototype.
The drupal_ajax wrapper format tells the main-content view subscriber to render the route’s result with the Ajax renderer. A controller that returns a render array is wrapped into an insert command (or a dialog command for the dialog formats); a controller that returns an AjaxResponse is used as it is.
Libraries and settings that the new content needs are added automatically: the Ajax attachments processor turns the attachments of the response (libraries, drupalSettings) into commands such as add_css, add_js and settings that run before the content commands.

sequenceDiagram participant V as Visitor participant J as Drupal.ajax (browser) participant R as Route and controller participant P as Ajax renderer V->>J: click a use-ajax link or change an element with Ajax settings J->>R: GET or POST ...?_wrapper_format=drupal_ajax R->>R: access checks, then build content or an AjaxResponse R->>P: render array or AjaxResponse P-->>J: JSON list of commands plus attachments J->>J: run commands (insert, remove, openDialog, message, ...) J->>J: Drupal.attachBehaviors on new content

Four ways to start a request

Trigger How it works

Trigger	How it works
A link with the `use-ajax` class	The framework turns the link into a `Drupal.ajax` object. `data-dialog-type="modal"` (or `dialog`) opens the response in a dialog, `data-dialog-options` passes jQuery UI dialog options as JSON, and `data-dialog-renderer="off_canvas"` selects the off-canvas tray. Optional attributes are `data-ajax-wrapper`, `data-ajax-progress`, `data-ajax-focus` and `data-ajax-http-method` (`GET` responses can be cached).
A submit button with the `use-ajax-submit` class	The form is posted to its action through Ajax, and the route must return a response the JavaScript can process.
The `#ajax` property of a form element or a link render element	Builds the `Drupal.ajax` object from the render array. See Form API for the form keys (`callback`, `wrapper`, `method`, `event`, `progress`). A link element uses `dialogType` and `dialog` keys.
JavaScript	`Drupal.ajax({url: ...})` followed by `execute()` creates and sends a request from a behavior.

A link with the use-ajax class

The framework turns the link into a Drupal.ajax object. data-dialog-type="modal" (or dialog) opens the response in a dialog, data-dialog-options passes jQuery UI dialog options as JSON, and data-dialog-renderer="off_canvas" selects the off-canvas tray. Optional attributes are data-ajax-wrapper, data-ajax-progress, data-ajax-focus and data-ajax-http-method (GET responses can be cached).

A submit button with the use-ajax-submit class

The form is posted to its action through Ajax, and the route must return a response the JavaScript can process.

The #ajax property of a form element or a link render element

Builds the Drupal.ajax object from the render array. See Form API for the form keys (callback, wrapper, method, event, progress). A link element uses dialogType and dialog keys.

JavaScript

Drupal.ajax({url: ...}) followed by execute() creates and sends a request from a behavior.

Source: Basic Concepts

The /nojs/ segment that older routes put in their path is replaced by /ajax/ when the request is an Ajax request, which lets one route serve both the Ajax and the plain page version of an interaction. A route that must work without JavaScript returns a render array for the full page and receives the Ajax treatment only when _wrapper_format is present.

Dialogs from links

Dialogs are the most common use of the framework and need no PHP beyond a normal route. The library core/drupal.dialog.ajax has to be loaded on the page that holds the link; a module declares it as a dependency of its own library or attaches it to the render array.

On the Meridian site every card in the collection listing offers a quick view of the object in a modal dialog. The route returns an ordinary render array.

# modules/custom/meridian_collection/meridian_collection.routing.yml
meridian_collection.quick_view:
  path: '/collection/{collection_object}/quick-view'
  defaults:
    _controller: '\Drupal\meridian_collection\Controller\QuickViewController::view'
    _title: 'Quick view'
  requirements:
    _entity_access: 'collection_object.view'
    collection_object: '\d+'
  options:
    parameters:
      collection_object:
        type: 'entity:collection_object'

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Controller;

use Drupal\Core\Controller\ControllerBase;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Url;
use Drupal\Component\Serialization\Json;
use Drupal\meridian_collection\Entity\CollectionObject;

/**
 * Quick view of one museum object.
 */
final class QuickViewController extends ControllerBase {

  public function __construct(
    private readonly EntityTypeManagerInterface $entityTypes,
  ) {}

  /**
   * Returns the teaser of the object; the dialog is created by the link.
   *
   * @return array<string, mixed>
   *   A render array.
   */
  public function view(CollectionObject $collection_object): array {
    return $this->entityTypes
      ->getViewBuilder('collection_object')
      ->view($collection_object, 'teaser');
  }

  /**
   * Builds the link that opens the quick view in a modal dialog.
   *
   * @return array<string, mixed>
   *   A link render array.
   */
  public function link(CollectionObject $collection_object): array {
    return [
      '#type' => 'link',
      '#title' => $this->t('Quick view'),
      '#url' => Url::fromRoute('meridian_collection.quick_view', [
        'collection_object' => $collection_object->id(),
      ]),
      '#attributes' => [
        'class' => ['use-ajax', 'button'],
        'data-dialog-type' => 'modal',
        'data-dialog-options' => Json::encode(['width' => 700, 'title' => $collection_object->label()]),
      ],
      '#attached' => ['library' => ['core/drupal.dialog.ajax']],
    ];
  }

}

Source: Ajax Dialog Boxes

The link degrades gracefully: without JavaScript it simply navigates to the quick-view route. In a template the same markup is written with class="use-ajax", data-dialog-type="modal" and a data-dialog-options value whose double quotes are written as "; invalid JSON in that attribute is the commonest reason a dialog does not open. A link that returns a form shows the form’s action buttons at the bottom of the dialog (they must be in an actions element), and a cancel link needs the button and dialog-cancel classes to appear in the action area.

`AjaxResponse` and the core commands

When a route must change several unrelated parts of the page, it returns an AjaxResponse and adds commands with $response->addCommand(). Commands run in the order they were added. The core commands, all in the Drupal\Core\Ajax namespace, are:

Command Arguments Effect

Command	Arguments	Effect
`ReplaceCommand`	selector, content, optional settings	Replaces the matched elements with the content.
`HtmlCommand`	selector, content, optional settings	Replaces the inner HTML of the matched elements.
`AppendCommand`, `PrependCommand`	selector, content, optional settings	Adds content inside the matched elements, at the end or at the start.
`BeforeCommand`, `AfterCommand`	selector, content, optional settings	Adds content before or after the matched elements.
`InsertCommand`	selector, content, optional settings	Generic insert that uses the method of the triggering element’s `#ajax` property.
`RemoveCommand`	selector	Removes the matched elements.
`CssCommand`, `AddCssCommand`	selector and an array of properties; a `<style>` string	Sets inline CSS properties on elements, or adds a style sheet to the page.
`DataCommand`	selector, key, value	Stores a value with the jQuery data API.
`InvokeCommand`	selector, method, optional arguments	Calls any jQuery method on the matched elements.
`ChangedCommand`	selector, optional asterisk	Marks elements as changed.
`MessageCommand`	message, optional selector, options and "clear previous" flag	Adds a status message through the `Drupal.Message()` JavaScript object (since 8.7.0).
`AnnounceCommand`	text, optional priority	Sends a screen-reader announcement through `Drupal.announce()`.
`AlertCommand`	text	Shows a JavaScript alert box.
`RedirectCommand`	full URL	Loads another page in the browser.
`OpenModalDialogCommand`	title, content, optional dialog options and settings	Opens a modal dialog; needs `core/drupal.dialog.ajax`.
`OpenDialogCommand`	selector, title, content, optional options and settings	Opens a non-modal dialog on a given selector.
`OpenOffCanvasDialogCommand`	title, content, optional options, settings and position	Opens the off-canvas tray.
`CloseModalDialogCommand`, `CloseDialogCommand`	optional persist flag; selector and persist flag	Closes the visible modal dialog or a given dialog.
`SetDialogOptionCommand`, `SetDialogTitleCommand`	selector and an option name and value; selector and a title	Changes an option or the title of an open dialog.
`SettingsCommand`	settings, optional merge flag	Replaces or extends `drupalSettings`.
`UpdateBuildIdCommand`	old and new `form_build_id`	Updates the hidden build id of a form (used by form rebuilds).
`RestripeCommand`	selector	Resets the odd and even striping of table rows.

ReplaceCommand