Skip to main content
Modals communicate information via a secondary window and allow the user to maintain the context of a particular task. Use Modals sparingly because they interrupt user workflow.

Passive Modal

<!-- 
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<button class="bx--btn bx--btn--primary" type="button" data-modal-target="#modal-5ppouesvfhc">Show
  modal</button>

<div data-modal id="modal-5ppouesvfhc" class="bx--modal " role="dialog"
  aria-modal="true" aria-labelledby="modal-5ppouesvfhc-label" aria-describedby="modal-5ppouesvfhc-heading" tabindex="-1">
  <div class="bx--modal-container">
    <div class="bx--modal-header">
      <p class="bx--modal-header__label bx--type-delta" id="modal-5ppouesvfhc-label">Optional label</p>
      <p class="bx--modal-header__heading bx--type-beta" id="modal-5ppouesvfhc-heading">Modal heading</p>
      <button class="bx--modal-close" type="button" data-modal-close aria-label="close modal"  data-modal-primary-focus>
          <svg class="bx--modal-close__icon" width="10" height="10" viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
            <title>Close Modal</title>
            <path d="M6.32 5L10 8.68 8.68 10 5 6.32 1.32 10 0 8.68 3.68 5 0 1.32 1.32 0 5 3.68 8.68 0 10 1.32 6.32 5z" fill-rule="nonzero"
            />
          </svg>
      </button>
    </div>

    <div class="bx--modal-content">
      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id accumsan augue. Phasellus consequat augue
        vitae
        tellus tincidunt posuere. Curabitur justo urna, consectetur vel elit iaculis, ultrices condimentum risus. Nulla
        facilisi.
        Etiam venenatis molestie tellus. Quisque consectetur non risus eu rutrum. </p>
    </div>

 </div>
        </div>

Transactional Modal

<!-- 
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<button class="bx--btn bx--btn--primary" type="button" data-modal-target="#modal-xw5udjp8ltl">Show
  modal</button>

<div data-modal id="modal-xw5udjp8ltl" class="bx--modal " role="dialog"
  aria-modal="true" aria-labelledby="modal-xw5udjp8ltl-label" aria-describedby="modal-xw5udjp8ltl-heading" tabindex="-1">
  <div class="bx--modal-container">
    <div class="bx--modal-header">
      <p class="bx--modal-header__label bx--type-delta" id="modal-xw5udjp8ltl-label">Optional label</p>
      <p class="bx--modal-header__heading bx--type-beta" id="modal-xw5udjp8ltl-heading">Modal heading</p>
      <button class="bx--modal-close" type="button" data-modal-close aria-label="close modal" >
          <svg class="bx--modal-close__icon" width="10" height="10" viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
            <title>Close Modal</title>
            <path d="M6.32 5L10 8.68 8.68 10 5 6.32 1.32 10 0 8.68 3.68 5 0 1.32 1.32 0 5 3.68 8.68 0 10 1.32 6.32 5z" fill-rule="nonzero"
            />
          </svg>
      </button>
    </div>

    <div class="bx--modal-content">
      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id accumsan augue. Phasellus consequat augue
        vitae
        tellus tincidunt posuere. Curabitur justo urna, consectetur vel elit iaculis, ultrices condimentum risus. Nulla
        facilisi.
        Etiam venenatis molestie tellus. Quisque consectetur non risus eu rutrum. </p>
    </div>

    <div class="bx--modal-footer">
      <button class="bx--btn bx--btn--secondary" type="button" data-modal-close>Secondary button</button>
      <button class="bx--btn bx--btn--primary" type="button"   data-modal-primary-focus>Primary button</button> </div>  </div>
        </div>

Danger Modal

<!-- 
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<button class="bx--btn bx--btn--danger--primary" type="button" data-modal-target="#modal-w18bajy9l7o">Show
  modal</button>

