JavaScript for Joomla

1. The Basics

1.1 What is JavaScript?

JavaScript is a programming language that runs inside the web browser, on the visitor's own computer or phone. This is the key difference from PHP: PHP runs on the server and builds the HTML, while JavaScript runs after that HTML has arrived, on the client side. The two never run in the same place at the same time.

When someone opens a Joomla page, the server sends finished HTML, CSS, and a set of JavaScript files. The browser draws the page, then runs the JavaScript. From that moment, JavaScript can change the page without asking the server again: it can show and hide elements, validate a form, or fetch a small piece of new data in the background.

1.2 Server Side Versus Client Side

It helps to keep the two halves of a Joomla request clearly apart:

That last row matters for security: anyone can read and change the JavaScript you send. So a check in JavaScript is a convenience for the user, never a real defence. The server must check everything again.

1.3 Where Joomla Uses JavaScript

You do not have to write a line of JavaScript to benefit from it. Joomla 6 already uses it across the whole interface:

• The administrator menu, tabs, and modal dialogs.
• The Media Manager, which uploads and previews without a page reload.
• The editor (TinyMCE or CodeMirror), which is a large JavaScript application.
• Form fields such as the tag picker, the calendar, and color pickers.
• Guided Tours, the Joomla Update progress bar, and the System Dashboard.

All of this ships with Joomla and is maintained by the project. Your job, when you add your own JavaScript, is to plug into the same system rather than fight it.

3. How the Browser Loads Joomla's JavaScript

3.1 Scripts at the Bottom, Loaded Once

When Joomla renders a page, it collects all the JavaScript that the page, its modules, and its plugins asked for, removes duplicates, sorts them by dependency, and writes the <script> tags into the HTML. You never add the same file twice; Joomla handles that for you.

3.2 defer, async, and module

Modern Joomla marks its scripts so they do not block the page from drawing. Three attributes control this:

Joomla's script renderer understands all of these. The point for you is that you should not paste a plain <script> at the top of a template; let Joomla add it with the right attributes so it does not slow the first paint.

3.3 ES Modules and the Import Map

Joomla 6 uses ES modules: modern JavaScript split into files that import from each other, the same standard your browser uses natively. To let one module find another by a short name instead of a long path, Joomla writes an import map into the page:

<script type="importmap">
{
  "imports": {
    "editor-api": "/media/system/js/editors/editor-api.min.js",
    "editor-decorator": "/media/system/js/editors/editor-decorator.min.js"
  }
}
</script>

An asset marked with "importmap": true in Joomla's asset list is added to this map automatically. For very old browsers, Joomla ships a small shim (es-module-shims) so the same code still works. You do not build the import map by hand; you mark an asset and Joomla generates it.

5. The Joomla JavaScript Object

Joomla ships a small core JavaScript file, media/system/js/core.js, that almost every back-end page loads. It defines a global Joomla object with helpers your own scripts can use. Knowing a handful of them saves a lot of work.

5.1 Joomla.getOptions: Read Data From PHP

Joomla.getOptions reads configuration that PHP placed in the page (see section 6). It is the clean way to pass a setting, an ID, or a URL from the server to your script:

// PHP put options under the key 'com_myextension'
const opts = Joomla.getOptions('com_myextension', {});
console.log(opts.apiUrl);

5.2 Joomla.request: Talk to the Server Safely

Joomla.request is a small wrapper around the browser's request handling that adds Joomla's security token automatically. It is the simplest way to call the server from your script:

Joomla.request({
  url: 'index.php?option=com_ajax&plugin=hello&format=json',
  method: 'GET',
  onSuccess: (response) => {
    const data = JSON.parse(response);
    console.log(data.data);
  },
});

You can also use the browser's own fetch directly; both are fine. For calls that read data, either works. For calls that change data, you must add the security token, which the next helper provides.

5.3 Joomla.Text: Translate in JavaScript

Strings you show from JavaScript should still be translatable. Joomla mirrors its language system into the browser. In PHP you mark a string for the front end with Text::script('MY_KEY'), and in JavaScript you read the translation back:

// In PHP, before the page renders:
// \Joomla\CMS\Language\Text::script('COM_MYEXTENSION_SAVED');

// In JavaScript:
alert(Joomla.Text._('COM_MYEXTENSION_SAVED'));

