CAST Figuration®

Modal modal.js

The Modal widget allows you to add dialog style windows to your site or application.

Page Contents

Important Notes

  • Modals get positioned over everything else in the document and remove scroll from the <body> so that modal content scrolls instead.
  • By default, clicking on the modal "backdrop" will automatically close the modal.
  • Figuration only supports one modal at a time. Nested modals are not supported, as this can cause difficult usability and accessibility issues.
  • Modals use position: fixed. Always try to place modal HTML code in a top-level position in your document, such as a direct chld of the <body> element. Putting modal HTML within a fixed position element will adversely affect placement.
  • There are some caveats regarding using modals on mobile devices. See our browser support docs for details.
  • Embedding YouTube videos in modals requires additional JavaScript, not included in Figuration, to automatically stop playback and more. See this helpful Stack Overflow post for more information.
  • The autofocus HTML attribute has no effect in modals. To achieve the same effect you will need some custom JavaScript:
$('#myModal').on('afterShow.cfw.modal', function() {
  $('#myInput').trigger('focus');
});

Examples

Below is a static modal example (meaning its position and display have been overridden). Included are the modal header, modal body (required for padding), and modal footer (optional). It is highly suggested to include modal headers with dismiss actions whenever possible, or provide another explicit dismiss action.

Modal title

Modal body content…

<div class="modal">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h4 class="modal-title">Modal title</h4>
        <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
      </div>
      <div class="modal-body">
        <p>Modal body content&hellip;</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

In the above static example, we use <h4>, to avoid issues with the heading hierarchy in the documentation page. Structurally, however, a modal dialog represents its own separate document/context, so the .modal-title should ideally be a <h1>. If necessary, you can use the font size utilities to control the heading's appearance. All the following live examples use this approach.

Live Demo

Toggle a modal via JavaScript by clicking the button below. It will slide down and fade in from the top of the page. Examples of tooltips, popover, and scroll handling included.

<!-- Button trigger -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalLive">
  Launch demo modal
</button>

<!-- Modal -->
<div class="modal" id="modalLive">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h1 class="modal-title fs-2xlarge">Modal title</h1>
        <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Scrolling Long Content

When modals become too long for the user's viewport or device, they scroll independent of the page itself. Try the demo below for an example.

<!-- Button trigger -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalScroll">
  Scrolling modal
</button>

<!-- Modal -->
<div class="modal" id="modalScroll">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h1 class="modal-title fs-2xlarge">Modal title</h1>
        <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Scrollable Body

Add .modal-dialog-scrollable to .modal-dialog where the .modal-body is the scrollable region, and the entire modal fits within the viewport height.

<!-- Button trigger -->
<button type="button" class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalScrollBody">
  Scrollable modal body
</button>

<!-- Modal -->
<div class="modal" id="modalScrollBody">
  <div class="modal-dialog modal-dialog-scrollable">
    <div class="modal-content">
      <div class="modal-header">
        <h1 class="modal-title fs-2xlarge">Modal title</h1>
        <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Vertically Centered

Add .modal-dialog-centered to .modal-dialog to vertically center the modal.

<!-- Button trigger -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalCenter">
  Centered modal
</button>

<!-- Modal -->
<div class="modal" id="modalCenter">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h1 class="modal-title fs-2xlarge">Modal title</h1>
        <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

A vertically centered dialog will also scroll when the content is longer than the viewport.

<!-- Button trigger -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalCenterScroll">
  Scrolling centered modal
</button>

<!-- Modal -->
<div class="modal" id="modalCenterScroll">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      <div class="modal-header">
        <h1 class="modal-title fs-2xlarge">Modal title</h1>
        <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

You can also combine .modal-dialog-centered with .modal-dialog-scrollable to keep the modal within the viewport height.

<!-- Button trigger -->
<button type="button" class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalCenterBody">
  Centered, scrolling modal body
</button>

<!-- Modal -->
<div class="modal" id="modalCenterBody">
  <div class="modal-dialog modal-dialog-centered modal-dialog-scrollable">
    <div class="modal-content">
      <div class="modal-header">
        <h1 class="modal-title fs-2xlarge">Modal title</h1>
        <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
      </div>
      <div class="modal-body">
        ...
      </div>
      <div class="modal-footer">
        <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div>
  </div>
</div>

Grid Usage

To take advantage of the grid system within a modal, just nest .container-fluid within the .modal-body and then use the normal grid system classes within this container.

