modal docs

2.20.0

Modal

The Modal component presents users with a short task or gathered information without losing context of the underlying page.

Published

History
View changes
Install
yarn add @bolt/components-modal
Source code
View on Github
Dependencies

Overview

The Modal component presents users with a short task or gathered information without losing context of the underlying page. Part of the collection of components, visual styles, and build tools that power the Bolt Design System.

Install via NPM
npm install @bolt/components-modal

Usage

  {% include "@bolt-components-button/button.twig" with {
  text: "Open Modal",
  attributes: {
    "on-click": "show",
    "on-click-target": "js-target-name"
  }
} only %}

{% include "@bolt-components-modal/modal.twig" with {
  content: "This is a modal",
  attributes: {
    class: "js-target-name"
  },
} only %}

Schema

Note: when assigning component props as HTML attributes on a web component, make sure to use kebab-case.

Prop Name Description Type Default Value Option(s)
attributes

A Drupal attributes object. Used to apply additional HTML attributes to the outer <bolt-modal> tag.

 object —
  • —
width

Controls the width of the modal container.

 string optimal
  • full, regular, optimal, auto
spacing

Controls the spacing around the modal container.

 string medium
  • none, small, medium, large
theme

Controls the color theme of the modal container.

 string xlight
  • none, xlight, light, dark, xdark
scroll

Controls the scrolling area.

 string container
  • overall or container
uuid

Unique ID for modal, randomly generated if not provided.

 string —
  • —
slots

There are 3 sections (slots) within the modal container. By assigning the appropriate slot name, content will be passed into the respective section.

 object —
    • default

      The body section of the modal container.

      • —
    • header

      The header section of the modal container.

      • —
    • footer

      The footer section of the modal container.

      • —
Open Accordion Close Accordion
disabled

Default disabled prop supported globally by most Bolt components.

 boolean —
  • —
no_shadow

Manually disables the component from rendering to the Shadow DOM in a Twig template. Useful for testing cross browser functionality / rendering behavior. By default this is handled globally based on browser support.

 boolean —
  • —
no-shadow

Manually disables the web component from rendering to the Shadow DOM. Useful for testing cross browser functionality / rendering behavior. By default this is handled globally based on browser support.

 boolean —
  • —

modal

This is the modal container's header.

This is the modal container's body

This is the modal container's body.

This is the modal container's footer.

modal width variations

The modal container's width can be adjusted by the width prop. The default is set to optimal. Width Options
This is a modal set to full width. This is taking up the full width of the screen minus the gutters (about 2rem on left and right).
This is a modal set to regular width. This is 10 out 12 columns wide, about 80% of the screen width.
This is a modal set to optimal width. This is about 75 characters wide, close to optimal reading length.
This is a modal set to auto width. This adjusts to the width of the modal content. In most cases, the user must define a max-width in absolute value (do not use relative value such as %) on the modal content to get the desired results. Recommended for advanced usage.
Additional Notes: this prop only applies to viewports equal to or above the small breakpoint (~600px).

modal spacing variations

The modal container's spacing can be adjusted by the spacing prop. The default is set to medium. Spacing Options
This is a modal set to none spacing. This removes the spacing inside the modal container.
This is a modal set to small spacing. This sets small inset spacing on the modal container.
This is a modal set to medium spacing. This sets medium inset spacing on the modal container.
This is a modal set to large spacing. This sets large inset spacing on the modal container.
Additional Notes: this prop only applies to viewports equal to or above the small breakpoint (~600px).

modal theme variations

The modal container's coloring theme can be adjusted by the theme prop. The default is set to xlight. Theme Options
This is a modal set to none theme. This makes the modal container transparent.
This is a modal set to xlight theme. This sets the xlight theme on the modal container.
This is a modal set to light theme. This sets the light theme on the modal container.
This is a modal set to dark theme. This sets the dark theme on the modal container.
This is a modal set to xdark theme. This sets the xdark theme on the modal container.
Additional Notes: this prop only applies to viewports equal to or above the small breakpoint (~600px).

modal scroll variations

The scrollable area can be adjusted by using the scroll prop. The default is set to container. Scroll Options
Tall image Tall image This makes the overall viewport area scrollable.
Tall image Tall image This makes the modal container itself scrollable.
Additional Notes: this prop only applies to viewports equal to or above the small breakpoint (~600px).

modal trigger variations

Trigger Options
This modal is triggered by a button. The Button component is the standard method to trigger a modal.
A Rock Climber A Rock Climber

Image trigger can be created by wrapping the Trigger component around an Image component.

