Explicitly Initializing MaterializeCSS v1.x Modals and Sidenavs: A Practical Guide

Why You Must Explicitly Initialize Components

In MaterializeCSS v1.x the interactive widgets—modals, sidenavs, dropdowns, tooltips, and the like—are pure JavaScript components. Adding the required class and data-* attributes to the markup is not enough; the framework must be told to bind the JavaScript logic to the DOM nodes. If you skip this step the widgets will render as plain HTML and remain static.

Desired Outcome

After following this guide you will:

• Know how to initialize modals and sidenavs once the DOM is ready.
• Be able to verify that the instances exist and are functional.
• Understand how to recover from common initialization failures.

Prerequisites

1. Include the MaterializeCSS v1.x CSS and JavaScript bundles in your page. The order matters: materialize.min.css first, then materialize.min.js.
   • Example:

     <link href="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css" rel="stylesheet"/>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/js/materialize.min.js">

2. Ensure the page has a <body> element that contains at least one modal and one sidenav.
   • Example markup for a modal:

     <div id="demoModal" class="modal">
       <div class="modal-content">
         <p>Hello, world!</p>
       </div>
       <div class="modal-footer">
         <a href="#" class="modal-close waves-effect waves-green btn-flat">Close</a>
       </div>
     </div>
     

   • Example markup for a sidenav:

     <ul id="demoSidenav" class="sidenav">
       <li><a href="#!">First Item</a></li>
       <li><a href="#!">Second Item</a></li>
     </ul>
     

3. Optionally, add a trigger button that toggles the modal or sidenav. For a modal:

   <a class="waves-effect waves-light btn modal-trigger" href="#demoModal">Open Modal</a>
   

   For a sidenav:

   <a href="#" data-target="demoSidenav" class="sidenav-trigger">
     <i class="material-icons">menu</i>
   </a>
   

4. Use a modern browser that supports ES6 modules and DOMContentLoaded events.

Focused Procedure

Step 1 – Wait for the DOM to be ready

Wrap your initialization code in a DOMContentLoaded listener or place it at the bottom of the <body> so that the elements exist when you call the API.

document.addEventListener('DOMContentLoaded', function() {
  // Initialization code goes here
});

Step 2 – Initialize each component individually

Using the M global object, call the component’s init method. The method returns an instance that you can later use to control the component.

const modalEl = document.querySelector('#demoModal');
const modalInstance = M.Modal.init(modalEl, {
  dismissible: true,          // Allows closing by clicking outside
  startingTop: '4%',           // Starting position when opened
  opacity: 0.5                // Backdrop opacity
});

const sidenavEl = document.querySelector('#demoSidenav');
const sidenavInstance = M.Sidenav.init(sidenavEl, {
  edge: 'left',                // 'left' or 'right'
  draggable: true
});

Note the camelCase option names; they differ from the 0.x jQuery style.

Step 3 – Verify the instances exist

After initialization you can retrieve the instance again to confirm it is not null and has the expected methods.

const modalCheck = M.Modal.getInstance(modalEl);
console.log('Modal instance:', modalCheck);
// Expected output: an object with open(), close(), destroy() methods

Step 4 – Test interaction

Open the modal programmatically to see that it appears.

modalInstance.open();

Click the backdrop or press Esc to ensure the modal dismisses when dismissible is true.

Expected Checks and Relevant Recovery Options

• Check 1 – M is defined: Open DevTools console and type M. If it returns undefined, the MaterializeJS file was not loaded or ran before the script tag.
  • Recovery: Verify the <script> tag order and that the URL is reachable. Place the script tag just before </body> or after the <link> tag.
• Check 2 – Element exists before init: If modalEl is null, the selector did not match any element.
  • Recovery: Ensure the modal markup is present in the DOM when the script runs. For dynamically inserted content, call M.Modal.init after the element is appended.
• Check 3 – Duplicate initialization: Re‑calling M.Modal.init on an already initialized element can throw an error or create duplicate event listeners.
  • Recovery: Retrieve the existing instance with M.Modal.getInstance and call destroy() before re‑initializing, or simply skip re‑initialization if the instance exists.
• Check 4 – Dynamic content: M.AutoInit() only runs once at the time you call it and will miss elements that are added later.
  • Recovery: After inserting new markup, call M.AutoInit() again or manually initialize the new elements with M.Modal.init or M.Sidenav.init.
• Check 5 – Version mismatch: If you copy sample code from a 0.x tutorial, the API names and options will differ.
  • Recovery: Verify the loaded MaterializeCSS version by inspecting the materialize.min.js file or checking M.version in the console. Adjust the API calls accordingly.

Concrete Example: A Minimal Working Page

Below is a full HTML snippet that you can copy into a file and open in a browser. It demonstrates the modal and sidenav with proper initialization and verification.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Materialize Init Demo</title>
  <link href="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css" rel="stylesheet"/>
</head>
<body>
  <nav>
    <a href="#" data-target="demoSidenav" class="sidenav-trigger">
      <i class="material-icons">menu</i>
    </a>
    <ul id="demoSidenav" class="sidenav">
      <li><a href="#!">Home</a></li>
      <li><a href="#!">About</a></li>
    </ul>
  </nav>

  <div class="container">
    <h1>Materialize Init Demo</h1>
    <a class="waves-effect waves-light btn modal-trigger" href="#demoModal">Open Modal</a>
  </div>

  <div id="demoModal" class="modal">
    <div class="modal-content">
      <p>This modal was initialized with vanilla JS.</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">

Recovery Checklist

• Open DevTools console and ensure M is defined.
• Confirm modalInstance and sidenavInstance appear in the console without errors.
• Click the menu icon to open the sidenav and the button to open the modal.
• If nothing happens, look for JavaScript errors: missing script, wrong selector, or duplicate initialization.

Conclusion

MaterializeCSS v1.x’s shift to a vanilla‑JS API means you must explicitly call M.Modal.init and M.Sidenav.init (or M.AutoInit() for a one‑shot approach). By following the steps above you guarantee that interactive widgets are bound to the DOM, that you can verify their existence, and that you have a clear path to recover from common pitfalls.