Small Footprint Modals for Web Projects – Simple Modal

Simple Modal JS is a lightweight, dependency-free JavaScript library that creates customizable modal windows using JavaScript configuration objects.

Features

• Dependency-Free: No jQuery, no other UI frameworks needed.
• JS Configuration: All styling (colors, fonts, sizes) and behavior options are set through a JavaScript object.
• Lightweight: Small footprint, ideal for projects where performance matters.
• Customizable Overlay: Control the visibility and opacity of the modal backdrop.
• Customizable Content: Adjust title and content text, colors, fonts, and weights.
• Simple API: Methods like show(), hide(), removeFromDOM(), and addToDOM() make it easy to control the modal lifecycle.
• Unique IDs: Automatically generates unique IDs for modal instances.

How to use it:

1. Install & import simple-modal-js with NPM.

# NPM
$ npm install simple-modal-js

import SimpleModalJS from 'simple-modal-js';
import './dist/style.css'

2. Or directly load the simple-modal-js library in the document.

<link rel="stylesheet" href="/dist/style.css">
<script src="/dist/main.min.js"></script>

3. Create a new modal instance and define your modal content as follows:

• show: Boolean to control overlay visibility
• opacity: Number between 0-1 for overlay transparency
• text: String containing the title/body text
• textColor: CSS color value
• font: Font family
• weight: Font weight
• size: Font size with CSS units

const modal = new SimpleModalJS({
  overlay: {
    show: true,
    opacity: 0.6
  },
  modal: {
    title: {
      text: 'Modal Title',
      textColor: 'black',
      font: 'Inter',
      weight: 'bold',
      size: '24px',
    },
    content: {
      text: 'Modal Content Here',
      textColor: 'black',
      font: 'Inter',
      weight: 'normal',
      size: '18px',
    }
  }
});

4. Show the modal window when needed.

modal.show();

5. API Methods:

• show(): Displays the modal window.
• hide(): Hides the modal window by adding a CSS class.
• removeFromDOM(): Completely removes the modal window’s elements from the DOM. Useful if you’re done with the modal and want to clean up.
• addToDOM(): Adds the modal window back to the DOM. This is automatically called on instantiation after DOMContentLoaded.

6. Properties:

• modalID: The unique ID of the modal wrapper (e.g., smjs-1).
• $modalWrapper: The main div element that wraps everything, including the overlay.
• $modal_window: The div representing the modal box itself.
• $modal_title: The h2 element for the title.
• $modal_text: The p element for the main content.
• $modal_close: The close button element.

FAQs

Q: Can I use HTML content within the modal body?
A: The modal.content.text configuration property sets textContent, so it will render HTML tags as literal strings. If you need to inject HTML, you’d access the $modal_text DOM element property after creating the modal instance and set its innerHTML directly. For example: myModal.$modal_text.innerHTML = '<strong>Important!</strong><br>Some details.';

Q: How are multiple modals handled on the same page?
A: Each new SimpleModalJS() creates an independent modal instance with a unique ID. They will stack in the order they are shown or added to the DOM. You’ll need to manage which one is currently “active” or how they should interact if you plan to show multiple simultaneously.

Q: How can I customize the modal’s appearance beyond the provided JS options?
A: Since the library uses predictable CSS class names (e.g., simple-modalJS__window, simple-modalJS__title), you can always write your own CSS to override the base styles injected by the library. Make sure your CSS selectors are specific enough or use !important (cautiously!) if needed.

Q: What happens if I call show() on a modal that’s already been removed with removeFromDOM()?
A: The show() method just removes a class. If the element isn’t in the DOM, removing a class won’t make it reappear. You’d need to call addToDOM() first, then show().

Q: Is there a built-in way to handle asynchronous operations before showing/hiding or on close?
A: No, the API is synchronous. If you need to, for example, fetch data before showing a modal, you’d do that in your own code and then call modal.show() in the callback or Promise.then(). Similarly, for actions on close, you could potentially wrap the hide() method or add logic where you invoke hide().