Modal
Display content inside a modal window that is hidden by default and shown when triggered, used to display additional information, confirmation screens, or calls to action.
Live Preview| Use case | Display extra content without leaving the page. |
| Page speed impact | Low initially, depending on the type and amount of content. May have Medium or High impact when using Form or Subscribe options, or heavy resources (large images, videos, CTAs). |
| Available in pages | No, but already included by default with all templates, both as an in-page editable module and global content. |
| Reserved block class | modal |
| Relevant files | css/components/modal.cssjs/components/modal.js |
Quick demo
Good to know
For more advanced control over when and how pop-ups appear, check out HubSpot's pop-up calls-to-action (CTAs) and the official documentation.
Adding a modal
To add a modal, edit your page and go to the Contents tab. At the bottom you will find two modules: Page modals and Global modals:
Use Page modals for modals specific to the current page, such as team member profiles on an About page. Use Global modals for modals that need to be accessible from any page, such as those triggered by a button in the header or footer.
Avoid adding modals to Global modals unless they are actually needed across multiple pages, as this adds unnecessary weight to every page on your site.
Give your modal a unique Custom ID. No other element on the page should share it. For example: john-doe.
Opening a modal
Use the Custom ID you specified above in an onclick field to open the modal:
open_modal('john-doe')open_modal('john-doe')Most modules include an onclick field for links. For the URL field, you can use #0 to avoid page scrolling when opening the modal.
HubSpot calls-to-action redirect the browser to a tracking domain first and only then to the target page, so they cannot open these modals. This only works with regular links/buttons.
Closing a modal
To close a modal from a button or link within the modal window, such as a Cancel button, use the onclick field with the Custom ID of the modal you want to close:
close_modal('john-doe')close_modal('john-doe')Modal gallery
Group modals into a gallery by giving them the same Group ID. Users can then browse through them using prev/next arrows or keyboard keys.
For example, add the Group ID our-team to all team member modals on your About page:
Adding a video, audio or iframe to a modal
For opening an image or video in a popup, the Lightbox may be a better fit. The modal is useful when you need more control, such as preventing autoplay or adding additional content like a title or description alongside the video.
When adding YouTube, Vimeo, or other iframes to a modal, replace the src attribute with data-src and add the modal__iframe class to your iframe. This lazy-loads the iframe so it does not affect page load time.
Below is an example of a YouTube embed with the data-src attribute, modal__iframe class, and the autoplay parameter in the URL. The video plays when the modal opens and stops when it closes. You can compare the differences with your own embed code.
<iframe width="560" height="315" src="https://www.youtube.com/embed/qDCyvvdzND4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe><iframe width="560" height="315" src="https://www.youtube.com/embed/qDCyvvdzND4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe><iframe class="modal__iframe" width="560" height="315" data-src="https://www.youtube.com/embed/qDCyvvdzND4?autoplay=1" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe><iframe class="modal__iframe" width="560" height="315" data-src="https://www.youtube.com/embed/qDCyvvdzND4?autoplay=1" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>For <video> or <audio> HTML elements that should only play when the modal is open, add the modal__media class and replace the autoplay attribute with data-autoplay.
<video width="430" height="242" style="width: 100%; height: auto;" src="https://273774.fs1.hubspotusercontent-na1.net/hubfs/273774/act3/videos/sample-1293jmdsm.mp4" controls preload="metadata" autoplay></video><video width="430" height="242" style="width: 100%; height: auto;" src="https://273774.fs1.hubspotusercontent-na1.net/hubfs/273774/act3/videos/sample-1293jmdsm.mp4" controls preload="metadata" autoplay></video><video width="430" height="242" style="width: 100%; height: auto;" class="modal__media" src="https://273774.fs1.hubspotusercontent-na1.net/hubfs/273774/act3/videos/sample-1293jmdsm.mp4" controls preload="metadata" data-autoplay></video><video width="430" height="242" style="width: 100%; height: auto;" class="modal__media" src="https://273774.fs1.hubspotusercontent-na1.net/hubfs/273774/act3/videos/sample-1293jmdsm.mp4" controls preload="metadata" data-autoplay></video>