<div class="modal-body">
  <div class="container-fluid">
    <div class="row">
      <div class="col-md-4">.col-md-4</div>
      <div class="col-md-4 offset-md-4">.col-md-4 .offset-md-4</div>
    </div>
    <div class="row">
      <div class="col-md-3 offset-md-3">.col-md-3 .offset-md-3</div>
      <div class="col-md-2 offset-md-4">.col-md-2 .offset-md-4</div>
    </div>
    <div class="row">
      <div class="col-md-6 offset-md-3">.col-md-6 .offset-md-3</div>
    </div>
    <div class="row">
      <div class="col-sm-9">
        Level 1: .col-sm-9
        <div class="row">
          <div class="col-8 col-sm-6">
            Level 2: .col-8 .col-sm-6
          </div>
          <div class="col-4 col-sm-6">
            Level 2: .col-4 .col-sm-6
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

Tooltips and Popovers

Tooltips and popovers can be placed within modal as needed. When modals are closed, any tooltips or popovers within are also automatically dismissed.

<div class="modal-body">
  <h2 class="fs-xlarge">Popover in a modal</h2>
  <p>This <button type="button" class="btn" title="Popover title" data-cfw="popover" data-cfw-popover-content="Popover body content is set in this attribute." data-cfw-popover-placement="forward">button</button> triggers a popover on click.</p>
  <hr>
  <h5>Tooltips in a modal</h5>
  <p><a href="#" title="Tooltip" data-cfw="tooltip">This link</a> and <a href="#" title="Tooltip" data-cfw="tooltip">that link</a> have tooltips on hover.</p>
</div>

Optional Sizes

Modals have two optional sizes, provided by Figuration's base CSS, available via modifier classes to be placed on a .modal-dialog.

<!-- Large modal -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalLg">Large modal</button>

<div class="modal" id="modalLg">
  <div class="modal-dialog modal-lg">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

<!-- Small modal -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalSm">Small modal</button>

<div class="modal" id="modalSm">
  <div class="modal-dialog modal-sm">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

Static Backdrop

When backdrop option is set to static, the modal will not close when clicking outside it. Click the button below to try it.

<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-backdrop="static" data-cfw-modal-target="#modalStaticBackdrop">Static backdrop modal</button>

<div class="modal" id="modalStaticBackdrop">
  <div class="modal-dialog modal-dialog-side-end modal-dialog-scrollable modal-sm">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

Side Aligned

Position a modal to the side of the page with a .modal-dialog-side-start or .modal-dialog-side-end modifier class placed on a the .modal-dialog. Side aligned modals can be used with .modal-dialog-scrollable, and can also use the sizing classes.

<!-- Start side modal -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalSideStart">Start side modal</button>

<div class="modal" id="modalSideStart">
  <div class="modal-dialog modal-dialog-side-start">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

<!-- End side modal -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalSideEnd">End side modal</button>

<div class="modal" id="modalSideEnd">
  <div class="modal-dialog modal-dialog-side-end modal-dialog-scrollable modal-sm">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

Position a modal to the top or bottom of the page with a .modal-dialog-side-top or .modal-dialog-side-bottom modifier class placed on a the .modal-dialog.

Top and bottom modals require the use of .modal-dialog-scrollable to keep their content within the defined area. The bottom-aligned modal will trigger a flash of scrollbar within the .modal container when sliding into view; this can be mitigated by adding the .overflow-hidden class to the .modal container.

<!-- Top side modal -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalSideTop">Top side modal</button>

<div class="modal" id="modalSideTop">
  <div class="modal-dialog modal-dialog-side-top modal-dialog-scrollable">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

<!-- Bottom side modal -->
<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalSideBottom">End side modal</button>

<div class="modal overflow-hidden" id="modalSideBottom">
  <div class="modal-dialog modal-dialog-side-start modal-dialog-scrollable">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

Fullscreen Modal

Enlarge a modal to fill the entire viewport with a .modal-fullscreen modifider class placed on the .modal-dialog.

<button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalFullscreen">Fullscreen modal</button>

<div class="modal" id="modalFullscreen">
  <div class="modal-dialog modal-fullscreen">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

Responsive variants are also available. These work for a given breakpoint and below with the form .modal-fullscreen-{breakpoint}-down.

Heads up! There is no .modal-fullscreen-*-down class created for the largest breakpoint since it is functionally equivalent to using .modal-fullscreen.

