modal docs

Modal

A content container that usually presents users with a short task or gathered information without losing context of the underlying page.

Published Last updated: 5.3.0 Change log Github NPM
Twig Usage 
{% include '@bolt-elements-button/button.twig' with {
  content: 'Open Modal',
  attributes: {
    type: 'button',
    'data-bolt-modal-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
persistent

Enables the modal to be persistent. This will eliminate ways to close the modal and it is up to the author to provide a custom link to close the modal or redirect to another page within the modal content. Must be used in tandem with the persistent_return_url prop.

 boolean false
  • —
persistent_return_url

The URL to be used on a return link. If a modal is persistent, a return link is required to provide the user a way out. Must be used in tandem with the persistent prop.

 string —
  • —
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 —
  • —
Install Install 
npm install @bolt/components-modal
Dependencies @a11y/focus-trap @bolt/components-button @bolt/components-text @bolt/components-trigger @bolt/core-v3.x @bolt/lazy-queue tabbable

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

Modal Width Variation The modal container's width can be adjusted by the width prop. The default is set to optimal. Important Notes: The full modal takes up the full width of the screen minus the gutters (about 2rem on left and right). The regular modal is 10 out 12 columns wide, about 80% of the screen width. The optimal modal is about 75 characters wide, close to optimal reading length. The auto modal 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. The width prop only applies to viewports equal to or above the small breakpoint (~600px). Advanced usage: use an image that has the width attribute defined (e.g. 640) in tandem with auto width modal will allow the image inside the modal to be responsive but does not stretch beyond the specified width. Demo This is a modal set to full width. This is a modal set to regular width. This is a modal set to optimal width. This is a modal set to auto width. A Rock Climber
Twig
{% include '@bolt-components-modal/modal.twig' with {
  content: 'This is a modal set to full width.',
  width: 'full',
  attributes: {
    class: 'js-bolt-modal--width-full',
  },
} only %}
HTML
Not available in plain HTML. Please use Twig.

modal spacing variations

Modal Spacing Variation The modal container's spacing can be adjusted by the spacing prop. The default is set to medium. Important Notes: The none prop removes the spacing inside the modal container. The small, medium, and large props add the respective spacing around the modal content. The spacing prop only applies to viewports equal to or above the small breakpoint (~600px). Demo This is a modal set to none spacing. This is a modal set to small spacing. This is a modal set to medium spacing. This is a modal set to large spacing.
Twig
{% include '@bolt-components-modal/modal.twig' with {
  content: 'This is a modal set to small spacing.',
  spacing: 'small',
  attributes: {
    class: 'js-bolt-modal--spacing-small',
  },
} only %}
HTML
Not available in plain HTML. Please use Twig.

modal theme variations

Modal Theme Options The modal container's coloring theme can be adjusted by the theme prop. The default is set to xlight. Important Notes: The none prop makes the modal container transparent. The xlight, light, dark, and xdark props adds the respective theme to the modal container. The theme prop only applies to viewports equal to or above the small breakpoint (~600px). Demo This is a modal with a transparent background. This is a modal with a xlight theme. This is a modal with a light theme. This is a modal with a dark theme. This is a modal with a xdark theme.
Twig
{% include '@bolt-components-modal/modal.twig' with {
  content: 'This is a modal with a xlight theme.',
  theme: 'xlight',
  attributes: {
    class: 'js-bolt-modal--theme-xlight',
  },
} only %}
HTML
Not available in plain HTML. Please use Twig.

modal scroll variations

Modal Scroll Options The scrollable area can be adjusted by using the scroll prop. The default is set to container. Important Notes: The overall prop makes the overall viewport area scrollable. The container prop makes the modal container itself scrollable. The scroll prop only applies to viewports equal to or above the small breakpoint (~600px). Demo Tall image Tall image
Twig
{% include '@bolt-components-modal/modal.twig' with {
  content: 'This is a modal set to overall scrolling.',
  scroll: 'overall',
  attributes: {
    class: 'js-bolt-modal--scroll-overall',
  },
} only %}
HTML
Not available in plain HTML. Please use Twig.

modal trigger variations

Modal Trigger Options Examples of different methods of launching a modal. Important Notes: The Button element is the standard method to trigger a modal. Semantic buttons are mandatory for opening a modal, never use a semantic link element. If a text link is needed as the trigger, use the Text Link element, which has the ability to be set as a semantic button element. If an image thumbnail is needed as the trigger, use the Trigger component to wrap around an Image element. Demo This modal is triggered by a button. A Rock Climber This modal is triggered by a text link.
Twig
{# Button element #}
{% include '@bolt-elements-button/button.twig' with {
  content: 'Button trigger',
  size: 'small',
  attributes: {
    type: 'button',
    'data-bolt-modal-target': '.js-bolt-modal--trigger-button',
  },
} only %}
{% include '@bolt-components-modal/modal.twig' with {
  content: 'This modal is triggered by a button.',
  attributes: {
    class: 'js-bolt-modal--trigger-button'
  },
} only %}

{# Image element and Trigger component #}
{% set trigger_content %}
  {% include '@bolt-elements-image/image.twig' with {
    attributes: {
      src: '/images/placeholders/tout-4x3-climber.jpg',
      alt: 'A Rock Climber',
      loading: 'lazy',
      style: 'max-width: 320px',
      width: '640',
      height: '480'
    }
  } only %}
{% endset %}

{% set modal_content %}
  {% include '@bolt-elements-image/image.twig' with {
    attributes: {
      src: '/images/placeholders/tout-4x3-climber.jpg',
      alt: 'A Rock Climber',
      width: '640',
      height: '480'
    }
  } only %}
{% endset %}

{% include '@bolt-components-trigger/trigger.twig' with {
  content: trigger_content,
  cursor: 'zoom-in',
  display: 'inline',
  attributes: {
    'data-bolt-modal-target': '.js-bolt-modal--trigger-image',
  },
} only %}

{% include '@bolt-components-modal/modal.twig' with {
  content: modal_content,
  spacing: 'none',
  theme: 'none',
  scroll: 'overall',
  width: 'auto',
  attributes: {
    class: 'js-bolt-modal--trigger-image'
  },
} only %}

{# Text Link element #}
{% include '@bolt-elements-text-link/text-link.twig' with {
  content: 'Text link trigger',
  attributes: {
    type: 'button',
    'data-bolt-modal-target': '.js-bolt-modal--trigger-link',
  },
} only %}

{% include '@bolt-components-modal/modal.twig' with {
  content: 'This modal is triggered by a text link.',
  attributes: {
    class: 'js-bolt-modal--trigger-link'
  },
} only %}
HTML
Not available in plain HTML. Please use Twig.

modal usage javascript

Toggle the Modal You can toggle a modal either by adding the data-bolt-modal-target data attribute to a trigger element, or by calling the Modal's show() and hide() methods directly via JavaScript. Data attribute Use the data attribute data-bolt-modal-target on a trigger element to toggle a modal. The value of the data attribute must be a valid CSS selector that matches your target modal. When you click the trigger the modal will show if currently hidden or it will hide if currently shown. Demo This modal was shown via the data-bolt-modal-target data attribute. The same data attribute is used on the button below to hide the modal. JavaScript Use the Modal's show() and hide() methods to toggle a modal. Before calling any methods on the modal you must first wait for the Modal component to be ready. See the demo below for reference. Demo This modal was shown by calling the show() method. The hide() method will be called when you click the button below. Custom JavaScript 
<script>
 const modal = document.querySelector('.js-bolt-modal--js-demo');
 const showButton = document.querySelector('.js-bolt-modal-trigger--open');
 const hideButton = document.querySelector('.js-bolt-modal-trigger--close');

 // Promise ensures Modal is defined before calling hide/show
 customElements.whenDefined('bolt-modal').then(() => {
   showButton.addEventListener('click', () => {
     modal.show();
   })
   hideButton.addEventListener('click', () => {
     modal.hide();
   })
 });
</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 the modal inside the modal is bigger than the thumbnail image. Modal width is set to auto and image has width attribute defined.
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 auto and image has width attribute defined.
Image description.

This is the caption for the image.

modal usage video

Video Modal Usage Videos opening and playing in a modal are handled by a couple data attributes. Button Attribute To open a modal, the triggering button requires a data-bolt-modal-target attribute. The value of this attribute is the target modal's class. There is JS that will handle the opening on target modal based on the attribute's value. Video Attributes To prevent a video from initializing on page load, the video-js requires a couple of attributes to delay the initialization. There are four attributes that are required, three of these replace the default Brightcove attributes.
  • data-delayed-account (replaces data-account)
  • data-delayed-player (replaces data-player)
  • data-delayed-video-id (replaces data-video-id)
  • data-video-delayed (flag to delay the initialization)
Within the Brightcove initialization logic these attributes will defer the video initialization until the modal:show event is fired. The JS will create the Brigthcove required attributes on the fly and start the initialization shortly after. After the modal is opened, it will automatically start playing the video Demo

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 persistent

Persistent Modal Usage Persistent modal is useful when creating subscription based content. To create one, two props are required: persistent and persistent_return_url. When a modal is persistent, the default close button is not shown, the only ways to close the modal is through filling out the form, hitting the return link, or hitting the escape key on the keyboard (which acts exactly like the return link). Activate the modal to see more instructions on setting up the twig template.

Template Instructions

Modal content can be anything. Content authors are free to set up single or multiple column layouts. The recommended format is text content on the left and form on the right. The return link is required, which is in its own cell under both the text content and form cells. It should not be part of the free-form authorable content, instead two required fields are required for content authors to input: return link url and return link text.

Sign in to view restricted content
No thanks! Return to last page

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 Modal is a web component. You can simply use <bolt-modal> in the markup to make it render. In the following examples, we use data-bolt-modal-target to trigger the modal. However, the same options shown on the Usage Javascript page are also available on the web component.
This is a modal. 
<button type="button" class="e-bolt-button" data-bolt-modal-target=".js-bolt-modal-demo">
  Open Modal
</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.
This is the header This is the body (default). This is the footer 
<button type="button" class="e-bolt-button" data-bolt-modal-target=".js-bolt-modal-basic-demo">
  Open Modal
</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>
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. 
<button type="button" class="e-bolt-button" data-bolt-modal-target=".js-bolt-modal-advanced-demo">
  Open Modal
</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>