5.4 The Most Useful Helpers

To use these in your own script, declare core as a dependency (or call $wa->useScript('core')) so the Joomla object exists before your code runs.

5.5 Listening for Events

Most of your JavaScript reacts to something the user does: a click, a change, a key press. The modern way to react is addEventListener. Avoid the old habit of writing onclick straight into the HTML, because it mixes behaviour into your markup and a Content Security Policy (section 12) will block it.

// Good: behaviour lives in the script, not the HTML.
document.querySelector('#save')
  .addEventListener('click', (event) => {
    event.preventDefault();
    // do the work
  });

When you have many similar elements, such as every row in a long list, do not attach a listener to each one. Attach a single listener to the parent and check what was clicked. This pattern is called event delegation, and it stays fast even when the list grows or rows are added later:

document.querySelector('#list')
  .addEventListener('click', (event) => {
    const button = event.target.closest('.delete');
    if (button) {
      // handle the delete for this row
    }
  });

One listener on the parent does the work of hundreds on the children, and it keeps working for rows your script adds after the page has loaded.

7. Web Components: Joomla's Custom Elements

Instead of a heavy framework, Joomla builds reusable interface pieces as Web Components: custom HTML elements defined by the browser standard. You use them like ordinary tags, and the browser runs the JavaScript behind them.

7.1 What a Web Component Looks Like

Joomla ships several as custom elements in media/vendor/joomla-custom-elements/, such as the alert and the tab. In your HTML they read like normal tags:

<joomla-alert type="warning" dismiss="true">
  Please save your work before leaving.
</joomla-alert>

The browser sees <joomla-alert>, loads the matching JavaScript, and the element becomes a working, dismissible alert. There is no jQuery and no framework involved.

7.2 Why Joomla Chose This

Web Components are part of the browser itself, so they keep working as browsers update and they do not lock Joomla into one JavaScript framework that might fade away. They are self-contained, reusable across templates, and load only when the matching tag appears on the page. For you as a developer, it means a stable, standards-based set of building blocks rather than a moving target.

7.3 The Bundled Libraries

Beyond its own components, Joomla bundles a curated set of third-party JavaScript libraries in media/vendor/, loaded only when needed:

Because these are shared, two extensions that both need a date picker or a chart can use the same bundled copy instead of each shipping its own.

7.4 Bootstrap 5 Comes With Joomla

One bundled library deserves its own note: Joomla ships Bootstrap 5, and not just its CSS. The JavaScript behaviour is there too, split into named assets so you load only the piece you need:

So a modal, a dropdown, or an accordion needs no extra download and no other framework, only a single useScript call:

$wa->useScript('bootstrap.modal');

7.5 Adding Your Own Library

Joomla does not bundle every library. If you need Chart.js for a graph, SortableJS for drag-and-drop, or a small framework such as Alpine.js or Vue, add it the same way as any other asset: register it in your joomla.asset.json (or with registerAndUseScript) and let the Web Asset Manager load it. Do not paste a hard-coded <script src="/..."> into your template; register the library so Joomla handles its order, its version, and its duplicates like everything else.

9. Building and Compiling JavaScript

The JavaScript Joomla ships is not the same as the JavaScript its developers write. The source is modern and split into many files; the version sent to browsers is minified and bundled. Knowing this helps you understand what you see in media/.

9.1 Source Versus Built Files

Joomla's core JavaScript source lives in a build/ folder and is compiled into the media/ folder. You will see pairs of files:

core.js        the readable source (for debugging)
core.min.js    the minified version (smaller, for production)
core.min.js.gz pre-compressed for faster delivery

Joomla loads the .min.js version on a live site and can load the readable .js when Debug mode is on, so you can read the real code while troubleshooting.

9.2 The Build Tools

Compiling these files uses Node.js and npm, the standard JavaScript tooling, with a build script in the project. You only need this if you develop the core or an extension with its own build step. For a normal site, the built files are already in place and you never run a build.

9.3 You Rarely Need a Build for Custom Code

For your own small scripts, you do not need a build pipeline at all. Write a plain, modern .js file, register it with the Web Asset Manager, and Joomla serves it. Reach for a build step (bundling, transpiling) only when your code grows large enough to need it, not for a few lines of interactivity.

