README.md

PicoModal

A small, self-contained JavaScript modal library. Plain, vanilla JS.

• Small: At around 2kb minified & gzipped, it's small and easily embeddable
• No Dependencies: PicoModal does not depend on any other JS libraries, so you can use it in places where you don't have access to one
• Self-contained: No extra CSS or images required; just the JS
• Simple: The interface is straight forward and easy to use
• Customizable: By changing a few settings you can customize or completely replace the default styles and behaviour
• Accessible: Handles focus management, keyboard events and Aria tags

Download

The latest version of PicoModal is available here: Download

Browser Support

Basic Example

If all you want to do is display a modal, it's as easy as this: (Run this code)

  picoModal("Ah, the pitter patter of tiny feet in huge combat boots.").show();

If you plan on showing the same modal multiple times, make sure you keep a reference to the instance, like this: (Run this code)

  var modal = picoModal("Ah, the pitter patter of tiny feet in huge combat boots.");
  document.getElementById("modal").addEventListener("click", function(){
      modal.show();
  });

For more control over the behaviour of the modal, you can pass in a settings object: (Run this code)

  picoModal({
      content: "Ah, the pitter patter of tiny feet in huge combat boots.",
      overlayStyles: {
          backgroundColor: "#169",
          opacity: 0.75
      }
  }).show();

A full list of settings is documented below.

Manually Closing a Modal

If you want to programatically close the modal you can do it like this: (Run this code)

  var modal = picoModal(
      "<p>Ah, the pitter patter of tiny feet in huge combat boots.<p>"
      + "<p><a href='#' class='dismiss'>Dismiss</a></p>"
  ).show();

  document.body.addEventListener('click', function(event) {
    if( /\bdismiss\b/.test(event.target.className) ) {
      modal.close();
    }
  });

Or you can use a more targetted implementation with the afterCreate event: (Run this code)

  picoModal(
      "<p>Ah, the pitter patter of tiny feet in huge combat boots.<p>"
      + "<p><a href='#' class='dismiss'>Dismiss</a></p>"
  ).afterCreate(function(modal){
      modal.modalElem().getElementsByClassName("dismiss")[0]
          .addEventListener('click', modal.close);
  }).show();

You can also attach an event to fire when the modal is closed: (Run this code)

  picoModal("Ah, the pitter patter of tiny feet in huge combat boots.")
      .afterClose(function () { alert("Closed"); })
      .show();

Customizing Behavior

To disable the close button, and instead just rely on someone clicking outside of the modal, you can do this: (Run this code)

  picoModal({
      content: "Ah, the pitter patter of tiny feet in huge combat boots.",
      closeButton: false
  }).show();

Or, to disable closing when someone clicks outside of the modal, you can do this: (Run this code)

  picoModal({
      content: "Ah, the pitter patter of tiny feet in huge combat boots.",
      overlayClose: false
  }).show();

To use custom HTML for the close button, do this: (Run this code)

  picoModal({
      content: "Ah, the pitter patter of tiny feet in huge combat boots.",
      closeHtml: "<span>Close</span>",
      closeStyles: {
          position: "absolute", top: "-10px", right: "-10px",
          background: "#eee", padding: "5px 10px", cursor: "pointer",
          borderRadius: "5px", border: "1px solid #ccc"
      }
  }).show();

Events

There are a few events you can hook into for watching and sometimes monitoring the behavior of a modal. The events are:

• afterCreate: Triggered when the DOM Nodes for a modal are created
• beforeShow: Triggered before a modal is shown. Allows for cancellation
• afterShow: Triggered after a modal is shown
• beforeClose: Triggered before a modal is closed. Allows for cancellation
• afterClose: triggered after a modal is closed

These exist as methods on the PicoModal instance. You can use them like this: (Run this code)

  picoModal("Ah, the pitter patter of tiny feet in huge combat boots.")
      .afterClose(function (modal) {
          alert("Modal Closed: " + modal.modalElem().innerText);
      })
      .show();

The first argument passed to the callback is the PicoModal instance for the specific modal.

For two of the events, beforeShow and beforeClose, there is a second argument passed that lets you cancel the behavior in question. For example: (Run this code)

  picoModal("Ah, the pitter patter of tiny feet in huge combat boots.")
      .beforeShow(function (modal, event) {
          if ( !confirm("Are you sure you want to open this modal?") ) {
              event.preventDefault();
          }
      })
      .show();

Single Shot Modal

You can use the afterClose event and the destroy method to create a modal that will clean up after itself when it is closed, like this: (Run this code)

  picoModal("Ah, the pitter patter of tiny feet in huge combat boots.")
      .afterClose(function (modal) { modal.destroy(); })
      .show();

