Skip to main content
Figuration v3 Preview Available!
Widgets

Bring interactivity to your site with a selection of jQuery widgets (plugins) all built with accessibility and usability in mind.

Modal modal.js

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

Overlapping modals not supported

Be sure not to open a modal while another is still visible. Showing more than one modal at a time requires custom code.

Always try to place a modal’s HTML code in a top-level position in your document, such as a direct chld of the <body> element, to avoid other components affecting the modal’s appearance and/or functionality. Placing it within a position: fixed; element may adversely affect placement.

Mobile Device Caveats

There are some caveats regarding using modals on mobile devices. See our browser support docs for details.

Embedding YouTube Videos

Embedding YouTube videos in modals requires additional JavaScript not in Figuration to automatically stop playback and more. See this helpful Stack Overflow post for more information.

Contents

Examples

Static Example

<div class="modal">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header">
                <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
                <h4 class="modal-title">Modal title</h4>
            </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><!-- /.modal-content -->
    </div><!-- /.modal-dialog -->
</div><!-- /.modal -->

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-toggle="#modalLive">
    Launch demo modal
</button>

<!-- Modal -->
<div class="modal" id="modalLive">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header">
                <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
                <h4 class="modal-title">Modal title</h4>
            </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 in Modals

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.

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

<!-- Modal -->
<div class="modal" id="modalLive">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header">
                <button type="button" class="close" data-cfw-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
                <h4 class="modal-title">Modal title</h4>
            </div>
            <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">.col-md-4</div>
                        <div class="col-md-4">.col-md-4</div>
                    </div>
                    ...
                </div>
            </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>

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-toggle="#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-toggle="#modalSm">Small modal</button>

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

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

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

<button type="button" data-cfw="modal" data-cfw-modal-toggle="#foo">Launch modal</button>

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.

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
toggle string null Either the selector (jQuery style), or the string related to the target tooltip having a `data-cfw-modal-target` attribute.
animate boolean true If modal targets should fade and slide in.
speed number| object backdrop:150, modal:300

Speed of animations for fading backdrop and sliding the modal dialog (ms).

If a number is supplied, speed is applied to both fade/slide. These numbers need to correspsond to the CSS animation settings.

Object structure is: `speed: { backdrop: 150, modal: 300 }`
unlink boolean false If the `unlink` method should be called when the modal is hidden. This leaves the modal behind in the DOM.
destroy boolean false If the `destroy` 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 seperate the modal from the page content.

keyboard boolean true Closes the modal when escape key is pressed
show boolean false Shows the modal when initialized.

Methods

.CFW_Modal(options)

Activates a modal dialog. Accepts an optional options object.

$('#myModal').CFW_Modal({
    animate: false
});

.CFW_Modal('toggle')

Toggles a modal dialog to be shown or hidden.

.CFW_Modal('show')

Shows a modal dialog.

.CFW_Modal('hide')

Hides a modal dialog.

Hides the modal, removes events and attributes from both trigger and modal.

.CFW_Modal('destroy')

Calls the unlink method, and then removes the modal from the DOM.

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.
destroy.cfw.modal This event is fired immediately before the modal item is removed from the DOM.

$('#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('destroy');
  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

Key Commands

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

  • Esc - Close the modal

Enforced Focus

In order to keep assistive technology users from interacting with the rest of the page when a modal is open, the focus is automatically forced back to the modal when a user tries to navigate out.

When navigating forward, out the bottom of the modal, focus will be moved to the top of the modal.

When navigation backward, out the top of the modal, focus will be moved back to the top of the modal.

If for some reason you need to disable the enforced focus for modals, you can override the enforceFocus() method.

// This needs to be loaded after Figuration's JavaScript
// PLEASE DO NOT DO THIS!!! - Just here for reference
$.fn.CFW_Modal.Constructor.prototype.enforceFocus = function() {};
// SERIOUSLY DO NOT DO THIS!!!

However, we do not advise disabling it completely, but overriding the function to handle the focus conditionally.

// This needs to be loaded after Figuration's JavaScript
$.fn.CFW_Modal.Constructor.prototype.enforceFocus = function() {
    var $selfRef = this;
    $(document)
        .off('focusin.cfw.modal') // guard against infinite focus loop
        .on('focusin.cfw.modal', function(e) {
            if (document !== e.target && $selfRef.$targetElm[0] !== e.target && !$selfRef.$targetElm.has(e.target).length)
                // Add conditions here
                // In this case items with a 'focusuable-item' class
                && !$(e.target.parentNode).hasClass('focusuable-item') {
                    $selfRef.$targetElm.trigger('focus');
            }
        });
    }
};