Advanced usage: if the Image component has an absolute value (e.g. 640px) defined for max_width, then the modal's width prop can be set to auto. This will allow the image inside the modal to be responsive but does not stretch beyond the specified max_width.
Link trigger Link trigger is currently not supported.

modal usage javascript

Custom JavaScript Usage You can write custom JavaScript to target the modal and attach behaviors. The following is an example of how you can use JavaScript to manipulate the Modal component. Please note that Bolt does not ship with any of this custom JavaScript. Demo
Automatically open a modal Use custom JavaScript to automatically open a modal on page load, after a short delay. Click on the "Activate JavaScript" button to see a demo. The page will reload and a modal will open after 3 seconds.

Auto-open Modal

This modal will open 3 seconds after page load.
Custom JavaScript <script> // Add parameter to the URL - demo helper function, not required in production var setAutoOpenModalParam = function(set){ var currentUrl = window.location.href.split('?').shift(); var param = '?showModal=true'; window.location.href = set ? currentUrl + param : currentUrl; } // Get parameter to the URL - demo helper function, not required in production var getUrlParameter = function(name) { name = name.replace(/[\[]/, '\\[').replace(/[\]]/, '\\]'); var regex = new RegExp('[\\?&]' + name + '=([^&#]*)'); var results = regex.exec(location.search); return results === null ? '' : decodeURIComponent(results[1].replace(/\+/g, ' ')); }; // Reference to the modal var autoOpenModal = document.querySelector('#js-modal-advanced-auto-open'); // Calls modal 'show' method after a delay var setAutoOpenModal = function(el) { if (getUrlParameter('showModal')) { setTimeout(function(){ el.show(); }, 3000) } } // Callback on modal 'ready' var onModalReady = function(e) { setAutoOpenModal(autoOpenModal); // IMPORTANT: remove this event listener unless you want it called each time the modal component renders e.target.removeEventListener('modal:ready', onModalReady); } // Add 'ready' callback autoOpenModal.addEventListener('modal:ready', onModalReady); </script> Demo
Automatically close a modal Use custom JavaScript to automatically close a modal after a set period of time. Click on the "Open Modal" button to see a demo. The modal will open and automatically close after 3 seconds.

Auto-close Modal