<!-- Fullscreen modal at `xs` breakpoint -->
<div class="modal-dialog modal-fullscreen-xs-down">
  ...
</div>

<!-- Fullscreen modal at `sm` breakpoint and below -->
<div class="modal-dialog modal-fullscreen-sm-down">
  ...
</div>

<!-- Fullscreen modal at `md` breakpoint and below -->
<div class="modal-dialog modal-fullscreen-md-down">
  ...
</div>

<!-- Fullscreen modal at `lg` breakpoint and below -->
<div class="modal-dialog modal-fullscreen-lg-down">
  ...
</div>

You can also combine fullscreen variants with the centered and scrollable variants. The fullscreen version of the modal will then assume a similar scrolling behavior to match, but centering will not occur since the modal will be stretched to the size of the viewport.

<!-- Fullscreen modals at `md` breakpoint and below -->

<!-- Scrollable body above `md` breakpoint -->
<div class="modal-dialog modal-fullscreen-md-down modal-dialog-scrollable">
  ...
</div>

<!-- Centered above `md` breakpoint -->
<div class="modal-dialog modal-fullscreen-md-down modal-dialog-centered">
  ...
</div>

<!-- Centered and scrollable body above `md` breakpoint -->
<div class="modal-dialog modal-fullscreen-md-down modal-dialog-centered modal-dialog-scrollable">
  ...
</div>

Chained Modals

While not necessarily recommended, it is possible to chain singular modals together into a workflow with the following options:

  • using a data-cfw-modal-chain="#destinationModal"attribute on a control within the initiating modal.
  • the provided chain JavaScript method: $('#startingModal').CFW_Modal('chain', '#destinationModal');.

Notes:

  • Multiple modals should not be open at the same time—this method only allows for chaining modals together.
  • Closing a chained modal does not automatically return to the originating modal.
<button type="button" class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalChained1">Chained modal example</button>

<!-- Initial modal -->
<div class="modal" id="modalChained1">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      ...
      <div class="modal-footer">
        <!-- Open the secondary modal -->
        <button class="btn btn-primary" data-cfw="modal" data-cfw-modal-target="#modalChained2" data-cfw-modal-chain="#modalChained2">Open second chained modal</button>
      </div>
    </div>
  </div>
</div>

<!-- Secondary modal -->
<div class="modal" id="modalChained2">
  <div class="modal-dialog modal-dialog-centered">
    <div class="modal-content">
      ...
      <div class="modal-footer">
        <!-- Close secondary modal and return to initial modal -->
        <button type="button" class="btn btn-primary" onclick="$('#modalChained2').CFW_Modal('chain', '#modalChained1');">Open First chained modal</button>
      </div>
    </div>
  </div>
</div>

Contained Modals

Contained modals will display the backdrop and modal within a specified element and not cover the entire page.

Place the modal HTML within the container, apply position: relative; to the container, and specify the rootElement option on the trigger button to limit the modal to the container.

It may also be useful to add a z-index to the container, this will keep the modal from appearing above other items that exist outside the container, such as a navbar. In the example below a z-index: 1; has been added to the #modalRootElement container so that the contained modal, and backdrop, do not overlap the site header when the page is scrolled.

While most modal positioning options are supported, the fullscreen variants should not be used within a container.

Note: Contained modals do not work well within Internet Explorer and are not supported. Issues could include multiple scrollbars or having to scroll within the container to locate the modal. Since IE is a low usage browser at this point effort has not been made to fix these issues specific to IE, and will most likely not be attempted in the future.

<!-- Modal will appear within this element, and not the document body -->
<div id="modalRootElement" class="position-relative border" style="height: 300px; z-index: 1;">
  <!-- Modal -->
  <div id="modalContained" class="modal">
    <div class="modal-dialog">
      <div class="modal-content">
        <div class="modal-header">
          <h1 class="modal-title fs-2xlarge">Contained modal title</h1>
          <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
        </div>
        <div class="modal-body">
          <p>Modal body content&hellip;</p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
          <button type="button" class="btn btn-primary">Save changes</button>
        </div>
      </div>
    </div>
  </div>

  <div id="modalContainedSide" class="modal">
    <div class="modal-dialog modal-dialog-scrollable modal-dialog-side-start modal-sm">
      <div class="modal-content">
        <div class="modal-header">
          <h1 class="modal-title fs-2xlarge">Modal title</h1>
          <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
        </div>
        <div class="modal-body">
          <h2 class="fs-xlarge">Overflowing text to show scroll behavior</h2>
          <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
          <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
          <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
          <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
          <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
          <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
          <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
          <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
          <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
          <p>Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.</p>
          <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</p>
          <p>Aenean lacinia bibendum nulla sed consectetur. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Donec sed odio dui. Donec ullamcorper nulla non metus auctor fringilla.</p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn" data-cfw-dismiss="modal">Close</button>
          <button type="button" class="btn btn-primary">Save changes</button>
        </div>
      </div>
    </div>
  </div>
