search

kylepaulsen / NanoModal

A small, self-contained JavaScript modal library with some extra features.
MIT License
47 stars 5 forks source link

readme

I am no longer maintaining NanoModal. If you want a maintained modal library, try https://github.com/Nycto/PicoModal

NanoModal Build Status

NanoModal is yet another modal / dialog library written in a small amount of pure JavaScript. See it in action!

Features:

I wanted a modal library that was small, easy to use, and worked everywhere - thus NanoModal was born. When I was writing NanoModal, my main goals were: it should be tiny, fully customizable, and it should work on all major browsers (including mobile). Most modal libraries don't work well (or at all) on mobile, especially when users rotate or zoom their device while looking at a modal. I aimed to fix all these problems and make the best modal library I possibly could.

Install

Get the minified, or non-minified source from Github, or install via npm using the following command in your command prompt:

npm install nanomodal

Or Bower:

bower install nanomodal

Usage

Basic usage: (See it in action: Example 1, Example 2)

// example 1:
var justTextModal = nanoModal("Hello World!");
justTextModal.show();

/* example 2:
 * given the html:
 * <!-- hidden modals container -->
 * <div style="display: none;">
 *   <div id="myHiddenFormDiv">
 *     ...
 *   </div>
 * </div>
 */
var elementModal = nanoModal(document.querySelector("#myHiddenFormDiv"));
elementModal.show();

Usage with more options: (See it in action: Example 1, Example 2)

// example 1:
var modalWithNoButtons = nanoModal("Hey this is an important message!", {
    buttons: []
});
modalWithNoButtons.show();

// example 2:
var dialogModal = nanoModal("Are you sure you want to do this?", {
    overlayClose: false, // Can't close the modal by clicking on the overlay.
    buttons: [{
        text: "I'm sure!",
        handler: function(modal) {
            // do something...
            alert("doing something...");
            modal.hide();
        },
        primary: true
    }, {
        text: "Maybe not...",
        handler: "hide"
    }]
});
dialogModal.show();

Full Documentation

nanoModal() Options

var customModal = nanoModal("hey", { /* options */ });

Here are the properties that can go in the options object and what they do:

The NanoModal Object

var modalObj = nanoModal("hi");

All functions ( except for .remove() and .getContent() ) return the API again so you can chain. Here is the API:

Other Properties (You probably wont need to use)

Button Definitions

var modalObj = nanoModal("sup", {buttons: [ /* button definition objects here */ ] });

When defining custom button objects, here are the properties you can set and what they do:

customShow and customHide

nanoModal.customShow = function(defaultShow, modalAPI) {
    defaultShow();
    modalAPI.overlay.el.style.opacity = 0.5;
    modalAPI.modal.el.style.opacity = 1;
};
nanoModal.customHide = function(defaultHide, modalAPI) {
    modalAPI.overlay.el.style.opacity = 0;
    // this is only needed if you have modals that open other modals on the onHide event.
    // modalAPI.modal.onHideEvent.fire();
    modalAPI.modal.el.style.opacity = 0;
    if (document.body.style.transition !== undefined) {
        setTimeout(defaultHide, 500);
    } else {
        defaultHide();
    }
};

The customShow and customHide properties on the main nanoModal var can be used to customize the experience of your modals. When defined, your functions will get passed the defaultShow or defaultHide methods that you must call eventually. Your functions will also be passed the corresponding modalAPI that is responsible for the modal that is being shown or hidden. The above example shows how you can make all modals fade in and out. Keep in mind you will also need some CSS like:

.nanoModal.nanoModalOverride, .nanoModalOverlay.nanoModalOverride {
    opacity: 0;
    transition: opacity 0.5s ease;
}

Making the modal stick to your scroll position

.nanoModal.nanoModalOverride {
    position: fixed;
}

You should test on your target mobile browsers though, as position fixed can do some weird things on mobile. I might add a built in feature for this if people want it (file an issue).

Note: You probably wont need to deal with the stuff below.

El Objects

var modalObj = nanoModal("hello");
var elObject = modalObj.modal;
var elObject2 = modalObj.overlay;

El Objects are just objects that hold an html element with some helper functions on it:

Modal Event Objects

var modalObj = nanoModal("hello");
var modalEventObj = modalObj.modal.onShowEvent;
var modalEventObj2 = modalObj.modal.onHideEvent;

Modal events are just me making a super simple custom event system:

nanoModal.resizeOverlay()

This exists just in case the overlay is not behaving on your screen or mobile device.

License

MIT