Modalbox is completely free of charge but donations are highly appreciated. Your donations will help me to keep it going. Thanks!

What is ModalBox?

ModalBox is a JavaScript library for creating modal dialogs or wizards (sequences of dialogs) without using conventional popups and page reloads. It's inspired by Mac OS X modal dialogs. It may also be useful for showing bigger versions of images.

ModalBox is built with JavaScript and is dependent from Prototype JavaScript Framework, and valid XHTML/CSS. ModalBox uses AJAX to load content.

ModalBox is still in development. Please submit your bugs here:

Sources of inspiration

Basically, ModalBox is based on GrayBox technique by Amir Salihefendic. But you can find a lot of similar techniques around the web: Lightbox JS, Lightbox gone wild, ThickBox etc.

There also a clone of ModalBox, the MOOdalBox, written on great and lightweight Mootools Framework.


ModalBox Screenshot

ModalBox on Google.Code

Found a bug or have something to say? Just check ModalBox project on Google.Code:

There is also a Modalbox Google Group exist, there you might find a solution or ask for the help. You may also use this email to post to this group:


Modalbox reference as well as an additional documentation can be found on Modalbox Google Code page.

ModalBox Features

  • Web 2.0-ready. ModalBox uses industry-standard libraries — prototype and
  • NEW! “Offline-mode”. Use dynamic- or plain-HTML without any Ajax-calls to fill out your dialog windows.
  • AJAX pages loading. ModalBox uses AJAX instead of deprecated iframe for content loading. It's also more secure — you can't access pages which are not on your host.
  • Callbacks support. You can attach your own JavaScript events after showing or hiding (and more) the ModalBox
  • NEW! Automatic height adjustment. ModalBox adjust it's height depending on your content. No more height tweaking!
  • NEW! “Scrolling mode”. If your content might be long just define the height of the ModalBox and it will be switched into “scrolling mode”
  • Browser and platform independent. Since most of modern browsers use popup blockers, it's hard to find another way to create 100% browser-compatible modal dialogs.
  • Multi-purpose. You can create complex wizards to guide users through the process. Image slideshows can be done too.
  • Keystrokes support. Use ESC key to close ModalBox.
  • Customizable Look & Feel. Use CSS to make ModalBox look like you want.
  • Supports transitional effects. Slide down appearing and on-the-fly resizing.
  • Lightweight. Just about 10 KB of code.
  • Works in most modern browsers. Tested in IE6, IE7, Firefox 1.0, 1.5, 2.0, Safari, Camino, Opera 8 and 9.


  1. Download latest version from GitHub and put to your /includes directory (you also need a prototype + files there. Included to ModalBox package.)
  2. Include the following JavaScript files in your pages:
    <script type="text/javascript" src="includes/prototype.js"></script>
    <script type="text/javascript" src="includes/scriptaculous.js?¬
    <script type="text/javascript" src="includes/modalbox.js"></script>
  3. Include the CSS file modalbox.css in your pages:
    <link rel="stylesheet" href="includes/modalbox.css" type="text/css"
    media="screen" />


Showing ModalBox

To invoke ModalBox all you need to do is call; code on event.

For example, let's create a link with href and title attibutes filled. We will use them as parameters in our example:

<a href="frame_send-link.html" title="Simple form" onclick=", {title: this.title, width: 600}); return false;
"> Send link to a friend</a>

Start Demo

From the version 1.5.4 you also may use “Offline-mode” to show modal dialogs without Ajax-requests and use instead pure HTML. Modalbox supports:

  • plain HTML
  • DOM nodes
  • HTML JavaScript objects

You can find more info and demos on each method below

Plain HTML

Let's say you're about to show some kind of short confirmation dialog. Something like “Are you sure to delete this item?” Obviously, it's too much to use a separated HTML page and an additional Ajax request to do that. ModalBox is the solution:'<div class=\'warning\'><p>Are you sure to delete this¬
item?</p> <input type=\'button\' value=\'Yes, delete!\'¬
onclick=\'Modalbox.hide()\' /> or <input type=\'button\'
value=\'No, leave it!\' onclick=\'Modalbox.hide()\' /></div>',¬
{title: this.title, width: 300});

See it in action

DOM Node

Now, let's say you already have a DOM node in your HTML document which could be referenced via ID or className attributes. Let's improve the above technique.

Here's how our existing DOM node looks like:

Are you sure to delete this item?


This block has an ID="domexample". We'll use it to show in ModalBox. Here's the code:$('domexample'), {title: this.title, width: 300});

See it in action

Notice, all attributes were copied into the new DOM node which was then used to show as ModalBox contents.

HTML JavaScript objects

The most advanced usage could be a JavaScript object containing HTML code. Let's use Builder for our example.

<script type="text/javascript" charset="utf-8">
var node = new Element('div', {className: 'warning', style: 'border: 1px solid #0F0; display:none'}).update(
new Element('p').update('Are you sure to delete this item?')
new Element('input', {type: 'button', value: 'Yes, delete it!', id: 'deleteBut'})
new Element('span').update(' or ')
new Element('input', {type: 'button', value: 'No, leave it', id: 'cancelBut'})
var hideObserver = Modalbox.hide.bindAsEventListener(Modalbox);
function setObservers() {
	$('deleteBut').observe('click', hideObserver);
	$('cancelBut').observe('click', hideObserver);
function removeObservers() {
	$('deleteBut').stopObserving('click', hideObserver);
	$('cancelBut').stopObserving('click', hideObserver);

<a href="#" class="demo-btn" title="JavaScript Object demo"
onclick=", {title: this.title, width: 300,
afterLoad: setObservers, onHide: removeObservers }); return false;">Link</a>

See it in action

Resize methods: resizeToContent and resizeToInclude

In version 1.6.0 there are two useful methods for resizing Modalbox height were added. They might be useful to adjust the height of the Modalbox window in case of manipulating dialog's contents via javascript such as field validation etc.

Here’s the example:

<p id="errmsg" style="display: none">Some message</p>

<input type="text" size="30" id="email" name="email" onfocus="
if($('errmsg').visible()) {
}" />
<button type="button" onclick="
Modalbox.resizeToInclude('errmsg', {afterResize: function(){
	new Effect.Appear('errmsg');

resizeToInclude(element [, options]) method allows you to increase Modalbox height by given element's height. element might be an ID of an element or even DOM element reference.

resizeToContent([options]) method adjust Modalbox height to fit actual content. For example, you did some modifications on the loaded content via javascript (removed some node) and you want Modalbox to reduce the height to the new content height value. Calling this method will do the trick.

See it in action (click on “Validate” button and then place cursor into the email field)

Wizards creation

To create a simple process (as shown in the Examples) you need to call; again from your ModalBox window:

<button type="button" onclick="'frame_send-link-done.html',¬
{width: 460, title: 'Sending status'}); return false;">¬
Send link</button>

Hiding ModalBox

To hide a ModalBox window with a custom link inside it, use the following:

<a href="#" title="Close window" onclick="Modalbox.hide();¬
return false;">Close</a>

Disabling Interactions

If you want to disable all interactions with ModalBox during the process (for example, during file uploading), use deactivate and activate methods. Since deactivated, ModalBox will not respond to ESC key and “Close” button will disappear. If you don't want ModalBox to fade out in inactive state, set inactiveFade parameter to false.

See it in action