The Dialog API in Drupal 8

On a recent Drupal build, a key requirement was to provide a quick and easy way of presenting a user with information without reloading the entire page. This was easily achieved using the Dialog API which provides a simple way of loading interactive content within a dialog window. The embedded content can range from forms, static text, or the results of an external API request.

The Dialog API provides 3 different types of dialog:

  • Modal dialogs – This type of dialog overlaps the entire page, preventing other interactive actions on the page while the user interacts with the dialog
  • Non modal dialogs – This type of dialog stays at the top of the page allowing a user to click on other interactive elements whilst the dialog is open. Multiple dialog windows can be opened at the same time.
  • Off canvas dialogs – Instead of using a popup, this type of dialog displays an off canvas dialog which slides into the page, moving content to one side.

For our requirement, modal dialogs were the best candidate. We wanted to prevent other actions from being completed whilst the dialog was open, giving more focus on the presented information, leading to an improved user experience.

A solution


The first step when using the Dialog API is to ensure the required libraries are loaded. This is added in the custom module which provides dialog functionality. To do this, the libraries were loaded as dependencies within a libraries.yml file in the custom module.


    version: 1.0.0
        theme: css/example.css {}
        js/example.js: {}
        - core/drupal.dialog.ajax - Required to display a dialog
        - core/jquery.form - Optional, If the dialog should support Ajax form interactions

The library is then loaded on pages which require dialog functionality. This is achieved by including the library in the related twig template, giving greater control over where the library should be loaded.

    {{ attach_library(my_module/my_library’) }}

There are several ways to include a custom library. More information on the various approaches can be found here:

Displaying the dialog

In most cases a dialog is opened by a user clicking a link or a call to action (such as a button). In our case it was the latter. Our template contained markup to display a button call to action. When a user clicked this button, we wanted to open and load custom content into a dialog window. We simply added the ‘use-ajax’ class to the desired button to enable dialog support.

    <a href="/my-custom-callback" class="btn btn-outline-primary btn-sm btn-nowrap use-ajax" role="button">Click me</a>

The important pieces of information above are the href value, which should point to a custom route (more on this next), and the ‘use-ajax’ class which must be added to enable dialog support.

The custom href value above must start with ‘/no-js’ followed by the remaining values for the link. For example, ‘/no-js/my-custom-callback’.

The next step was to add a custom routing.yml file in the module which contained the above link with some minor changes.


      path: '/ajax/my-custom-callback'
        _permission: 'access content'

The key information here is the path: value which must start with ‘/ajax’ followed by the link value. Also included is a controller path (responsible for returning the response data to display within the dialog) and the permission a user needs to access this link. For our requirement, ‘access content’ was sufficient.

Note** The link convention must be correct for the dialog to display e.g. ‘/no-js/my-custom-callback’ (for the call to action which opens the dialog) and ‘/ajax/my-custom-callback’ for the link in the routing.yml file.

Finally, the custom controller was added to the module which returns the response data to display within the dialog.


    namespace Drupalmy_moduleController;
    use DrupalCoreAjaxAjaxResponse;
         * @return AjaxResponse
        public function showModalResults()
            $response = new AjaxResponse();
            $content = 'This content will be loaded in the dialog!'
            $response->addCommand(new OpenModalDialogCommand(‘My Dialog title’’, $content, ['width' => '576px', 'height' => 'auto']));
            return $response;

The method was defined above in the routing.yml file. This method will be called when a user clicks on the call to action button. The method is simplified to show a basic response.

As we are returning the data using Ajax, the DrupalCoreAjaxAjaxResponse class include is required. I then create a new Ajax response using this class. In this example the data returned is a basic string, however this could be a custom form or the results of an API request.

A new OpenModalDialogCommand is then added to the response and returned.This class accepts 4 parameters; the title of the dialog which is displayed above the content, the dialog content itself, dialog options which can be used to control basic settings such as width and height (more information here:, and any custom settings. This will result in a popup showing the content displayed within a modal dialog.


By default, the dialog can only be closed by clicking on the ‘X’ icon in the top right hand corner of the dialog. Custom Javascript behaviour can be added allowing the dialog to be closed if a user clicked anywhere outside of it, giving a better user experience.

The default JQuery dialog window looks quite bland, however this can easily be overridden using custom styles.


The Dialog API provides a quick and easy way in Drupal core to display content within a modal without the need of any 3rd party libraries, reducing the amount of code needed to create a dialog, as well as improving the user’s experience by not having to navigate away from the page they are on.

Performance Max new features

Performance Max new features

As we head into the business end of Q4, it’s more important than ever to get better performance from your digital marketing campaigns. One way to do that is through utilising Performance Max campaigns and especially the new features.

Let's chat. Tell us a bit about your project.

 If you prefer to speak with someone, call 01202 203160 or if you'd like to book a 30 min meeting to see if we can help just let us know and we'll arrange a call with one of our Directors.

Attraction Marketing Using Google

Attraction Marketing Using Google

Brunel’s SS Great Britain is Bristol’s number one visitor attraction and a top 10 UK museum (TripAdvisor 2022). It is home to the world’s first great ocean liner, the SS Great Britain, the Being Brunel museum, and the Brunel Institute, which houses one of the world’s finest maritime and Brunel collections. The charity that manages and maintains Brunel’s SS Great Britain and collections is the SS Great Britain Trust.

Charles Stanley Direct PPC

Charles Stanley Direct PPC

Charles Stanley set us the challenge of delivering improved performance from their PPC campaigns. In a highly regulated industry, with multiple stakeholders to govern marketing activities and an ever changing market, the brief called for exceptionally high levels of service, reporting and flexibility.

Avery WePrint – Content Strategy

Avery WePrint – Content Strategy

We were tasked to increase revenue from new and returning customers by delivering a content strategy with objectives to improve SEO for article pages and produce engaging content to link to from their emails..

Google Grant PPC Management

Google Grant PPC Management

Digital Marketing: Google Grant PPC Management IntroductionThe Centre for Ageing Better is an independent charitable foundation, funded by The National Lottery Community Fund. It creates change in policy and practice informed by evidence and works with partners across...

Legoland Discovery Centre Launch Campaign

Legoland Discovery Centre Launch Campaign

We were delighted to win the brief to help Merlin Entertainments’ launch Legoland Discovery Centre, Birmingham.

The ultimate indoor playground was the second to be built in the UK and opened just outside the centre of Birmingham.

SEO and Social Success for Holiday France Direct

SEO and Social Success for Holiday France Direct

Like many businesses, Holiday France Direct wanted to increase the number of visitors to their website from non-paid traffic and increase their social reach and engagement. They came to us with a brief to upgrade their website and to run a programme of monthly SEO and Social activity.

Blackpool Has it All

Blackpool Has it All

We love working in travel and tourism. So we were thrilled when the UK’s top beach resort asked us to plan and deliver the digital marketing for their 2018, 2019 and 2021 destination marketing campaigns.

Post Pandemic Pickup

Post Pandemic Pickup

As global travel markets opened up following the COVID-19 pandemic, we supported a valued client with a range of (very flexible) PPC and social marketing services to help their business rebound.