<div data-modal id="modal-w18bajy9l7o" class="bx--modal bx--modal--danger" role="dialog"
  aria-modal="true" aria-labelledby="modal-w18bajy9l7o-label" aria-describedby="modal-w18bajy9l7o-heading" tabindex="-1">
  <div class="bx--modal-container">
    <div class="bx--modal-header">
      <p class="bx--modal-header__label bx--type-delta" id="modal-w18bajy9l7o-label">Optional label</p>
      <p class="bx--modal-header__heading bx--type-beta" id="modal-w18bajy9l7o-heading">Modal heading</p>
      <button class="bx--modal-close" type="button" data-modal-close aria-label="close modal" >
          <svg class="bx--modal-close__icon" width="10" height="10" viewBox="0 0 10 10" xmlns="http://www.w3.org/2000/svg">
            <title>Close Modal</title>
            <path d="M6.32 5L10 8.68 8.68 10 5 6.32 1.32 10 0 8.68 3.68 5 0 1.32 1.32 0 5 3.68 8.68 0 10 1.32 6.32 5z" fill-rule="nonzero"
            />
          </svg>
      </button>
    </div>

    <div class="bx--modal-content">
      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id accumsan augue. Phasellus consequat augue
        vitae
        tellus tincidunt posuere. Curabitur justo urna, consectetur vel elit iaculis, ultrices condimentum risus. Nulla
        facilisi.
        Etiam venenatis molestie tellus. Quisque consectetur non risus eu rutrum. </p>
    </div>

    <div class="bx--modal-footer">
      <button class="bx--btn bx--btn--tertiary" type="button" data-modal-close>Secondary button</button>
      <button class="bx--btn bx--btn--danger--primary" type="button"  aria-label="Danger"
          data-modal-primary-focus>Primary button</button> </div>  </div>
        </div>

Documentation

SCSS

Modifiers

Use these modifiers with .bx--modal class.

Name Description
.bx--modal--danger Selector for applying danger modal styles

JavaScript

Getting component class reference

ES2015
import { Modal } from 'carbon-components';
With pre-build bundle (carbon-components.min.js)
var Modal = CarbonComponents.Modal;

Instantiating

For one with a trigger button (a <button> with data-modal-target attribute)
Modal.init();
For one without a trigger button
// `#my-modal` is an element with `[data-modal]` attribute
Modal.create(document.getElementById('my-modal'));

Public methods

Name Params Description
release Deletes the instance
show Show the modal
hide Hide the modal
Example - Showing modal
// `#my-modal` is an element with `[data-modal]` attribute
var modalInstance = Modal.create(document.getElementById('my-modal'));
modalInstance.show();

Options

Option Default selector Description
selectorInit '[data-modal]' The css selector for root modal component
selectorModalClose '[data-modal-close]' The selector to find elements that close the modal
selectorPrimaryFocus '[data-modal-primary-focus]' The CSS selector to determine the element to put focus when modal gets open
classVisible 'is-visible' Class to toggle visibility of modal
attribInitTarget 'data-modal-target' The attribute on the launching element to target the modal
initEventNames '['click']' On specified events, if event matches the attribInitTarget, then initialize the component and run createdByLauncher if method exists
Example - Putting focus on text box when modal gets open
<div
  data-modal
  id="my-modal"
  class="bx--modal "
  role="dialog"
  aria-modal="true"
  aria-labelledby="my-modal-label"
  aria-describedby="my-modal-heading"
  tabindex="-1"
>
  <div class="bx--modal-container">
    <div class="bx--modal-header">
      <p class="bx--modal-header__heading bx--type-beta" id="my-modal-heading">Modal heading</p>
      <button class="bx--modal-close" type="button" data-modal-close aria-label="close modal">(The close button image)</button>
    </div>
    <div class="bx--modal-content">
      <label for="my-text-input" class="bx--label">Text Input label</label>
      <input
        id="my-text-input"
        type="text"
        class="bx--text-input"
        placeholder="Optional placeholder text"
        data-modal-primary-focus
      />
    </div>
  </div>
</div>

Events

Event option Event name
eventBeforeShown 'modal-beingshown'
eventAfterShown 'modal-shown'
eventBeforeHidden 'modal-beinghidden'
eventAfterHidden 'modal-hidden'
Example - Preventing modals from being closed in a certain condition
document.addEventListener('modal-beinghidden', function(evt) {
  if (myApplication.shouldModalKeptOpen(evt.target)) {
    evt.preventDefault();
  }
});
Example - Notifying events of all modals being closed to an analytics library
document.addEventListener('modal-hidden', function(evt) {
  myAnalyticsLibrary.send({
    action: 'Modal hidden',
    id: evt.target.id,
  });
});

FAQ

How do I point multiple elements to the same modal?

To trigger the same modal, you need to add the data-modal-target attribute to a element, and then point it to the same id. For example

<button class="bx--btn bx-btn--primary" type="button" data-modal-target="#modal">A button</button>
<button class="bx--btn bx-btn--secondary" type="button" data-modal-target="#modal">Another button</button>

Both these buttons would trigger the modal with the id of modal.