Dialog

There is no built in dialog option, but there are tools to make it easy to implement one yourself. If you think about it, dialogs are really just modals that have some sort of 'result'. To achieve this, add click handlers that send data to the afterClose function indicating the result: (Run this code)

picoModal({
    content: "<p>Ah, the pitter patter of tiny feet in huge combat boots.</p>" +
        "<p class='footer'>" +
        "<button class='cancel'>Cancel</button> " +
        "<button class='ok'>Ok</button>" +
        "</p>"
}).afterCreate(modal => {
    modal.modalElem().addEventListener("click", evt => {
        if (evt.target && evt.target.matches(".ok")) {
            modal.close(true);
        } else if (evt.target && evt.target.matches(".cancel")) {
            modal.close();
        }
    });
}).afterClose((modal, event) => {
    alert(event.detail ? "Ok" : "Cancelled");
}).show();

In the example above, notice the argument passed to modal.close() above, and then accessing it by reading event.detail.

Animation

PicoModal doesn't have any built in animations, but you can use the event system to add some of your own. For example, the following snippet adds a fade in and out using jQuery: (Run this code)

  picoModal({
      content: "Ah, the pitter patter of tiny feet in huge combat boots.",
      overlayStyles: function ( styles ) { styles.opacity = 0; },
      modalStyles: function ( styles ) { styles.opacity = 0; }
  })
  .afterShow(function(modal){
      $(modal.overlayElem()).animate({opacity: .5});
      $(modal.modalElem()).animate({opacity: 1});
  })
  .beforeClose(function(modal, event) {
      event.preventDefault();
      $(modal.overlayElem()).add(modal.modalElem())
          .animate(
              { opacity: 0 },
              { complete: modal.forceClose }
          );
  })
  .show();

Settings

The following settings are available when creating a modal:

• content: The data to display to the user
• width: The forced width of the modal
• closeButton: Boolean whether to display the close button
• closeHtml: Custom HTML content for the close button
• closeStyles: A hash of CSS properties to apply to the close button
• closeClass: A class to attach to the close button
• overlayClose: Boolean whether a click on the shadow should close the modal
• overlayStyles: A hash of additional CSS properties to apply to the overlay behind the modal
• overlayClass: A class to attach to the overlay element
• modalStyles: A hash of additional CSS properties to apply to the modal element
• modalClass: A class to attach to the main modal element
• modalId: The ID to assign to the modal element. A default ID is generated used if none is provided.
• parent: By default, the modal dialog elements are attached to document.body. This options allows you to select an alternative parent element by specifying a node or a selector
• escCloses: When false, disables pressing the escape key to close this modal. This defaults to true.
• focus: Whether to automatically set focus on the first focusable element within this modal when it opens. This defaults to true.
• ariaDescribedBy: The id of the element that contains the main content of this modal. This sets the [aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute) attribute. This defaults to the ID of the modal if none is provided.
• ariaLabelledBy: The id of the element that contains the general label for this modal. This sets the [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute) attributed. It is left blank if none is provided.
• bodyOverflow: Whether to set overflow: hidden on the body when the modal is displayed. This prevents the main page from scrolling when a modal is open

If a method is passed as an argument for any of the settings, it will be called. The first argument passed in is the default value for that setting. This makes it easy to modify the defaults instead of having to totally define your own, like so: (Run this code)

  picoModal({
      content: "Ah, the pitter patter of tiny feet in huge combat boots.",
      overlayStyles: function (styles) {
          styles.opacity = 0.1;
          return styles;
      }
  }).show();

Modal Instance API

The following methods are available on the object returned by picoModal:

• modalElem: Returns the modal DOM Node
• closeElem: Returns the close button DOM Node
• overlayElem: Returns the overlay DOM Node
• show: Displays the modal
• buildDom: Builds the DOM for the modal, but without showing it
• close: Hides the modal
• forceClose: Hides the modal without calling the beforeClose events
• destroy: Detaches all DOM Nodes and unhooks this modal
• isVisible: Whether this modal is currently being displayed
• options: Updates the options for this modal. This will only let you change options that are re-evaluted regularly, such as overlayClose.
• afterCreate: Registers a callback to invoke when the modal is created
• beforeShow: Registers a callback to invoke before the modal is shown
• afterShow: Registers a callback to invoke when the modal is shown
• beforeClose: Registers a callback to invoke before the modal is closed
• afterClose: Registers a callback to invoke when the modal is closed

License

PicoModal is released under the MIT License, which is pretty spiffy. You should have received a copy of the MIT License along with this program. If not, see http://www.opensource.org/licenses/mit-license.php