Choosing Between Materialize CSS Modal and a Custom Modal Implementation

Decision at a Glance

Use Materialize CSS’s built‑in modal when you need a ready‑made, accessible dialog with minimal code and can accept the ~15 KB JavaScript payload that comes with the framework. Switch to a custom modal only if you must eliminate the Materialize dependency, require full control over styling and animation, or need a payload under ~5 KB.

Constraints That Shape the Choice

• Responsive layout – the dialog must adapt to mobile and desktop viewports.
• Keyboard navigation – focus must move into the modal on open, trap inside, and return on close.
• ARIA roles – role="dialog", aria-modal="true", and labelledby/describedby attributes are required.
• Page‑load impact – keep added JavaScript and CSS as small as possible.

Feature Comparison

Feature	Materialize Built‑in Modal	Custom Modal (Vanilla JS)
File size (JS only)	~15 KB (minified, part of materialize.min.js)	<5 KB (single ES module)
Dependencies	Materialize CSS + JS (jQuery not required since v1.0)	None (plain ES6)
ARIA & focus trap	Built‑in, automatically applied on init	Manual implementation required
CSS transitions	Pre‑defined slide‑up/fade, customizable via Sass variables	Author‑defined (CSS keyframes or transition)
Theming effort	Low – override Sass variables or CSS classes	High – write all styles from scratch
Browser support	Same as Materialize (IE11+ with polyfills)	Modern browsers; polyfill for Element.closest if needed

Trade‑offs Explained

Built‑in Modal

Pros: immediate accessibility compliance, focus management, and animated backdrop with a single initialization call. Cons: you ship the entire Materialize runtime even if the modal is the only component used; theming is limited to the framework’s design language.

Custom Modal

Pros: zero external dependency, full control over markup, animation timing, and styling. Cons: you must implement focus trapping, ESC handling, backdrop click dismissal, and ARIA attributes yourself – a common source of accessibility regressions.

Concrete Implementation – Built‑in Modal

Run the following in a static HTML file served over HTTP/HTTPS (local file:// works for quick tests but blocks ES‑module imports). No special permissions required.

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Materialize Modal Demo</title>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css">
</head>
<body>
  <a class="waves-effect waves-light btn modal-trigger" href="#demo-modal">Open Modal</a>

  <div id="demo-modal" class="modal">
    <div class="modal-content">
      <h4 id="modal-title">Sample Modal</h4>
      <p>This dialog uses Materialize’s built‑in component.</p>
    </div>
    <div class="modal-footer">
      <a href="#" class="modal-close waves-effect waves-green btn-flat">Close</a>
    </div>
  </div>

  <script src="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/js/materialize.min.js"></script>
  <script>
    document.addEventListener('DOMContentLoaded', function () {
      var elems = document.querySelectorAll('.modal');
      var instances = M.Modal.init(elems, {
        // optional: disable backdrop dismissal
        // dismissible: false,
        onOpenStart: function () { console.log('modal opening'); },
        onCloseEnd: function () { console.log('modal closed'); }
      });
    });
  </script>
</body>
</html>

Verification steps (run in browser devtools console):

1. Click Open Modal – focus should land on the first focusable element inside .modal-content.
2. Press Esc – modal closes and focus returns to the trigger button.
3. Click the grey backdrop – modal closes (unless dismissible: false).
4. Inspect the live region: the modal element has role="dialog" and aria-modal="true" automatically added by Materialize.

Risk: If the Materialize CSS or JS fails to load (network error, CSP block), M.Modal is undefined and the trigger becomes a plain link causing a page jump.

Concrete Implementation – Custom Modal (Vanilla ES Module)

Save as modal.js and import from your main script. This example stays under 5 KB gzipped.

// modal.js
export function createModal({ triggerSelector, modalId, title, contentHtml }) {
  const trigger = document.querySelector(triggerSelector);
  if (!trigger) return;

  // Build modal markup
  const modal = document.createElement('div');
  modal.id = modalId;
  modal.className = 'custom-modal';
  modal.setAttribute('role', 'dialog');
  modal.setAttribute('aria-modal', 'true');
  modal.setAttribute('aria-labelledby', `${modalId}-title`);
  modal.hidden = true;
  modal.innerHTML = `
    
    
      
        
${title}
        ×
      
      ${contentHtml}
    
  `;
  document.body.appendChild(modal);

  const overlay = modal.querySelector('.custom-modal-overlay');
  const closeBtn = modal.querySelector('.custom-modal-close');
  let lastFocused = null;

  function open() {
    lastFocused = document.activeElement;
    modal.hidden = false;
    // Force reflow for CSS transition
    requestAnimationFrame(() => modal.classList.add('is-open'));
    trapFocus(modal);
    closeBtn.focus();
    document.addEventListener('keydown', onKeyDown);
  }

  function close() {
    modal.classList.remove('is-open');
    modal.addEventListener('transitionend', function onEnd() {
      modal.hidden = true;
      modal.removeEventListener('transitionend', onEnd);
    }, { once: true });
    document.removeEventListener('keydown', onKeyDown);
    if (lastFocused) lastFocused.focus();
  }

  function onKeyDown(e) {
    if (e.key === 'Escape') close();
    if (e.key === 'Tab') trapFocus(e);
  }

  function trapFocus(e) {
    const focusable = modal.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
    const first = focusable[0];
    const last = focusable[focusable.length - 1];
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault(); last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault(); first.focus();
    }
  }

  trigger.addEventListener('click', (e) => { e.preventDefault(); open(); });
  closeBtn.addEventListener('click', close);
  overlay.addEventListener('click', close);
}