11. Performance: Keep JavaScript Fast

JavaScript is powerful, but every script the browser downloads, parses, and runs costs time. On a phone over a weak connection, heavy JavaScript is one of the biggest reasons a site feels slow.

11.1 Load Less, and Load It Late

• Use defer (the Web Asset Manager default) so scripts do not block the first paint.
• Only enable an asset on the pages that need it, not site-wide by habit.
• Watch for extensions that each load their own copy of jQuery or a chart library; share the bundled one instead.

11.2 Combine and Minify

Joomla can be helped here at two levels. The built core files are already minified. For the rest, a good caching or optimisation extension can combine several small scripts into one request and minify them. Fewer, smaller files mean fewer round trips and faster pages, especially on HTTP/1.1 hosts.

11.3 Debounce and Cache Requests

When your script calls the server as the user types (a live search, for example), do not send a request on every keystroke. Debounce the input: wait until the user pauses, then send one request. And cache results that rarely change, such as a list of countries, so you do not ask the server twice for the same answer.

11.4 Measure, Do Not Guess

Use the browser's developer tools (the Network and Performance tabs) to see which scripts load and how long they take. A tool such as Lighthouse points directly at render-blocking or oversized JavaScript. Optimise what the measurement shows, not what you assume.

13. SEO and Metadata

JavaScript and search ranking meet in two places: speed and content visibility. Both can help or hurt, depending on how you use scripts.

• Render-blocking scripts delay the first paint and hurt Core Web Vitals. Defer your JavaScript so the page draws before the scripts run.
• Heavy JavaScript raises the time before a page becomes usable. Smaller, fewer scripts give better scores.
• Content built only by JavaScript may not be seen reliably by every crawler. Important text should be in the HTML Joomla sends, with JavaScript enhancing it, not creating it.
• Progressive enhancement is the safe pattern: the page works without JavaScript, and scripts add convenience on top. Search engines and users with scripts blocked still see the core content.

In short, treat JavaScript as an enhancement layer for SEO. Let Joomla and PHP deliver the content and the structure; let JavaScript make it nicer, quickly and without blocking.

15. Best Practices

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

• Use the Web Asset Manager for every script and style; declare dependencies instead of guessing the order.
• Write plain, modern JavaScript; reach for jQuery or a framework only when you truly must.
• Pass data from PHP to JavaScript with addScriptOptions and read it with Joomla.getOptions.
• Use Joomla.Text::script and Joomla.Text._() so script messages stay translatable.
• Defer scripts, load them only where needed, and share bundled libraries to keep pages fast.
• Send and verify a CSRF token for anything that changes data; keep reads on GET.
• Never trust the client: validate and authorise every request again on the server.
• Guard against XSS: escape on output, prefer textContent, and consider a Content Security Policy.
• Never edit core files; add JavaScript through templates, overrides, plugins, or your own extension.
• Keep content in the HTML and let JavaScript enhance it, so SEO and no-script users are safe.

17. Summary

JavaScript is the half of Joomla that runs in the browser. PHP builds the page on the server; JavaScript makes it interactive once it arrives. Joomla 6 takes a modern, standards-based approach to it:

• Plain JavaScript: the core dropped MooTools and made jQuery optional; new code uses the browser's own features.
• The Web Asset Manager: the correct way to add scripts and styles, with named assets and declared dependencies, so nothing loads twice or in the wrong order.
• The Joomla object: helpers such as getOptions, request, and Text connect your script to Joomla's data, security token, and translations.
• Web Components and ES modules: reusable, standards-based building blocks instead of a heavy framework.
• Security and speed: never trust the client, escape output, send tokens for writes, and defer scripts so pages stay fast.

Most JavaScript problems on a Joomla site are not deep coding bugs. They are scripts added the wrong way, a library loaded several times, data echoed unsafely into a page, or a check trusted on the client that should have run on the server. Each one is quick to fix once you know how Joomla expects JavaScript to be loaded and secured.

If your site feels sluggish, throws "is not defined" errors, or you want to add interactivity such as live search or save-without-reload the right way, the cause and the cure usually sit in how the JavaScript is loaded and how it talks to the server. That is exactly the kind of front-end and Joomla integration work I help with, so a site stays fast, safe, and easy to maintain for years.