Dialog

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.5.0

Github

NPM

Twig Usage

{# Render a trigger button #}
{% include '@bolt-elements-button/button.twig' with {
  content: 'Open dialog',
  attributes: {
    type: 'button',
    'data-bolt-dialog-target': '#dialog-1',
  }
} only %}

{# Render the related dialog #}
{% set dialog_content %}
  {% include '@bolt-components-dialog/dialog-header.twig' with {
    content: header_content,
  } only %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: body_content,
  } only %}
  {% include '@bolt-components-dialog/dialog-footer.twig' with {
    content: footer_content,
  } only %}
{% endset %}
{% include '@bolt-components-dialog/dialog.twig' with {
  content: dialog_content,
  attributes: {
    id: 'dialog-1'
  },
} only %}

Schema

Dialog (dialog.twig)

Prop Name	Description	Type	Default Value	Option(s)
attributes	A Drupal-style attributes object with extra attributes to append to this component.	`object`	—	—
content	Renders the dialog content. The dialog-header.twig, dialog-body.twig, and dialog-footer.twig components are expected here.	`any`	—	—
width	Controls the width of the dialog.	`string`	`optimal`	`full`, `regular`, `optimal`, `auto`
spacing	Controls the inset spacing of the dialog header, body, and footer.	`string`	`medium`	`none`, `small`, `medium`, `large`
persistent	Enables the dialog to be persistent. This will eliminate ways to close the dialog and it is up to the author to provide a custom link to close the dialog or redirect to another page within the dialog content.	`boolean`	`false`	—
transparent	Renders a transparent background for the dialog. Only use this when building an image or video only modal without any text. Do not pass header and footer as text will not be legible with a transparent background.	`boolean`	`false`	—

Dialog Header (dialog-header.twig)

Prop Name	Description	Type	Default Value	Option(s)
attributes	A Drupal attributes object. Applies extra HTML attributes to the parent element.	`object`	—	—
content	Main content of the dialog header.	`any`	—	—

Dialog Body (dialog-body.twig)

Prop Name	Description	Type	Default Value	Option(s)
attributes	A Drupal attributes object. Applies extra HTML attributes to the parent element.	`object`	—	—
content	Main content of the dialog body.	`any`	—	—

Dialog Footer (dialog-footer.twig)

Prop Name	Description	Type	Default Value	Option(s)
attributes	A Drupal attributes object. Applies extra HTML attributes to the parent element.	`object`	—	—
content	Main content of the dialog footer.	`any`	—	—

Install

npm install @bolt/components-dialog

Dependencies

@bolt/core-v3.x

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Basic Dialog

A dialog can be used to display interactive content over a webpage. The element is generally hidden on page load and becomes visible after interaction with a trigger. Triggers are typically a Button element or Text Link element.

Important Notes:

This is a replacement for the Modal component.

The trigger must be a semantic <button>.

To relate a trigger to a specific dialog, add the data-bolt-dialog-target attribute to the trigger and set the value to the <dialog>’s unique id or class name (eg. #dialog-1).

There are 3 content areas within a dialog: header, body, and footer. Header and footer are optional, only use them when you need sticky header and footer. Use body for regular dialog content. Each area comes with its own template:

dialog-header.twig

dialog-body.twig

dialog-footer.twig

Reference the Dialog schema for all options.

Demo

Twig

{# Render a trigger button #}
{% include '@bolt-elements-button/button.twig' with {
  content: 'Open dialog',
  attributes: {
    type: 'button',
    'data-bolt-dialog-target': '#dialog-1',
  }
} only %}

{# Render the related dialog #}
{% set dialog_content %}
  {% include '@bolt-components-dialog/dialog-header.twig' with {
    content: header_content,
  } only %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: body_content,
  } only %}
  {% include '@bolt-components-dialog/dialog-footer.twig' with {
    content: footer_content,
  } only %}
{% endset %}
{% include '@bolt-components-dialog/dialog.twig' with {
  content: dialog_content,
  attributes: {
    id: 'dialog-1'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Dialog Width

A width can be explicitly set on a dialog. By default, a dialog is about 75 characters wide.

Important Notes:

Use the width prop to adjust the dialog’s width.

Full: This is taking up the full width of the screen minus the gutters (about 2rem on left and right).

Regular: This is 10 out 12 columns wide, about 80% of the screen width.

Optimal: This is about 75 characters wide, close to optimal reading length (This is the default setting).

Auto: This adapts the width of the dialog content. Only use this option if the dialog content has an explicit width. Recommended for advanced usage.

Demo

Twig

{% include '@bolt-components-dialog/dialog.twig' with {
  content: content,
  width: 'full',
  attributes: {
    id: 'dialog-width-1'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Dialog Spacing

The inset spacing of the dialog’s header, body, and footer is adjustable.

Important Notes:

Use the spacing prop to control the spacing. It can even be set to none to remove all spacing.

Reference the Dialog schema for all options.

Demo

Twig

{% include '@bolt-components-dialog/dialog.twig' with {
  content: content,
  spacing: 'large',
  attributes: {
    id: 'dialog-spacing-1'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Persistent Dialog

A persistent dialog is useful when creating paywall or subscription-wall.

Important Notes:

Set the persistent prop to true to make a dialog persistent.

When a dialog is persistent the default close button is not shown and clicking anywhere outside the dialog will not close the dialog.

A close method is mandatory, make sure to manually add a trigger with the data-dialog-close attribute to close a persistent dialog or a link to navigate to another page in the dialog content.

Demo

Twig

{% include '@bolt-components-dialog/dialog.twig' with {
  content: content,
  persistent: true,
  attributes: {
    id: 'dialog-persistent-1'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Transparent Dialog

A transparent dialog is recommended when creating image or video only dialogs, and other advanced dialogs.

Important Notes:

Set the transparent prop to true to make a dialog transparent.

When building advanced transparent dialogs, make sure to adjust text color or manually add background color because the dialog has no background at all.

See the image only dialog use case.

See the video only dialog use case.

Demo

Twig

{% include '@bolt-elements-button/button.twig' with {
  content: 'Transparent dialog',
  attributes: {
    type: 'button',
    'data-bolt-dialog-target': '#dialog-transparent',
  }
} only %}

{% set dialog_content %}
  {# Manually set the color theme (text + background color) #}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: 'Lorem, ipsum dolor sit amet consectetur adipisicing elit. Mollitia aliquam distinctio optio debitis ab praesentium, velit magnam aliquid tenetur sequi ipsam maiores porro sapiente eaque. Maiores quibusdam eaque cupiditate placeat?',
    attributes: {
      class: 't-bolt-yellow',
    },
  } only %}
{% endset %}

{% include '@bolt-components-dialog/dialog.twig' with {
  content: dialog_content,
  transparent: true,
  attributes: {
    id: 'dialog-transparent'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Dialog Theme

A dialog can apply its own color theme that is independent of the page.

Important Notes:

See the Theming System page for all color themes.

Demo

Twig

{% include '@bolt-components-dialog/dialog.twig' with {
  content: content,
  attributes: {
    class: 't-bolt-navy',
    id: 'dialog-theme-1',
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Image Dialog

Dialog can be used to display just an image or an image with text caption.

Important Notes:

When building an image only dialog, set spacing prop to none and transparent prop to true.

When building an image dialog with caption, use the footer for the caption text.

If width and height are defined on the image, set the dialog’s width prop to auto. This allows the dialog to be as big as the image size.

Demo

Twig

{# Image only dialog #}
{% set image_dialog_content %}
  {% set image %}
    {% include '@bolt-elements-image/image.twig' with {
      attributes: {
        src: '/images/placeholders/tout-4x3-climber.jpg',
        alt: 'Alt text.',
        loading: 'lazy',
        width: 640,
        height: 480,
      }
    } only %}
  {% endset %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: image,
  } only %}
{% endset %}
{% include '@bolt-components-dialog/dialog.twig' with {
  content: image_dialog_content,
  spacing: 'none',
  width: 'auto',
  transparent: true,
  attributes: {
    id: 'dialog-image'
  },
} only %}

{# Image + caption dialog #}
{% set caption_dialog_content %}
  {% set image %}
    {% include '@bolt-elements-image/image.twig' with {
      attributes: {
        src: '/images/placeholders/tout-4x3-climber.jpg',
        alt: 'Alt text.',
        loading: 'lazy',
        width: 640,
        height: 480,
      }
    } only %}
  {% endset %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: image,
  } only %}
  {% include '@bolt-components-dialog/dialog-footer.twig' with {
    content: 'This is the image caption.',
  } only %}
{% endset %}
{% include '@bolt-components-dialog/dialog.twig' with {
  content: caption_dialog_content,
  spacing: 'small',
  width: 'auto',
  attributes: {
    id: 'dialog-caption'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Dialog Video

Dialog can be used to display just an video or an video with text description.

Important Notes:

When building a video only dialog, set spacing prop to none and transparent prop to true.

When building a video dialog with description, use the footer for the description text.

To automatically play a Brightcove video when a dialog opens, you must add some specific data-attributes. These attributes delay the video initialization. When these attributes are present, the video will initialize when the dialog opens, automatically begin playing, and pause when the dialog closes:

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)

Demo

Twig

{# Video only dialog #}
{% set image_dialog_content %}
  {% set video %}
    {% set brightcove %}
      <video-js
        data-delayed-account="1900410236"
        data-delayed-player="O3FkeBiaDz"
        data-delayed-video-id="4892122320001"
        data-video-delayed
        data-embed="default"
        controls
        data-media-title
        data-media-duration
        class="c-base-video"></video-js>
    {% endset %}
    {% include '@bolt-elements-ratio/ratio.twig' with {
      content: brightcove,
      ratio: 'wide'
    } only %}
  {% endset %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: video,
  } only %}
{% endset %}
{% include '@bolt-components-dialog/dialog.twig' with {
  content: image_dialog_content,
  spacing: 'none',
  transparent: true,
  attributes: {
    id: 'dialog-video'
  },
} only %}

{# Video + description dialog #}
{% set caption_dialog_content %}
  {% set video %}
    {% set brightcove %}
      <video-js
        data-delayed-account="1900410236"
        data-delayed-player="O3FkeBiaDz"
        data-delayed-video-id="4892122320001"
        data-video-delayed
        data-embed="default"
        controls
        data-media-title
        data-media-duration
        class="c-base-video"></video-js>
    {% endset %}
    {% include '@bolt-elements-ratio/ratio.twig' with {
      content: brightcove,
      ratio: 'wide'
    } only %}
  {% endset %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: video,
  } only %}
  {% include '@bolt-components-dialog/dialog-footer.twig' with {
    content: 'This is the video description.',
  } only %}
{% endset %}
{% include '@bolt-components-dialog/dialog.twig' with {
  content: caption_dialog_content,
  spacing: 'small',
  attributes: {
    id: 'dialog-description'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Dialog Form Usage

A form dialog is best suited for presenting content restriction message or account creation/registration.

Important Notes:

Utilize all the dialog areas to create the best experience: header, body, and footer. Header and footer can become sticky when the body gets too tall.

Render the form inside the body. The <form> element must have an id.

Render form controls inside the footer. Each <button> element must have the form attribute set to the id of the <form> element.

Demo

Twig

{% set header_content %}
  {% include '@bolt-components-headline/headline.twig' with {
    text: 'Get the Report',
    size: 'xlarge'
  } only %}
  {% include '@bolt-components-headline/text.twig' with {
    text: '(all fields are required)',
    size: 'small'
  } only %}
{% endset %}

{% set body_content %}
  <form id="form-uuid-123">
    {# form elements #}
  </form>
{% endset %}

{% set footer_content %}
  {% set icon_download %}
    {% include '@bolt-elements-icon/icon.twig' with {
      name: 'download',
    } only %}
  {% endset %}
  {% include '@bolt-elements-button/button.twig' with {
    content: 'Download Now',
    icon_before: icon_download,
    display: 'block',
    attributes: {
      type: 'submit',
      form: 'form-uuid-123',
    },
  } only %}
{% endset %}

{% set dialog_content %}
  {% include '@bolt-components-dialog/dialog-header.twig' with {
    content: header_content,
  } only %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: body_content,
  } only %}
  {% include '@bolt-components-dialog/dialog-footer.twig' with {
    content: footer_content,
  } only %}
{% endset %}

{% include '@bolt-components-dialog/dialog.twig' with {
  content: dialog_content,
  attributes: {
    id: 'dialog-form'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

Dialog is only supported in Safari 15.4 and newer. Use Modal component instead if you need to support older browsers.

Dialog with Complex Layouts

Layouts and grids can be used within a dialog to create complex design.

Important Notes:

While this is possible to do, we do not encourage building complex layouts within a dialog. Consider other design patterns before resorting to this.

Demo

Twig

{% set layout %}
  {% include '@bolt-layouts-layout/layout.twig' with {
    content: 'Complex layout goes here',
    padding_top: 'medium',
    padding_bottom: 'none',
  } only %}
{% endset %}
{% set footer_content %}
  {% include '@bolt-elements-button/button.twig' with {
    content: 'View full profile',
    display: 'block',
    attributes: {
      href: 'https://pega.com',
    },
  } only %}
{% endset %}
{% set dialog_content %}
  {% include '@bolt-components-dialog/dialog-body.twig' with {
    content: layout,
  } only %}
  {% include '@bolt-components-dialog/dialog-footer.twig' with {
    content: footer_content,
  } only %}
{% endset %}

{% include '@bolt-components-dialog/dialog.twig' with {
  content: dialog_content,
  attributes: {
    id: 'dialog-layout'
  },
} only %}

HTML

Not available in plain HTML. Please use Twig.

dialog

dialog docs Show Code Hide Code

Dialog

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

dialog Show Code Hide Code

dialog width Show Code Hide Code

dialog spacing Show Code Hide Code

dialog persistent Show Code Hide Code

dialog transparent Show Code Hide Code

dialog themes Show Code Hide Code

dialog use case image Show Code Hide Code

dialog use case video Show Code Hide Code

dialog use case form Show Code Hide Code

dialog use case layouts Show Code Hide Code

dialog docs

dialog

dialog width

dialog spacing

dialog persistent

dialog transparent

dialog themes

dialog use case image

dialog use case video

dialog use case form

dialog use case layouts