How to Upgrade Modals from Joomla 3 to Joomla 4

Modals has a single package that works on both Joomla 3 and Joomla 4. The correct files will be installed from the same package depending on which version of Joomla you're using.

We have separate Documentation pages for the J3 and J4 versions of Modals. You can switch to the desired J3/J4 documentation by using the button on the top right corner of this site.

This is the process to upgrade any of the Regular Labs Extensions:

  1. First, make sure that your Joomla 3 site is updated to the latest Joomla 3.10 release
  2. On Joomla 3.10, update all the installed Regular Labs Extensions to their latest version
  3. Upgrade your Joomla 3.10 site to Joomla 4
  4. Upgrade the PHP version on your server to PHP 8.1 or higher
  5. Reinstall the latest versions of all the Regular Labs extensions. This will upgrade the extensions to their Joomla 4 counterpart.

Differences with the Joomla 3 version

Modals for Joomla 4 has been completely rewritten. This means there are a lot of differences to the Joomla 3 version. It has some different features, different ways of doing things (syntax) and some features have been removed.


Modals for Joomla 4 now comes with themes. Read more about it here: Themes for Modals

Different CSS

The HTML output and DOM elements generated by Modals are different on Joomla 4 than they were on Joomla 3.

This means that all CSS has been changed too. Your custom CSS for Modals on Joomla 3 will not work on Joomla 4.
If you want to customize the look and feel on Joomla 4 too, you will need to rewrite your CSS.

No more jQuery

The javascript for Modals has been rewritten from the ground up, using vanilla (pure) javascript. It is no longer reliant on jQuery or other javascript libraries.

This should also mean that there should be less to no more conflicts with other extensions (like template frameworks that load a bunch of their own javascripts and libraries).

Different javascript API

As the javascript has been rewritten, the javascript API has changed too.

There is more information on how to close the modal via custom javascript calls here: Closing the Modal

IFrame mode for all urls

With the Joomla 3 version, internal urls would in most cases be opened inline. This however caused issues with many template frameworks and components.

The Joomla 4 version will open all urls in iframes. It is not possible to switch that behavior off.
If, however, you want to open content internal content inline, there are ways to do that.

You can use the {modalcontent} tags to open content inline (so not in an iframe). Just surround the content you want to open in the modal with the {modalcontent}...{/modalcontent} tags, and reference that in the {modal} tag.

If this is content you want to use in multiple places, you can consider using Snippets. Just place that {snippet} inside those inline content tags.

If you want to open an article (or parts of an article's content or data) inside the modal, you could consider using Articles Anywhere. Just place the necessary {article} tag inside those inline content tags.

Different way to position modals

In the Joomla 3 version of Modals you can position a modal by setting the pixel offset via top, bottom, left and right attributes. This is gone now.

In the Joomla 4 version you can set the position via named positions. See the section about Positioning for more details.

Different syntax for the data.txt

When showing images and galleries via Modals, you can use a data.txt file to set titles and descriptions for the images.

In Joomla 4, the syntax of how to set these has changed. Go to the Titles & Descriptions section to see the new syntax.

Other settings

A lot of the global settings have been changed. Quite a few pretty useless settings have been removed. Other settings have changed how they behave. And also some settings have been added.

Browse through the Configuration to see if there is anything you use that has been changed.

Bulk replacing syntax

If you need to change certain things in your {modal} tags to get things to work how you want, you can use DB Replacer to replace things in a few clicks.