Creating a modal in Drupal 8 with one line of HTML

Modal dialogs are incredibly useful on websites as they allow the user to do something without having to leave the web page they are on. Drupal 8 now has a Dialog API in core, which greatly reduces the amount of code you need to write to create a modal dialog. Dialogs in Drupal 8 leverage jQuery UI.

In this first part in the series on the modal API in Drupal 8, we are going to create a search link in a block in the sidebar. When a user clicks on the search link, they will be presented with the modal with Drupal’s search form.

The first step is to add a block to the side bar. Head over to Block Layout and add it to a region of your choice. In this example, I’m going to add it to sidebar first.

Place a block button in Drupal 8

Select Add custom block.

Button to add a custom block in Drupal 8

In the block settings, change the text format to Full HTML and click on the Source button to remove the rich text editor. This will allow you to add a small HTML snippet without the rich text editor trying to encode the HTML.

In the body of the block, add the following snippet:

<p><a class="use-ajax" data-dialog-type="modal" href="/search/node">Search</a></p>

And now if you head back to the site, you will see the block in the side bar. Click on the search link, and you will get the modal.

Search modal

Adjusting the width

You can adjust the width by adding the data-dialog-options attribute:


I’m including the HTML entity &quot; because that will end up being a quote mark in the rendered HTML.

The full snippet with a width of 800 pixels is:

<p><a class="use-ajax" data-dialog-options="{&quot;width&quot;:800}" data-dialog-type="modal" href="/search/node">Search</a></p>

Wrapping up

You can use this method to display any valid Drupal path in a modal. For example, if you want to show a node in a modal, change the href to the path for the node.

<p><a class="use-ajax" data-dialog-options="{&quot;width&quot;:800}" data-dialog-type="modal" href="/node/2">See node 2</a></p>

These examples show the power of Drupal 8’s dialog API. With just a couple of attributes in a standard link, you can display any path in a modal.

This is a very simple example to help get you started. In most cases, adding modals is done in custom modules or themes. To find out how to do this in a custom module, check out the next tutorial in the series: Create a modal in Drupal 8 in a custom module

If you liked this, you'll love my book, Conquer Drupal 8 Module Development.


Excellent write-up. Clear and concise, had no idea it was this easy to accomplish something that is seemingly quite complex!

The above example is not working.

Blair Wadman's picture

If you have copy and pasted, can you check the quotation marks? Also, check that you have Full HTML selected and the rich text editor is off (hit the Source button)

I haven't tried it myself, but unless I'm mistaken, this won't work unless you have some other AJAX functionality on that page. The "magic" will only work if the <code>core/misc/ajax.js</code> file is included in the page – which will happen automatically for any properly included AJAX functionality, but not for a custom block with HTML in it.

@ Blair: Could that be the case, or am I mistaken?

Blair Wadman's picture

As far as I'm aware, as long as the jQuery UI dialog JS in on the page, this will work.

I've tested this again with a brand new install of Drupal 8.3.6 without enabling anything other than the update module and it works just fine.

Amazing, thank you. Every other article I found made this overly complex.

Sorry but, I'm not agree with the utility of this article.
It's a poor technique to do something like this. It's not maintainable, not exportable, not secure and not customisable.
Moreover the examples are not the most suitable to show this functionality.
Stuff like that produce always a "technical debt" that is really complicated to reduce or to fix later. It can produce a really high reduction of the quality too. If it's necessary to do it, do it in a template.
At least it will be more maintainable.

Blair Wadman's picture

See Create a modal in Drupal 8 in a custom module for the next tutorial in the series, which is how to do this in a custom module.

Not working for me. On D8.36. Added directly to source...

Blair Wadman's picture

I've tested this again with a brand new install of Drupal 8.3.6 without enabling anything other than the update module and it works just fine.

Can you check that jQuery UI dialog is on the page (you'll need to disable JS aggregation first):

<script src="/core/assets/vendor/jquery.ui/ui/dialog-min.js?v=1.11.4"></script>

For this tip to work, you need to enable ajax in jquery in your theme.

Nice! Ty

How can i add custom class to the drupal model id when it opens. Don't want to add by jquery .

Thank you for this great tip!

Any idea why it doesn't work for anonymous users?

This worked for me before upgrading to core 8.4 (with jquery3). However, the data-dialog-options seem to be ignored now, all modals open with default 300px width. From the API documentation I can not figure out if the syntax has changed. Any clues?

wow.. its really nice...
thanks ur great effort

Thanks for this great tutorial.

I have been this link and altering the href value in ajax response. But after updating the link, when i click on it is reloading the page instead of showing the modal popup.. I tried many different ways but it is not working. Could you please help me on this...

This works for me if it goes to a page like /search/node but if I try to have it go to an image (e.g. href='/files/myimage.jpg') then the popup doesn't open

New comments for this tutorial have been turned off.