AJAX in Joomla

1. The Basics

1.1 What is com_ajax?

The name "Ajax" stands for an old idea: a page asks the server for a small piece of data in the background, then updates itself without a full reload. com_ajax is the core component that makes this easy in Joomla.

It is unusual among Joomla components because it has almost no code of its own. It does not build a page, it has no menu items, and it has no views. Its only job is to take an incoming request, hand it to the right extension, and return whatever that extension produces.

Think of com_ajax as a switchboard operator: it does not answer your question itself, it just connects your call to the right extension and hands the answer back.

1.2 The Problem It Solves

Before com_ajax, every developer who wanted a small JSON response had to build a full component with a controller, a model, and a router, just to return one value. That is a lot of work for one number.

com_ajax removes that work. A plugin, a module, or a template can expose a single method, and com_ajax will call it. You write the logic, Joomla handles the request, the routing, and the response format.

Once you have it, a lot of common features become easy:

• Live search and search suggestions as the user types.
• Dependent fields - pick a country, and the list of states updates.
• Lazy loading - load heavy content only when it scrolls into view.
• Save without reload - a setting, a vote, a "snooze this notice" click.
• Dashboard widgets that each fetch their own data.

1.3 The URL Anatomy

Every call to com_ajax is just a URL with a few query parameters. Here is the shape of a typical request:

index.php?option=com_ajax&plugin=hello&group=ajax&format=json
          |               |            |           |
          |               |            |           └─ response format (required)
          |               |            └─ which plugin group to load
          |               └─ which target to call
          └─ always com_ajax

The same component is reachable from the front end (index.php) and from the back end (administrator/index.php). The back-end version simply includes the front-end file.

3. Plugins: the Most Common Target

For most projects, an Ajax plugin is the right tool. A plugin is not tied to a single module or template, so you can call it from anywhere on the site.

3.1 The onAjax<Name> Event

When you call index.php?option=com_ajax&plugin=hello&format=json, com_ajax does two things:

1. It imports every plugin in the requested group (default ajax; override it with &group=system and similar).
2. It fires the event onAjaxHello - the word after plugin=, capitalised, with onAjax in front.

plugin=hello   ──→   event onAjaxHello
plugin=stats   ──→   event onAjaxStats
plugin=cart    ──→   event onAjaxCart

Any enabled plugin that subscribes to that event will run. This is the same publish-and-subscribe model that drives all Joomla plugins.

3.2 The AjaxEvent Object

Since Joomla 5, com_ajax passes a typed event object, AjaxEvent, to your method. The event always carries the application as its subject, and it collects whatever you return in a result argument.

// Inside com_ajax, simplified:
$eventName = 'onAjax' . ucfirst($input->get('plugin', ''));
$results   = $dispatcher
    ->dispatch($eventName, new AjaxEvent($eventName, ['subject' => $app]))
    ->getArgument('result', []);

Your plugin reads the request, does its work, and adds its answer to the event's result. com_ajax then formats that result and sends it back.

3.3 A Complete Example Plugin

Here is a minimal, modern Ajax plugin. It lives in plugins/ajax/hello/ and answers with a greeting:

use Joomla\CMS\Event\Plugin\AjaxEvent;
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\Event\SubscriberInterface;

final class Hello extends CMSPlugin implements SubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return ['onAjaxHello' => 'onAjaxHello'];
    }

    public function onAjaxHello(AjaxEvent $event): void
    {
        $app  = $event->getApplication();
        $name = $app->getInput()->getString('name', 'world');

        // Add the answer to the event result:
        $event->addResult(['greeting' => 'Hello, ' . $name . '!']);
    }
}

Enable the plugin, then visit:

index.php?option=com_ajax&plugin=hello&format=json&name=JUG

You get back a JSON envelope whose data contains your greeting.

3.4 Returning the Result

The AjaxEvent object gives you three clear ways to set the answer:

