Hire our team

Download version 1.6.0

Includes prototype 1.6.0, script.aculo.us 1.8.0 library, unit- and functional tests. See version log

Start Demo

Like ModalBox? Try Beanstalk, our hosted Subversion service.

What is ModalBox?

ModalBox is a JavaScript technique for creating modern (Web 2.0-style) modal dialogs or even wizards (sequences of dialogs) without using conventional popups and page reloads. It’s inspired by Mac OS X modal dialogs. And yes, it may also be useful for showing larger versions of images. :)

ModalBox is built with pure JavaScript and is based on Sam Stephenson’s excellent Prototype JavaScript Framework, script.aculo.us and valid XHTML/CSS. ModalBox uses AJAX to load content.

ModalBox technique is still in development. Please feel free to comment or submit your bugs here: http://code.google.com/p/modalbox/

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 the great and lightweight Mootools Framework.


ModalBox Screenshot

ModalBox Features

  • Web 2.0-ready. ModalBox uses industry-standard libraries — prototype and script.aculo.us.
  • NEW! “Offline-mode”. Use dynamic- or plain-HTML without any Ajax-calls to fill out your dialog windows.
  • AJAX page loading. ModalBox uses AJAX instead of deprecated iframe for content loading. It’s also more secure — you can’t access pages that 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 is long, just define the height of the ModalBox and it will switch into “scrolling mode”
  • Browser and platform independent. Since most 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 created 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.

ModalBox on Google.Code

Found a bug or have something to say? Just check the ModalBox project on Google.Code: http://code.google.com/p/modalbox/

There is also a Modalbox Google Group that exists where you might find a solution or ask for help. You may also use this email to post to this group: modalbox@googlegroups.com


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


  1. Download ModalBox and unpack to your /includes directory (you also need the prototype + script.aculo.us files there, which are included in the 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 Modalbox.show(params); 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="
Modalbox.show(this.href, {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:

Modalbox.show('<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:

Modalbox.show($('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 Script.aculo.us 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="Modalbox.show(node, {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)

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