CSS (include in your stylesheet):

.custom-modal { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; z-index: 1000; }
.custom-modal[hidden] { display: none; }
.custom-modal-overlay { position: absolute; inset: 0; background: rgba(0,0,0,.5); opacity: 0; transition: opacity .2s; }
.custom-modal-dialog { position: relative; background: #fff; max-width: 600px; width: 90%; max-height: 80vh; overflow: auto; transform: scale(.9); opacity: 0; transition: transform .2s, opacity .2s; }
.custom-modal.is-open .custom-modal-overlay { opacity: 1; }
.custom-modal.is-open .custom-modal-dialog { transform: scale(1); opacity: 1; }
.custom-modal-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem; border-bottom: 1px solid #eee; }
.custom-modal-close { background: none; border: none; font-size: 1.5rem; cursor: pointer; }
.custom-modal-body { padding: 1rem; }

Usage in your main script:

import { createModal } from './modal.js';

createModal({
  triggerSelector: '#open-custom',
  modalId: 'custom-demo',
  title: 'Custom Modal',
  contentHtml: '
Built without Materialize.
'
});

Verification steps (same as built‑in):

1. Activate trigger – focus moves to close button.
2. Tab cycles within modal only.
3. Esc closes, focus returns to trigger.
4. Backdrop click closes.
5. Run axe-core or Lighthouse accessibility audit – expect zero dialog‑related violations.

Limitations: No built‑in animation configuration; you must edit CSS keyframes for different effects. Focus trap implementation is minimal – complex forms with nested modals may need a more robust library (e.g., focus-trap).

Practical Checklist Before Shipping

• ✅ Verify both modals pass axe-core dialog rules.
• ✅ Measure added bundle size (webpack/rollup --analyze).
• ✅ Test on iOS Safari, Chrome Android, Firefox, Edge – confirm focus restoration.
• ✅ Ensure CSP allows inline scripts if you embed the init code directly.

Rollback Note

Switching from built‑in to custom modal (or vice‑versa) only changes client‑side assets. No server‑side state is modified, so a simple redeploy of the updated HTML/JS bundle is sufficient. If you used Materialize’s Sass variables for theming, remember to remove the now‑unused @import 'materialize' to avoid dead code.