</div>

<button type="button" class="btn btn-primary mt-1" data-cfw="modal" data-cfw-modal-target="#modalContained" data-cfw-modal-root-element="#modalRootElement">
  Show contained modal
</button>
<button type="button" class="btn btn-primary mt-1" data-cfw="modal" data-cfw-modal-target="#modalContainedSide" data-cfw-modal-root-element="#modalRootElement">
  Show contained, side-aligned modal
</button>

Usage

The modal widget toggles your hidden content on demand, via data attributes or JavaScript. It also adds .modal-open to the <body> to override default scrolling behavior and generates a .modal-backdrop to provide a click area for dismissing shown modals when clicking outside the modal.

Via Data Attributes

Toggle

Activate a modal without writing JavaScript. Set data-cfw="modal" on a controller element, like a button, along with a data-cfw-modal-target="#foo" or href="#foo" to target a specific modal to toggle.

<button type="button" data-cfw="modal" data-cfw-modal-target="#myModal">Launch modal</button>

Dismiss

Dismissal can be achieved with data-cfw-dismiss attributes on a button within the modal as demonstrated below:

<button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>

or on a button outside the modal using the additional data-cfw-modal-target as demonstrated below:

<button type="button" class="close" data-cfw-dismiss="modal" data-cfw-modal-target="#myModal">Close modal</button>

While both ways to dismiss a modal are supported, keep in mind that dismissing from outside a modal does not match ARIA Authoring Practices Guide dialog (modal) pattern. Do this at your own risk.

Via JavaScript

Call a modal with id myModal with a single line of JavaScript:

$('#myModal').CFW_Modal();

Close Triggers

Any an element with a data attribute of data-cfw-dismiss="modal" within the modal element will act as a close trigger for the modal. There can be multiple close triggers, such as a header/titlebar close and a cancel button in the footer.

Alter Animation

In Sass settings, The $modal-transform-fade setting determines the transform state of .modal-dialog before the modal fade-in animation, the $modal-transform-in setting determines the transform of .modal-dialog at the end of the modal fade-in animation.

If you want for example a zoom-in animation, you can set $modal-transform-fade: scale(.75).

Dynamic Heights

If the height of a modal changes while it is open, you will need to call $('#myModal').CFW_Modal('handleUpdate'); to readjust the modal's position and backdrop.

With Positioned Content

Since the scrollbar is removed from the <body> when a modal is shown, there can be some shifting of content in fixed or sticky positioned elements.

The scrollbar handler will attempt to adjust padding values, and margin for sticky elements, to mitigate the content shift. These values will then be reset when the modal dialog is closed.

Some positioning utility classes (.fixed-top, .fixed-bottom, .sticky-top, and .sticky-bottom) are automatically handled. For respsonsive or custom positioned items, there additional .is-fixed and .is-sticky helper classes can be added to an element to trigger the scrollbar handler to adjust for the shift. The scrollbar handler will check the computed style on any item with these classes, and only adjust when neccessary.

Custom positioned elements using translation to modify their position may not be handled correctly, so a custom solution may be needed.

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-cfw-modal-, as in data-cfw-modal-animate=false.

Name Type Default Description
target string null The selector of the target modal.
rootElement string 'body' The selector of the container to display modal within.
animate boolean true If modal targets should fade and slide in.
unlink boolean false If the unlink method should be called when the modal is hidden. This leaves the modal behind in the DOM.
dispose boolean false If the dispose method should be called when the modal is hidden. This will remove the modal from the DOM.
backdrop boolean or the string 'static' true

Includes a modal-backdrop element. Alternatively, specify 'static' for a backdrop which doesn't close the modal on click.

