PicoModal

A small, self-contained JavaScript modal library

• Small: At less than 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

Download

The latest version of PicoModal is available here: Download

Browser Support

IE9+, Chrome, FireFox and Safari

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();

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
• 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
• modalStyles: A hash of additional CSS properties to apply to the modal element
• modalClass: A class to attach to the main modal element
• overlayClass: A class to attach to the overlay element
• closeClass: A class to attach to the close button

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
• close: Hides the modal
• forceClose: Hides the modal without calling the beforeClose events
• destroy: Detaches all DOM Nodes and unhooks this modal
• 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