Use addResult() when more than one plugin may answer the same event, and updateEventResult() when your plugin owns the whole response.

5. Calling com_ajax from the Browser

So far we have looked at the server side. Now let us call the endpoint from JavaScript, which is where com_ajax is normally used.

5.1 A Simple Fetch Call

The modern way is the browser's built-in fetch. Core Joomla plugins use exactly this pattern:

const url = 'index.php?option=com_ajax&plugin=hello&format=json&name=JUG';

fetch(url, { method: 'GET' })
  .then((response) => response.json())
  .then((data) => {
    console.log(data.data); // your result lives in .data
  });

Joomla also ships a small helper, Joomla.request(), which adds the security token automatically. You can read its options with Joomla.getOptions('system.paths') to build a correct root URL.

5.2 The CSRF Token and POST Requests

A read-only GET request is fine for fetching data. But any call that changes something - saving, deleting, sending - must protect against cross-site request forgery (CSRF). Joomla expects a one-time token.

const token = Joomla.getOptions('csrf.token', '');

fetch('index.php?option=com_ajax&plugin=cart&format=json', {
  method: 'POST',
  headers: { 'X-CSRF-Token': token },
  body: new URLSearchParams({ productId: 42 }),
});

On the server, check the token with Session::checkToken() before you act on a write request. Never trust a GET request to change data.

5.3 Passing Parameters

Anything you add to the URL or the POST body is available through the application input, exactly like in any Joomla code:

$input = $event->getApplication()->getInput();
$id    = $input->getInt('id');          // safe integer
$name  = $input->getString('name');     // filtered string
$html  = $input->get('body', '', 'raw'); // raw, use with care

Always use the typed getters (getInt, getString, getWord). They filter the input for you and prevent many injection problems.

5.4 Check Permissions on the Server

Filtering input is not the same as checking who is allowed to do something. A front-end endpoint can be called by anyone, so your method must verify the user's rights itself, with Joomla's ACL:

$user = $event->getApplication()->getIdentity();

if (!$user->authorise('core.edit', 'com_inventory')) {
    throw new \RuntimeException('Not allowed', 403);
}

Never rely on the URL or a hidden form field to decide access. The rule is simple: filter every input, and authorise every action.

7. Security and the Back End

An open endpoint that returns data is a security surface. com_ajax has several built-in protections, and Joomla 6 adds an important new one for the back end.

7.1 Site Versus Administrator Endpoints

There are two entry points:

• index.php?option=com_ajax&... - the public front end.
• administrator/index.php?option=com_ajax&... - the back end. The admin file just includes the site file, so the logic is shared.

On the front end, anyone can call an endpoint, so your plugin must check permissions itself. On the back end, com_ajax normally requires a logged-in administrator.

7.2 The AllowUnauthorizedAdministratorAccess Attribute

Sometimes a back-end Ajax call must run before the admin has logged in - for example, a passwordless login challenge or a captcha check on the login screen. Joomla 6 (introduced in 5.4.4) handles this with a PHP attribute.

If a guest calls com_ajax in the back end, com_ajax inspects the target method. Unless that method is marked with the attribute, it refuses the call with a "not authorised" error.

use Joomla\CMS\Plugin\Attribute\AllowUnauthorizedAdministratorAccess;

#[AllowUnauthorizedAdministratorAccess]
public function onAjaxMyLoginStep(AjaxEvent $event): void
{
    // This may run for a guest in the administrator area,
    // because the attribute explicitly allows it.
}

This is a deliberate "deny by default" design: a back-end endpoint is closed to guests unless you opt in, one method at a time.

7.3 Caching and Indexing

com_ajax protects itself in two more ways on every request:

• It calls allowCache(false), so responses are never served from the page cache. Each call runs fresh.
• It sets the header X-Robots-Tag: noindex, nofollow, so search engines do not index the endpoint URLs.

9. Performance and Caching