This modal will close 3 seconds after opening.
Custom JavaScript <script> openAutoCloseModal = function() { // Reference to the modal var autoCloseModal = document.querySelector('#js-modal-advanced-auto-close'); // When modal opens, start a timer and close after 3 seconds var onModalShow = function() { setTimeout(function() { autoCloseModal.hide(); // Don't forget to remove the event listener autoCloseModal.removeEventListener('modal:show', onModalShow); }, 3000); }; // Wait for 'modal:show' event and call custom function autoCloseModal.addEventListener('modal:show', onModalShow); if (autoCloseModal._wasInitiallyRendered) { // If modal is ready, show it now autoCloseModal.show(); } else { // Otherwise, wait to show until 'modal:ready' event is emitted autoCloseModal.addEventListener('modal:ready', function() { autoCloseModal.show(); }); } }; </script>

modal usage image and caption

Image Modal Usage <bolt-trigger> is needed to create an image modal that gets triggered from either the Image component or the Device Viewer component. The following are examples of how you can assemble the necessary pieces together. Please note that you should use the width prop on <bolt-modal> to accommodate your needs, optimal width is about 70 characters wide, full width will take up the width of the page.
Enlarge image and show caption Create a thumbnail image trigger and pass a figure with image and caption into the modal content. Note: make sure you upload a high-resolution image (up to 2880px wide) if you intend to show the image as big as possible. Modal width is set to auto and image max-width is set to 1000px.
Image description. Image description.

This is the caption for the image.
Enlarge image (inside device viewer) and show caption Create a device viewer trigger and pass a figure with image and caption into the modal content. Note: make sure you upload a high-resolution image (up to 2880px wide) if you intend to show the image as big as possible. Modal width is set to optimal .
Image description. Image description.

This is the caption for the image.

modal usage video

Video Modal Usage There are two options for playing a video in a modal. Both require some custom JavaScript. Option 1: Modal triggers Video Clicking a button calls a modal's show method. Custom JavaScript listens for the event and plays the video when it happens. Demo
Custom JavaScript <script> // Play the video on modal show, pause on hide const modal1 = document.querySelector('.js-modal-123'); const video1 = document.querySelector('.js-modal-video-123'); modal1.addEventListener('modal:show', function() { video1.play(); }); modal1.addEventListener('modal:hide', function() { video1.pause(); }); </script> Option 2: Video triggers Modal Clicking a button calls a video's toggle method. Custom JavaScript listens for the event and opens the modal when it happens. Demo
Custom JavaScript <script> // Show modal on video toggle, pause on modal hide const modal2 = document.querySelector('.js-modal-456'); const video2 = document.querySelector('.js-modal-video-456'); video2.addEventListener('playing', function() { modal2.show(); }); modal2.addEventListener('modal:hide', function() { video2.pause(); }); </script>

modal usage content

Content Modal Usage Content modals can be as simple as a few lines of text or as complex as a page layout. Note: when using bands inside a modal, the full_bleed prop must be set to false.
Show a simple layout Pass any components inside the modal content to create simple layouts, such as short confirmations, alerts, notifications, etc.

This Is a Headline

This is a paragraph. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. In pellentesque faucibus vestibulum. Nulla at nulla justo, eget luctus tortor. Nulla facilisi. Duis aliquet egestas purus in blandit. Curabitur vulputate, ligula lacinia scelerisque tempor, lacus lacus ornare ante, ac egestas est urna sit amet arcu. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie augue sit amet leo consequat posuere. Vestibulum ante.
Show a complex layout Create complex layouts with components and layout objects inside the modal content and set the modal width to full to maximize space. For example, you can build a multi-column layout with the grid, band, and card components.

This Is an Eyebrow

This Is a Headline

This Is a Subheadline

This is a paragraph. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. In pellentesque faucibus vestibulum. Nulla at nulla justo, eget luctus tortor. Nulla facilisi. Duis aliquet egestas purus in blandit. Curabitur vulputate, ligula lacinia scelerisque tempor, lacus lacus ornare ante, ac egestas est urna sit amet arcu. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie augue sit amet leo consequat posuere. Vestibulum ante.

Sign in to view PegaWorld live stream

modal usage form

Form Modal Usage Form modals are best suited for presenting a paywall, signup/login, or content restrictions.
Form only Pass some text and a form into the modal content.

Get the report

(all fields are required)

modal with web component

"on-click": "show", "on-click-target": "js-modal-123"
Web Component Usage Modal is a web component. You can simply use <bolt-modal> in the markup to make it render. In the following examples, we use onclick to trigger the modal. However, the same options shown on the Trigger Options page are also available on the web component.
Open Modal This is a modal.
<bolt-button on-click="show" on-click-target="js-bolt-modal-demo"> Open Modal </bolt-button> <bolt-modal class="js-bolt-modal-demo"> This is a modal. </bolt-modal>
Basic Usage The modal container has 3 sections (slots) for passing content, header, default, footer. To pass content to either the header or footer, slot must be defined.
Open Modal This is the header This is the body (default). This is the footer
<bolt-button on-click="show" on-click-target="js-bolt-modal-basic-demo"> Open Modal </bolt-button> <bolt-modal class="js-bolt-modal-basic-demo"> <bolt-text slot="header">This is the header</bolt-text> <bolt-text>This is the body (default).</bolt-text> <bolt-text slot="footer">This is the footer</bolt-text> </bolt-modal>
Trigger Usage When using an open button that comes right before a <bolt-modal>, set onclick to this.nextElementSibling.show(). When using a close button that's inside a <bolt-modal>, set onclick to this.closest('bolt-modal').hide().
Open Modal This modal has a close button along with the content. Close Modal
<bolt-button on-click="show" on-click-target="js-bolt-modal-trigger-demo"> Open Modal </bolt-button> <bolt-modal class="js-bolt-modal-trigger-demo"> <bolt-text>This modal has a close button along with the content.</bolt-text> <bolt-button on-click="hide">Close Modal</bolt-button> </bolt-modal>
Advanced Usage The web component has all the options shown in the schema table. You can define each prop on the <bolt-modal> element. Use unique combinations to customize a modal to your liking.
Open Modal
<bolt-button on-click="show" on-click-target="js-bolt-modal-advanced-demo"> Open Modal </bolt-button> <bolt-modal width="optimal" spacing="none" theme="none" scroll="overall" class="js-bolt-modal-advanced-demo"> <bolt-image src="/images/content/backgrounds/background-robotics-customer-service.jpg" alt="This is an image"></bolt-image> </bolt-modal>
Server-side Rendered Web Components (Experimental) The Modal component, among many other web components in Bolt, will support server-side rendering via the new upcoming {% filter bolt_ssr %} custom Twig filter. Check out the docs on server-side rendering for information!
Open Modal This is a modal.
{% filter bolt_ssr %} <bolt-button on-click="show" on-click-target="js-bolt-modal-ssr-demo"> Open Modal </bolt-button> <bolt-modal class="js-bolt-modal-ssr-demo"> This is a modal. </bolt-modal> {% endfilter %}
Debug Panel