The modal component must be initialized on an element that will trigger the display of the modals, for example.

<a href="/categories/add" class="js-modal" id="add-category">Add Category</a>

The value of the getContent option (falls back to href attribute) determines the URL to request for modal content. Once a request completes, the AJAX response will be inserted into the data-modal-content element.

To insert non-AJAX content into a modal, the getContent value can point to an ID in the page, like so #some-id. We can also set the content directly through the modal instance.

$('.js-modal').toolkit('modal', 'show', [$('#add-category'), 'This will be inserted into the modal.']);

Or we can trigger the modal by passing in the node to read from.

$('.js-modal').toolkit('modal', 'show', $('#add-category')); // Loads /categories/add

Dynamic Content Loading

Briefly mentioned above, modals use a form of dynamic content loading. This allows the body of the modal to be loaded dynamically from multiple sources, either from an AJAX request, an element, or a literal value.

Multiple Modals

Displaying multiple modals at the same time is possible, but will require multiple modal instances.


Activating the modal uses event delegation, so placing .js-modal-1 and .js-modal-2 anywhere will open it. This even applies to elements loaded in via AJAX, like within the body of another modal.

Form Submitting

How useful would a modal be if it didn't support forms? Rather useless. Using forms in modals is rather simple, simply place the form tag and a data-modal-submit attribute on the element that should trigger form submission.

<form action="/url/to/post/to" method="post">

    <button type="button" data-modal-submit>Submit</button>

Once submitted, the action and method from the form tag will be used as the URL to submit to. If the AJAX response is HTML, then the response will replace the content in the current modal. If the AJAX response is non-HTML, then continue reading.

File uploading is possible through modal forms if the browser supports the FormData API. This is automatically detected and enabled.
Do not use normal submit buttons within a modal form, use [data-modal-submit] instead.

Non-HTML Responses

If an AJAX request returns a non-HTML response, say JSON or XML, the modal will not be shown. Instead of position() being called on the instance, process() will be called, which will fire the process event.

The process() method can also trigger a callback automatically if the response is JSON. Simply return an index in the JSON response with the key callback and the value the name of the function to call. For example, if the JSON response was.


Then the console.log function will be triggered with the response passed as the 1st argument.


  • The animation option will be appended as a class name.
  • An .is-fullscreen class will be added to the modal when fullScreen is enabled.
  • File uploading is enabled if the browser supports the FormData API.


The dialog role and the appropriate aria-* attributes are required when supporting ARIA. Learn more about this role.

All required ARIA attributes will be automatically added to the component when initialized, which will generate the following markup.

<div class="modal" role="dialog" aria-labelledby="toolkit-modal-1-title" aria-describedby="toolkit-modal-1-content">

The only requirement for fully supporting ARIA is adding the appropriate IDs to the content being inserted into the modal. We would need to add toolkit-modal-#-title and toolkit-modal-#-content, where # represents the modal unique ID.

<div class="modal-head" id="toolkit-modal-1-title">

<div class="modal-body" id="toolkit-modal-1-content">
The JavaScript component will automatically map all ARIA attributes.


Variable Default Description
$modal-animations ("fade", "from-above", "from-below", "slide-in-top", "slide-in-right", "slide-in-bottom", "slide-in-left") A list of all animations to include in the CSS output.
$modal-class .modal CSS class name for the modal wrapper.
$modal-class-outer .modal-outer CSS class name for the outer modal element.
$modal-class-inner .modal-inner CSS class name for the inner modal element.
$modal-class-head .modal-head CSS class name for the modal header element.
$modal-class-body .modal-body CSS class name for the modal body element.
$modal-class-foot .modal-foot CSS class name for the modal footer element.
$modal-mobile-breakpoint 640px The break point to apply mobile widths.
$modal-transition .3s The transition time for all modal animations.
$modal-zindex 610 The z-index for the modal element.


Inherits all options from the parent Component.

Option Type Default Description
animation string fade The animation to use when displaying the modal. Available options are: fade, from-above, from-below, slide-in-top, slide-in-right, slide-in-bottom, slide-in-left.
blackout bool true Whether to display a blackout when a modal is open.
clickout bool true Whether to hide the modal when the blackout is clicked.
fullScreen bool false Whether to resize the modal to fullscreen and cover the viewport.
getContent string|function data-modal If a string is passed, fetch the URL from the HTML attribute. If a string is passed in #id format, fetch the content from the HTML of the element. If a function is passed, use the return value as the URL. If no value is found, will fallback to href attribute for URL. The URL will be requested via AJAX for the content.
stopScroll bool true Whether to remove the scrollbar on the window while the modal is open. Requires html.touch for mobile devices to function properly.
template string <div class="modal">
<div class="modal-outer">
<div class="modal-inner" data-modal-content></div>
<button class="modal-close" data-modal-close><span class="x"></span></button>
The modal markup. The data-modal-* attributes are required.


Inherits all events from the parent Component.

Event Arguments Description
submit element:form Triggered after a form submit has been clicked but before the AJAX request is posted.


Inherits all properties from the parent Component.

Property Type Description
blackout object The Toolkit.Blackout instance when blackout is enabled.
cache object Collection of cached AJAX requests indexed by URL.


Inherits all methods from the parent Component.

Method Description Bound To
hide() Hide the modal. [data-modal-close]
show([element:node[, string:content]]) Display the modal. If a node is passed, extract the URL to request, or the content to use. If the content argument is passed, use that as the content. selector
submit() Submit a form found within the modal using an AJAX call. [data-modal-submit]