com_ajax is convenient, but it is not free. Knowing what each call really costs helps you keep an interactive page fast.

9.1 Every Call Is a Full Joomla Boot

An Ajax request is not a lightweight microservice call. Each one boots the entire Joomla stack before your method runs:

Request
   │
   v
Framework + autoloader
   │
   v
Application + DI container
   │
   v
Session + user
   │
   v
Language files
   │
   v
Plugins imported
   │
   v
Your Ajax handler
   │
   v
JsonResponse

The work to answer "what is the stock of item 42?" includes all of that setup. So treat Ajax calls as real requests: make fewer of them, and return more per call instead of firing many tiny ones.

9.2 Keep the Handler Thin

An Ajax method should do three things: read and check the input, call your logic, and return the result. Keep the real work in a separate service or helper class, not in the handler itself.

public function onAjaxInventory(AjaxEvent $event): void
{
    $app = $event->getApplication();
    $id  = $app->getInput()->getInt('id');

    // The handler stays thin; the service does the work.
    $event->addResult($this->inventory->getStock($id));
}

A thin handler is easier to test, easier to read, and easier to reuse from a normal controller later.

9.3 Cache Expensive Results

com_ajax disables the page cache for its own responses, but nothing stops you from caching the data your handler produces. Values that change rarely are ideal:

• Category trees and menus.
• Country, region, and currency lists.
• Product catalogues and search suggestions.

Use Joomla's cache for these lookups so a popular endpoint does not hit the database on every keystroke. On the browser side, debounce rapid events such as typing, so you send one request after a short pause instead of one per character.

11. SEO and Metadata

com_ajax is not a content URL, and you should never let it behave like one.

• com_ajax already sends X-Robots-Tag: noindex, nofollow, so its URLs stay out of search results. Do not undo this.
• Do not create menu items that point at com_ajax. It has no human-readable view, so it would produce a broken page.
• Keep Ajax responses small and data-only. They are for scripts, not for crawlers.
• If an Ajax response builds part of a page, make sure the page also works without JavaScript, so search engines still see the core content.

In short: com_ajax serves data to the browser, while your normal pages serve content to people and search engines. Keep the two jobs separate.

13. Best Practices

If you only remember a few things from this article, remember these:

• Always send a format. com_ajax will not guess one for you.
• Prefer an Ajax plugin for reusable logic; use a module or template helper only when the logic clearly belongs there.
• Use format=json for data and read it from the data field; use format=raw for HTML fragments.
• Send and verify a CSRF token for anything that changes data; keep GET requests read-only.
• Filter all input with the typed getters, and authorise every action with Joomla's ACL.
• Keep the handler thin: read input, call a service, return the result. Put real logic in its own class.
• Remember each call is a full Joomla boot. Make fewer, larger calls, and cache results that change rarely.
• Throw exceptions to report errors; never use die() or exit() in a handler.
• In the back end, keep endpoints closed to guests; open a method to guests only with the attribute, when truly needed.
• Use com_ajax for in-page interactions, and the Web Services API for external integrations.

15. Summary

com_ajax is one of the smallest components in Joomla, yet it unlocks a large amount of interactivity. Instead of building a full component just to return one value, you expose a single method and let Joomla handle the request, the routing, and the response.

The key ideas are short:

• One endpoint, option=com_ajax, routes to a plugin, a module, or a template.
• Plugins answer the event onAjax<Name> through a typed AjaxEvent; modules and templates answer with a <method>Ajax() helper.
• A format is always required, and JSON responses follow a fixed envelope.
• Security comes first: filter input, use the CSRF token for writes, and keep back-end endpoints closed to guests unless you opt in.

If you are adding live search, a save-without-reload button, or a small data feed to your site, com_ajax is usually the cleanest way to do it. And if you need help designing a secure Ajax endpoint, tracking down why one returns nothing, or deciding between com_ajax and the Web Services API, that is exactly the kind of advanced Joomla work I do every day.