Drupal AJAX

As of Drupal 11.3, HTMX is available in core and is the recommended approach for new projects. This guide covers the legacy AJAX framework, which remains essential for existing codebases and contributed module patterns.

I need to...	Guide	Summary
Understand the AJAX system architecture	Core Concepts	Use Drupal AJAX when maintaining existing codebases, working with contributed modules, or needing backward compatibility. Use HTMX (available in Drupal 11.3+) for new projects — it reduces JavaScript size by up to 71%.
Add AJAX to a form element	Form Element AJAX Configuration	Use the #ajax property on any form element when you need server-driven content updates triggered by user interaction without a full page reload.
Create dependent fields (category/subcategory)	Dependent Field Patterns	Use dependent fields when form options must change based on the value of another field (category/subcategory, country/state, product type/options).
Build a multi-step wizard form	Multi-Step Form Workflows	Use multi-step AJAX forms for wizard-style workflows where users navigate sequential steps without page reloads. Use standard forms for simple one-page submissions.
Validate fields as user types	Live Field Validation	Use live validation when user experience benefits from immediate field-level feedback (email availability checks, username format, real-time constraints). Avoid for simple required-field checks.
Update, append, or remove DOM content	Content Manipulation Commands	Use these commands when you need to update DOM content from AJAX callbacks. Choose the command that matches the specific DOM operation needed.
Add CSS classes or invoke jQuery methods	CSS Styling Commands	Use CSS styling commands for dynamic visual changes triggered by AJAX responses. Prefer adding classes over inline styles.
Open or close modal dialogs	Dialog Commands	Use OpenModalDialogCommand when you need to block page interaction. Use OpenDialogCommand for non-blocking side panels.
Show messages or screen reader alerts	Feedback Commands	Use MessageCommand for all user-facing messages. Use AnnounceCommand to notify screen readers of content changes.
Create a custom AJAX command	Custom AJAX Commands	Create custom AJAX commands when core commands don't meet your needs: custom animations, third-party library integration, or complex DOM manipulation requiring JavaScript logic.
Build a custom AJAX route (non-Form API)	Custom Route Implementation	Use custom AJAX routes when you need AJAX endpoints outside Form API: autocomplete, search, content loading, or API-style endpoints. Always implement the nojs fallback for JavaScript-disabled environments.
Handle file uploads via AJAX	File Upload Patterns	Use #type => 'managed_file' with AJAX for file uploads that need immediate preview or feedback (avatars, attachments, media galleries). Always configure upload validators.
Implement autocomplete suggestions	Autocomplete Implementation	Use #autocomplete_route_name for dynamic suggestions as users type. Use core's system.entity_autocomplete for existing entity types.
Restrict access to AJAX callbacks	Access Control Patterns	Every AJAX callback and route is an HTTP endpoint and requires access control. AJAX callbacks are not protected by the UI alone — attackers can call them directly.
Protect AJAX endpoints from CSRF	CSRF Protection	Drupal's Form API handles CSRF automatically. For custom AJAX routes outside Form API, add _csrf_token: 'TRUE' and verify request type.
Optimize slow AJAX requests	Performance Optimization	Apply these patterns when AJAX requests are slow, causing excessive database queries, large DOM updates, or timeouts on large operations.
Cache AJAX responses	Response Caching	Use CacheableAjaxResponse for AJAX responses containing cacheable data: public content, configuration results, or expensive calculations that don't vary per user. Do not cache user-specific data without proper cache contexts.
Make AJAX meet WCAG 2.1 AA	WCAG Compliance Patterns	Apply these patterns to every AJAX implementation. Accessibility is not optional — WCAG 2.1 Level AA is the standard for Drupal sites.
Announce updates to screen readers	Screen Reader Support	Every AJAX content update must be announced to screen reader users. Silence after a dynamic update is a WCAG failure.
Debug failing AJAX requests	Debugging Techniques	Use these techniques when AJAX requests fail, return unexpected results, or produce errors. Start with the browser DevTools Network tab before adding server-side logging.
Write automated AJAX tests	Testing AJAX	Use WebDriverTestBase (FunctionalJavascript namespace) for AJAX tests — it drives a real browser. Use BrowserTestBase only for non-JavaScript tests.
Integrate React or Vue with Drupal	Frontend Framework Integration	Use JSON endpoints with React/Vue for fully decoupled sites. Use Drupal AJAX for simple enhancements.
Apply security best practices	Best Practices: Security	Apply every item in this guide to every AJAX implementation. AJAX callbacks and routes are HTTP endpoints — they require the same security rigor as any web API.
Apply performance best practices	Best Practices: Performance	Apply these standards to every AJAX implementation. Slow AJAX destroys UX.
Follow Drupal development standards	Best Practices: Development Standards	Apply these standards to all AJAX code. They prevent the most common sources of bugs, broken tests, and maintenance pain.
Meet accessibility requirements	Best Practices: Accessibility	Every AJAX implementation must meet WCAG 2.1 Level AA. This is not optional — it's a legal and ethical requirement.