The backdrop is the semi-opaque overlay used to visually separate the modal from the page content.
keyboard boolean true Closes the modal when escape key is pressed.
focus boolean true Enforce focus when using keyboard navigation to remain within the modal dialog.
show boolean false Shows the modal when initialized.
manual boolean false If the modal should be triggered manually through method calls, not from clicking the trigger element. Closing a manual modal will not automatically return focus to the trigger item when the modal is hidden. 
$('#myModal').CFW_Modal({
  animate: false
});

Methods

Method calls can be made on either the trigger or the target <div class="modal"> element.

Method Name Description
toggle Toggles a modal dialog to be shown or hidden.
show Shows a modal dialog.
hide Hides a modal dialog.
unlink Hides the modal, removes events and attributes from both trigger and modal.
dispose Calls the unlink method, and then removes the modal from the DOM.
chain

A helper method for moving from one modal to another.

Called in the form: $('#startingModal').CFW_Modal('chain', '#destinationModal');

Where #startingModal is the id for the currently open .modal container that should be closed, and #destinationModal is the id for the next .modal container to be shown.

 
$('#myModal').CFW_Modal('show');

Events

Event callbacks happen on the target <div class="modal"> element.

Event Type Description
init.cfw.modal This event fires after the modal item is initialized.
beforeShow.cfw.modal This event is fired immediately when the show method is called.
scrollbarSet.cfw.modal This event is fired immediately when the <body> padding is adjusted for the scrollbar width.
afterShow.cfw.modal This event is fired when a modal dialog has been made visible to the user (will wait for CSS transitions to complete).
scrollbarReset.cfw.modal This event is fired immediately when the <body> padding adjustment for the scrollbar is removed.
beforeHide.cfw.modal This event is fired immediately when the hide method is called.
afterHide.cfw.modal This event is fired when a modal dialog has been hidden from the user (will wait for CSS transitions to complete).
beforeUnlink.cfw.modal This event is fired immediately when the unlink method is called. This event can occur after the `beforeHide` event if set to automatically unlink, or before if called via method.
afterUnlink.cfw.modal

This event is fired when a modal item has been unlinked from its trigger item and the data-api removed. This event can occur after the afterHide event when invoked from the unlink method, or before if set to automatically unlink.

This event may need to be listened for using event delegation, since all cfw.modal namespaced events will be detached from the trigger element as part of the unlink process.
dispose.cfw.modal

This event is fired immediately before the modal item is removed from the DOM.

This event may need to be listened for using event delegation, since all cfw.modal namespaced events will be detached from the trigger element as part of the unlink process.

 
$('#myModal').on('afterHide.cfw.modal', function() {
  // do something...
});

Server-side Apps

Modals are designed to hopefully work with server side applications, such as Apache Wicket, and other instances where the server-side application might need to create or update the modal content after the initial page load.

A quick example:

  1. An item with an event handler that makes a callback to create a new modal is interacted with.
  2. Call as needed:
    • $('#myModal').CFW_Modal('hide');
    • or $('#myModal').CFW_Modal('unlink');
    • or $('#myModal').CFW_Modal('dispose');
  3. Update/create the modal object and insert into DOM.
  4. Initialize the modal: $('#myModal').CFW_Modal(options); with desired options.
  5. Show modal: $('#myModal').CFW_Modal('show');

Accessibility

It is recommended that a .modal-title item is used, even if visually hidden, within the modal since it will be automatically be found and linked with an aria-labelledby on the .modal container. This provides a potential description of the modal to screen-reader users when the modal is shown and focus is automatically moved to the .modal container.

Key Commands

The following key commands are handled when focus is inside the modal:

  • Esc - Close the modal
  • Tab - Moves focus to next focusable element inside the dialog. When focus is on the last focusable element in the dialog, moves focus to the first focusable element in the dialog.
  • Shift + Tab - Moves focus to previous focusable element inside the dialog. When focus is on the first focusable element in the dialog, moves focus to the last focusable element in the dialog.

Enforced Focus

Modals employ a 'focus trap' in an attempt to keep focus with the modal dialog when one is open, as specified by the WAI-ARIA recommendations.

If for some reason you need to disable the enforced focus for modals, you can override the behavior by setting the focus option to false.

SASS Reference

Variables

The available Customization options, or Sass variables, that can be customized for the modal component.

