modal docs

2.6.0-beta.1

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-modal/modal.twig" 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 with extra HTML attributes to the outer <bolt-modal> tag.

 object —
  • —
width

Controls the width of the modal container.

 string optimal
  • auto, regular, optimal, full
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.

      • —

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, which is about 70 characters wide. Note: this prop only applies to viewports equal to or above the small breakpoint (~600px).
Auto Width This is a modal set to auto width.
Regular Width This is a modal set to regular width.
Optimal Width This is a modal set to optimal width.
Full Width This is a modal set to full width.

modal spacing variations

The modal container's spacing can be adjusted by the spacing prop. The default is set to medium. Note: this prop only applies to viewports equal to or above the small breakpoint (~600px).
None Spacing This is a modal set to none spacing.
Small Spacing This is a modal set to small spacing.
Medium Spacing This is a modal set to medium spacing.
Large Spacing This is a modal set to large spacing.

modal theme variations

The modal container's coloring theme can be adjusted by the theme prop. The default is set to xlight. It can also be set to none to make the container completely transparent. Note: this prop only applies to viewports equal to or above the small breakpoint (~600px).
None Theme This is a modal set to none theme.
Xlight Theme This is a modal set to xlight theme.
Light Theme This is a modal set to light theme.
Dark Theme This is a modal set to dark theme.
Xdark Theme This is a modal set to xdark theme.

modal scroll variations

The scrollable area can be adjusted by using the scroll prop. By default, the modal container is scrollable, but it can be changed to have the overall area to be scrollable. Note: this prop only applies to viewports equal to or above the small breakpoint (~600px).
Scroll Area: Overall Tall image Tall image
Scroll Area: Container Tall image Tall image

modal trigger variations

Button Trigger This modal is triggered by a button.
Image Trigger
Link Trigger Warning: this is experimental and should not be replicated on production sites. Open Modal This modal is triggered by a link.

modal usage javascript

Custom Javascript Usage You can write custom javascript to target the modal and attach specific behaviors. Please note that Bolt does not ship with custom javascript, the following is an example of how you can manipulate the bolt-modal component. Demo
Automatically open a modal Use custom javascript to automatically open a modal on page load (after a short delay). Click on the activate 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>

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 res image (up to 2880px wide) if you intend to show the image as big as possible. Modal width is set to full.
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 res 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 a simple layout, 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

Web Component Usage Bolt Modal is a web component, you can simply use <bolt-modal> in the markup to make it render. For the trigger, you must use onclick to activate the modal.
Open Modal This is a modal.
<bolt-button onclick="this.nextElementSibling.show()"> Open Modal </bolt-button> <bolt-modal> 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 prop must be defined.
Open Modal This is the header This is the body (default). This is the footer
<bolt-button onclick="this.nextElementSibling.show()"> Open Modal </bolt-button> <bolt-modal> <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 the onclick to: this.nextElementSibling.show() When using a close button that's inside a <bolt-modal>, set the onclick to: this.closest('bolt-modal').hide()
Open Modal This modal has a close button along with the content. Close Modal
<bolt-button onclick="this.nextElementSibling.show()"> Open Modal </bolt-button> <bolt-modal> <bolt-text>This modal has a close button along with the content.</bolt-text> <bolt-button onclick="this.closest('bolt-modal').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 within the <bolt-modal> element. Use unique combinations to customize a modal to your liking.
Open Modal
<bolt-button onclick="this.nextElementSibling.show()"> Open Modal </bolt-button> <bolt-modal width="optimal" spacing="none" theme="none" scroll="overall"> <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 <bolt-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 onclick="this.nextElementSibling.show()"> Open Modal </bolt-button> <bolt-modal> This is a modal. </bolt-modal> {% endfilter %}