Accessible jQuery Modal Plugin with Focus Trapping and CSS3 Animations

jquery-modal.js is a lightweight jQuery plugin that creates accessible, customizable modal windows with smooth animations powered by CSS3.

The plugin handles ARIA attributes, keyboard navigation, and focus management automatically while enabling you to control size, animations, and close behaviors through data attributes or JavaScript options.

Features:

• Accessibility: The plugin automatically manages aria-modal, aria-hidden, and role="dialog" attributes.
• Focus Management: It traps focus within the modal while open and returns focus to the trigger button upon closing.
• Keyboard Support: You can close the modal with the ESC key and navigate content using the Tab key.
• Responsive Design: The modal adapts to various screen sizes using flexible CSS.
• Customization: You can control dimensions and behavior via HTML data attributes or JavaScript options.
• Animation: It uses CSS transitions for smooth fade-in and scale effects.

Use Cases:

• Legacy System Updates: You need to add modern, accessible modals to an older application that already depends on jQuery.
• Form Submissions: You want to display a login or contact form in an overlay without navigating away from the current page.
• Alerts and Confirmations: You require a custom-styled alternative to the browser's native alert() or confirm() dialogs.
• Media Lightboxes: You need to display images or videos in a focused view when a user clicks a thumbnail.

How To Use It:

1. Include the jQuery library and the plugin script on your webpage.

<!-- jQuery Modal CSS -->
<link rel="stylesheet" href="/path/to/jquery-modal.css"/>

<!-- Scripts -->
<script src="/path/to/cdn/jquery.min.js"></script>
<script src="/path/to/jquery-modal.js"></script>

2. Set up the HTML. The plugin requires three elements: a modal overlay, the modal container with content, and a trigger button. The data-modal-target attribute on the modal must match the data-modal-trigger value on the button:

<!-- Overlay that darkens the background -->
<div class="modal-overlay" id="modalOverlay" aria-hidden="true"></div>

<!-- Modal container positioned with flexbox centering -->
<div class="modal-outer">
  <div data-modal-target="myModal" class="modal" role="dialog" 
       aria-labelledby="modal-title" aria-modal="true">
    <button class="modal-close" aria-label="Modal Close">&times;</button>
    <h2 id="modal-title">Modal Title</h2>
    <p>Modal content goes here</p>
  </div>
</div>

<!-- Trigger button -->
<button class="modal-trigger" data-modal-trigger="myModal">
  Open Modal
</button>

3. The plugin automatically detects buttons with the .modal-trigger class. You do not need to write extra JavaScript.

<!-- Default 300x200 modal -->
<button class="modal-trigger" data-modal-trigger="modal1">
  Open Modal
</button>

<!-- Custom dimensions -->
<button class="modal-trigger" 
  data-modal-trigger="modal2"
  data-modal-width="600"
  data-modal-height="500">
  Open Large Modal
</button>

4. You can also initialize modals programmatically using the jQuery plugin interface:

// Basic initialization
$('#myButton').modal();

// With configuration options
$('#myButton').modal({
  width: 500,
  height: 400,
  closeOnOverlay: true,
  closeOnEsc: true,
  animationDuration: 300
});

5. The plugin binds these event handlers when a modal opens:

• Click Events: The close button and overlay (if closeOnOverlay is true) both trigger close() on click.
• ESC Key: When closeOnEsc is true, document-level keydown listener closes the modal on keyCode 27.
• Focus Trap: Tab and Shift+Tab are intercepted within the modal. Focus cycles between the first and last focusable elements (buttons, inputs, links with visible href, and elements with tabindex 0).
• Focus Restoration: The plugin stores document.activeElement before opening and restores focus to that element after closing.

FAQs:

Q: Can I open multiple modals simultaneously or stack them?
A: The plugin calls closeAll() before opening any modal, so only one modal displays at a time. You could modify the open() method to remove this line if you need modal stacking, but you'd also need to adjust z-index values and manage multiple overlay instances manually.

Q: The focus trap isn't working with dynamically added form fields. How do I fix this?
A: The trapFocus method queries focusable elements only once when binding events. If you add inputs after the modal opens, you need to manually call modal.bindEvents() again or store a reference to the modal instance and update the focusable elements list. A better approach is to render all form fields before opening the modal, even if some are hidden with CSS.

Q: How do I change the animation speed or use a different animation style?
A: Modify the transition properties in the CSS for .modal and .modal-overlay. The animationDuration option controls the JavaScript timeout that waits before hiding elements, so update both the CSS transition duration and the JavaScript option to match. For different animations, replace transform: scale(0.7) with your preferred starting state like translateY(-50px) for a slide-down effect.

Q: Does this work with server-side rendered modals that don't exist on initial page load?
A: Yes, because the plugin uses jQuery's delegated event binding on the document level with $(document).on('click', '.modal-trigger', ...). This handles dynamically added trigger buttons automatically. The modal content must exist in the DOM when the trigger is clicked, but you can insert it via AJAX and the plugin will find it using the data-modal-target selector.

Related Resources:

• 10 Best Modal Components In JavaScript & Pure CSS

 

---

This awesome jQuery plugin is developed by SiHyung-Lee. For more Advanced Usages, please check the demo page or visit the official website.