Name Type Default Description
$enable-modal boolean true Enable the generation of the modal component classes. Smaller segements of the modal component classes can be disabled with the following $enable-* variables.
$enable-modal-centered boolean true Enable the generation of the vertically centered modal variant.
$enable-modal-scrollable boolean true Enable the generation of the scrollable body modal variant.
$enable-modal-side-start boolean true Enable the generation of the start side aligned modal variant.
$enable-modal-side-end boolean true Enable the generation of the end side aligned modal variant.
$enable-modal-side-top boolean true Enable the generation of the top side aligned modal variant.
$enable-modal-side-bottom boolean true Enable the generation of the bottom side aligned modal variant.
$enable-modal-fullscreen boolean true Enable the generation of the fullscreen modal variant.
$enable-modal-fullscreen-responsive boolean true Enable the generation of the responsive fullscreen modal variants.
$enable-modal-header boolean true Enable the generation of the modal header class.
$enable-modal-title boolean true Enable the generation of the modal title class.
$enable-modal-body boolean true Enable the generation of the modal body class.
$enable-modal-footer boolean true Enable the generation of the modal footer class.
$modal-dialog-margin string .625rem Spacing around modal dialog.
$modal-dialog-bp-up-margin-y string .625rem Vertical spacing for modal dialog starting at the breakpoint defined by $modal-breakpoint.
$modal-content font-size string $font-size-base Font size for modal content container.
$modal-content-bg string $component-bg Background color for modal content container.
$modal-content-color string null Text color for modal content container.
$modal-content-border-color string $component-overlay-border-color Border color for modal content container.
$modal-content-border-width string $border-width Border width for modal content container.
$modal-content-box-shadow string map-get($shadows, "d3") Box shadow for modal content container.
$modal-content-bp-up-box-shadow string map-get($shadows, "d4") Box shadow for modal content container at the breakpoint defined by $modal-breakpoint.
$modal-border-radius string .375rem Border radius for modal content container.
$modal-inner-border-radius string calc(#{$modal-border-radius} - #{$modal-content-border-width}) Border radius for modal header and footer.
$modal-backdrop-bg string $dark Background color for modal backdrop.
$modal-backdrop-opacity string .5 Opacity for modal backdrop.
$modal-header-padding-y string .75rem Vertical padding for modal header.
$modal-header-padding-x string 1rem Horizontal padding for modal header.
$modal-header-color string null Text color for modal header.
$modal-header-background-color string null Background color for modal header.
$modal-header-border-color string rgba($uibase-900, .2) Border color for modal header.
$modal-header-border-width string $modal-content-border-width Border width for modal header.
$modal-title-line-height string $line-height-base Line height for modal header.
$modal-close-padding-y string .75rem Vertical padding for close button in modal header.
$modal-close-padding-x string .75rem Horizontal padding for close button in modal header.
$modal-body-padding-y string .75rem Vertical padding for modal body.
$modal-body-padding-x string 1rem Horizontal padding for modal body.
$modal-footer-padding-y string .75rem Vertical padding for modal footer.
$modal-footer-padding-x string 1rem Horizontal padding for modal footer.
$modal-footer-color string null Text color for modal footer.
$modal-footer-background-color string null Background color for modal footer.
$modal-footer-border-color string $modal-header-border-color Border color for modal footer.
$modal-footer-border-width string $modal-header-border-width Border width for modal footer.
$modal-sm string rem(304px) (19rem) Max width for small modal dialog variant.
$modal-md string rem(528px) (33rem) Max width for modal dialog starting at the breakpoint defined by $modal-breakpoint.
$modal-lg string rem(896px) (56rem) Max width for large modal dialog variant.
$modal-breakpoint string sm When to start scaling up modal width and margins.
$modal-lg-breakpoint string lg The minimum breakpoint to allow .modal-lg.
$modal-side-vertical-height string 33vh Height for top and bottom aligned modals.
$modal-transform-fade string translate(0, -3rem) Transform state of .modal-dialog before the modal fade-in animation
$modal-transform-in string none Transform state of .modal-dialog at the end of the modal fade-in animation.
$modal-transform-side-offset string -5rem Transform state offset of .modal-dialog before the modal fade-in animation for side variant modals.
$modal-transform-blocked string scale(1.01) Transform state of .modal-dialog for when the close is blocked animation.
$modal-transform-fullscreen string none Transform state of .modal-dialog for the slide animation when the modal in fullscreen mode.
$modal-transition string transform .15s linear Transition settings for the .modal-dialog animations.
$modal-fullscreen-breakpoints list map-keys($grid-breakpoints) Breakpoint list for responsive fullscreen modals.

Mixins

Enable fullscreen mode on a .modal-dialog.

@include modal-fullscreen();
Top of Page