Replacing Thickbox

A theme of development since version 2.0 of ClassicPress was released has been the replacement of obsolete JavaScript libraries. In version 2.1, for example, the thickbox library was removed from core. The point of thickbox is to enable the use of modals, but there is a much better alternative available these days.

The dialog element

The native HTML5 dialog element provides significantly better accessibility. Yet it uses much less JavaScript and so makes pages load faster and with less risk of breakage. It also works on every browser that ClassicPress supports.

An example of how we are now using the dialog element may be found in the ~/wp-admin/js/plugin-install.js file. We encourage everyone currently using thickbox to follow our example. The point of this post is to provide some guidance on how to do so.

How to convert your code

The first thing to do is to identify the element that currently acts as the container for the modal. This is typically a div. Whatever it is, this needs to be changed to dialog. So, if writing straight HTML, this would involve writing <dialog></dialog> while, in JavaScript (as in the ~/wp-admin/js/plugin-install.js file), it would mean writing something like var dialog = document.createElement( 'dialog' ).

Next, the dialog should be appended to the bottom of the page on which it will be used, whether by just adding it to near the end of the page’s HTML directly or by writing something like document.body.append( dialog ) in JavaScript. No hidden attribute should be added, nor should any CSS be used to hide the modal, because the dialog element is hidden by default.

How to use the new modal

The contents of the modal can now be added to the dialog modal in just the same way as you currently do it.

To open the modal, simply call dialog.showModal() in your JavaScript. To close it, call dialog.close() or just hit the Escape button on your keyboard. It’s that simple!

If you need to detect whether the modal is open or not, that’s easy too. If the modal is open, an open property is added to the dialog element; it is removed when the modal is closed. So you can simply do this: if ( dialog.open ) { ...

Additional options

You can get a bit more fancy by adding the autofocus attribute to any focusable element within the modal on which you want focus to be placed when the modal is first opened. This is typically a button that, if clicked, will also close the modal. Remember, though, that if you have such a button, you will need to add a bit of custom JavaScript to get it working. But it’s not hard. Something like this will do the trick:

dialog.querySelector( '#dialog-close-button' ).addEventListener( 'click', function() {
    dialog.close();
} );

If you want to darken the background color of the environment surrounding the dialog, then a little CSS is all you need, like this:

dialog::backdrop {
    background: #000;
    opacity: 0.7;
}

Time to update

In version 2.2 of ClassicPress, thickbox has now been deprecated. This means that plugins and themes that continue to use it will still work, but a message will be emitted to site administrators (and sent to the site’s debug log) saying that it should be replaced. When we get to version 3.0 of ClassicPress, thickbox may be removed from the bundle of scripts we provide. Then it will no longer work unless you supply your own thickbox library file.

We hope you don’t do that. ClassicPress version 3.0 is some time away, so you have plenty of time to update your code. I hope this guide has shown you how easy it is to do.