‹‹ homejQuery BlockUI Plugin (v2)

Overview

This documentation is for the 2.X versions of the plugin. If you need documentation for the old 1.X versions, you can find it here. This version of BlockUI requires jQuery v1.2.3 or later!

17-JAN-09: New options: fadeIn, timeout and showOverlay
New function: $.growlUI (see the Demos tab for more info)

The jQuery BlockUI Plugin lets you simulate synchronous behavior when using AJAX, without locking the browser[1]. When activated, it will prevent user activity with the page (or part of the page) until it is deactivated. BlockUI adds elements to the DOM to give it both the appearance and behavior of blocking user interaction.

Usage is very simple; to block user activity for the page:

$.blockUI();
Blocking with a custom message:
$.blockUI({ message: '<h1><img src="busy.gif" /> Just a moment...</h1>' });
Blocking with custom style:
$.blockUI({ css: { backgroundColor: '#f00', color: '#fff'} });
To unblock the page:
$.unblockUI();
If you want to use the default settings and have the UI blocked for all ajax requests, it's as easy as this:
$().ajaxStart($.blockUI).ajaxStop($.unblockUI);

Page Blocking Examples

This page demonstrates several ways to block the page. Each button below activates blockUI and then makes a remote call to the server.

The following code is used on this page:

<script type="text/javascript">

    // unblock when ajax activity stops
    $().ajaxStop($.unblockUI);

    function test() {
        $.ajax({ url: 'wait.php', cache: false });
    }

    $(document).ready(function() {
        $('#pageDemo1').click(function() {
            $.blockUI();
            test();
        });
        $('#pageDemo2').click(function() {
            $.blockUI({ message: '<h1><img src="busy.gif" /> Just a moment...</h1>' });
            test();
        });
        $('#pageDemo3').click(function() {
            $.blockUI({ css: { backgroundColor: '#f00', color: '#fff' } });
            test();
        });

        $('#pageDemo4').click(function() {
            $.blockUI({ message: $('#domMessage') });
            test();
        });
    });

</script>

...

<div id="domMessage" style="display:none;">
    <h1>We are processing your request.  Please be patient.</h1>
</div>

Element Blocking Examples

This page demonstrates how to block selected elements on the page rather than the entire page. The buttons below will block/unblock access to the bordered area beneath them.

Test link - click me!

lorem ipsum dolor sit amet consectetuer adipiscing elit sed lorem leo lorem leo consectetuer adipiscing elit sed lorem leo rhoncus sit amet lorem ipsum dolor sit amet consectetuer adipiscing elit sed lorem leo Test link - click me! lorem leo consectetuer adipiscing elit sed lorem leo rhoncus sit amet

This text will not be blocked. Test link - click me!

The following code is used on this page:

<script type="text/javascript">
    $(document).ready(function() {

        $('#blockButton').click(function() {
            $('div.test').block({ message: null });
        });

        $('#blockButton2').click(function() {
            $('div.test').block({
                message: '<h1>Processing</h1>',
                css: { border: '3px solid #a00' }
            });
        });

        $('#unblockButton').click(function() {
            $('div.test').unblock();
        });

        $('a.test').click(function() {
            alert('link clicked');
            return false;
        });
    });
</script>

Simple Modal Dialog Example

This page demonstrates how to display a simple modal dialog. The button below will invoke blockUI with a custom message. Depending upon the user response (yes or no) an ajax call will be made while keeping the UI blocked.

The following code is used on this page:

<script type="text/javascript">
    $(document).ready(function() {

        $('#test').click(function() {
            $.blockUI({ message: $('#question'), css: { width: '275px' } });
        });

        $('#yes').click(function() {
            // update the block message
            $.blockUI({ message: "<h1>Remote call in progress...</h1>" });

            $.ajax({
                url: 'wait.php',
                cache: false,
                complete: function() {
                    // unblock when remote call returns
                    $.unblockUI();
                }
            });
        });

        $('#no').click(function() {
            $.unblockUI();
            return false;
        });

    });
</script>

...

<input id="test" type="submit" value="Show Dialog" />

...

<div id="question" style="display:none; cursor: default">
        <h1>Would you like to contine?.</h1>
        <input type="button" id="yes" value="Yes" />
        <input type="button" id="no" value="No" />
</div>
For full-featured modal dialog support, check out the jqModal Plugin by Brice Burgess.

Demos

Most of the demos below will display for 2 seconds

Login Form
$(document).ready(function() {
    $('#demo1').click(function() {
        $.blockUI({ message: $('#loginForm') });

        setTimeout($.unblockUI, 2000);
    });
});
        
iPhoto (ish)
$(document).ready(function() {
    $('#demo2').click(function() {
        $.blockUI({ css: {
            border: 'none',
            padding: '15px',
            backgroundColor: '#000',
            '-webkit-border-radius': '10px',
            '-moz-border-radius': '10px',
            opacity: '.5',
            color: '#fff'
        } });

        setTimeout($.unblockUI, 2000);
    });
});
        
Blue Overlay
$(document).ready(function() {
    $('#demo3').click(function() {
        $.blockUI({ overlayCSS: { backgroundColor: '#00f' } });

        setTimeout($.unblockUI, 2000);
    });
});
        
Tall Content
$(document).ready(function() {
    $('#demo4').click(function() {
        $.blockUI({
            message: $('#tallContent'),
            css: { top: '20%' }
        });

        setTimeout($.unblockUI, 2000);
    });
});
        
Image Box
$(document).ready(function() {
    $('#demo5').click(function() {
        $.blockUI({
            message: $('img#displayBox'),
            css: {
                top:  ($(window).height() - 500) /2 + 'px',
                left: ($(window).width() - 500) /2 + 'px',
                width: '500px'
            }
        });

        setTimeout($.unblockUI, 2000);
    });
});
        
Non-centered message
$(document).ready(function() {
    $('#demo6').click(function() {
        $.blockUI({
            centerY: 0,
            css: { top: '10px', left: '', right: '10px' }
        });

        setTimeout($.unblockUI, 2000);
    });
});
        
Blocking without a message
(pass null as message)
$(document).ready(function() {
    $('#demo7').click(function() {
        $.blockUI({ message: null });

        setTimeout($.unblockUI, 2000);
    });
});
        
onUnblock callback
(useful when using fadeOut option
as it is invoked when all
the blocking elements have been removed)
$(document).ready(function() {
    $('#demo8').click(function() {
        $.blockUI();

        setTimeout(function() {
            $.unblockUI({
                onUnblock: function(){ alert('onUnblock'); }
            });
        }, 2000);
    });
});
        
Click overlay to unblock
(This demo will not automatically unblock, you must click the overlay.)
$(document).ready(function() {
    $('#demo9').click(function() {
        $.blockUI();
        $('.blockOverlay').attr('title','Click to unblock').click($.unblockUI);
    });
});
        
Auto-Unblock
Sets a timer to unblock after a specified timeout.
$(document).ready(function() {
    $('#demo10').click(function() {
        $.blockUI({
			message: '<h1>Auto-Unblock!</h1>',
			timeout: 3000
		});
	});
});
        
Growl (the hard way)
$(document).ready(function() {
    $('#demo11').click(function() {
        $.blockUI({
			message: $('div.growlUI'),
			fadeIn: 700,
			fadeOut: 700,
			timeout: 3000,
			showOverlay: false,
            centerY: false,
			css: {
				width: '350px',
				top: '10px',
				left: '',
				right: '10px',
			    border: 'none',
			    padding: '5px',
			    backgroundColor: '#000',
			    '-webkit-border-radius': '10px',
			    '-moz-border-radius': '10px',
			    opacity: '.6',
			    color: '#fff'
			}
        });
    });
});
        
Growl (the easy way)
$(document).ready(function() {
   $('#demo12').click(function() {
       $.growlUI('Growl Notification', 'Have a nice day!');
   });
});
       

The two growl examples above also make use of the following external CSS:

div.growlUI { background: url(check48.png) no-repeat 10px 10px }
div.growlUI h1, div.growlUI h2 {
	color: white; padding: 5px 5px 5px 75px; text-align: left
}
	

Note: For a more full-featured "growl" implementation, check out the excellent jGrowl plugin by Stan Lemon.

Options

BlockUI's default options look (exactly) like this:
// override these in your code to change the default behavior and style
$.blockUI.defaults = {
    // message displayed when blocking (use null for no message)
    message:  '<h1>Please wait...</h1>',

    // styles for the message when blocking; if you wish to disable
    // these and use an external stylesheet then do this in your code:
    // $.blockUI.defaults.css = {};
    css: {
        padding:        0,
        margin:         0,
        width:          '30%',
        top:            '40%',
        left:           '35%',
        textAlign:      'center',
        color:          '#000',
        border:         '3px solid #aaa',
        backgroundColor:'#fff',
        cursor:         'wait'
    },

    // styles for the overlay
    overlayCSS:  {
        backgroundColor:'#000',
        opacity:        '0.6'
    },

	// styles applied when using $.growlUI
	growlCSS: {
		width:    '350px',
		top:      '10px',
		left:     '',
		right:    '10px',
	    border:   'none',
	    padding:  '5px',
	    opacity:  '0.6',
	    color:    '#fff',
	    backgroundColor: '#000',
	    '-webkit-border-radius': '10px',
	    '-moz-border-radius':    '10px'
	},

    // z-index for the blocking overlay
    baseZ: 1000,

    // set these to true to have the message automatically centered
    centerX: true, // <-- only effects element blocking (page block controlled via css above)
    centerY: true,

    // allow body element to be stetched in ie6; this makes blocking look better
    // on "short" pages.  disable if you wish to prevent changes to the body height
    allowBodyStretch: true,

    // be default blockUI will supress tab navigation from leaving blocking content;
    constrainTabKey: true,

    // fadeIn time in millis; set to 0 to disable fadeIn on block
    fadeIn:  200,

    // fadeOut time in millis; set to 0 to disable fadeOut on unblock
    fadeOut:  400,

	// time in millis to wait before auto-unblocking; set to 0 to disable auto-unblock
	timeout: 0,

	// disable if you don't want to show the overlay
	showOverlay: true,

    // if true, focus will be placed in the first available input field when
    // page blocking
    focusInput: true,

    // suppresses the use of overlay styles on FF/Linux (due to performance issues with opacity)
    applyPlatformOpacityRules: true,

    // callback method invoked when unblocking has completed; the callback is
    // passed the element that has been unblocked (which is the window object for page
    // blocks) and the options that were passed to the unblock call:
    //     onUnblock(element, options)
    onUnblock: null,

    // don't ask; if you really must know: http://groups.google.com/group/jquery-en/browse_thread/thread/36640a8730503595/2f6a79a77a78e493#2f6a79a77a78e493
    quirksmodeOffsetHack: 4
};
Changing the blockUI options is simple and can be done in one of two ways:
  1. Globally, by directly overriding the values in the $.blockUI.defaults object
  2. Locally, by passing an options object to the blockUI (or block) function.

Global Overrides

You can change the default options by simply declaring different values for them. For example:
// change message border
$.blockUI.defaults.css.border = '5px solid red';

// make fadeOut effect shorter
$.blockUI.defaults.fadeOut = 200;

Local Overrides

Local overrides are achieved by passing an object to the blockUI, unblockUI, block or unblock functions. The exact same options are available to the local options object as are available in the global object. For example:
// change message border
$.blockUI({ css: { border = '5px solid red'} });

...

// make fadeOut effect shorter
$.unblockUI({ fadeOut: 200 });

...

// use a different message
$.blockUI({ message: 'Hold on!' });

...

// use a different message
$('#myDiv').block({ message: 'Processing...' });

Frequently Asked Questions

What version of jQuery does the BlockUI plugin require?
BlockUI is compatible with jQuery v1.2.3 and later.
What has changed in version 2 of the BlockUI plugin?
  • Elements are no longer removed from the DOM when unblocking
  • The default overlay color is now black instead of white
  • The available options have been consolidated and sanitized
  • The way in which options are passed to the plugin has changed
  • Support for Opera 8 has been dropped
  • The internals have been restructured for improved readability
  • displayBox functionality removed (other plugins do this better)
Is my code that used the old blockUI plugin compatible with the new 2.0x version?
No, not if that code was passing options to blockUI. The manner in which options are passed has changed slightly. See the Options page for details on how to pass options in the new version.
Does the BlockUI Plugin have any dependencies on other plugins?
No.
How do I use an external stylesheet to style the blocking message?
See this demo page.
How do I use an external stylesheet to style the blocking overlay?
See this demo page.
Can I change the default message text used when blocking the page?
Yes. The default message is stored in $.blockUI.defaults.message. You can change it simply by assigning a new value, like this:
$.blockUI.defaults.message = "Please be patient...";
Can I change the color or transparency of the overlay?
Yes. The default overlay CSS is stored in $.blockUI.defaults.overlayCSS. You can choose a different default overlay color and transparency value like this:
// use yellow overlay
$.blockUI.defaults.overlayCSS.backgroundColor = '#ff0';

// make overlay more transparent
$.blockUI.defaults.overlayCSS.opacity = '.2';
Does BlockUI support Opera 8?
No.
Why don't I see overlays in FF on Linux?
Several people informed me that full page opacity rendering in FF/Linux is crazy slow, so by default it's disabled for that platform. You can enable it by overriding the applyPlatformOpacityRules property like this:
// enable transparent overlay on FF/Linux
$.blockUI.defaults.applyPlatformOpacityRules = false;
I don't want the message content to be centered. How do override the default position?
See this demo page.

Download

blockUI is available for download right here: jquery.blockUI.js.

It is also available from the project's github repository: http://github.com/malsup/blockui/.

The last version in the 1.x line, v1.33, is still available here: jquery.blockUI.1.33.js.
The old 1.x docs can be found here.

Support

Support for the BlockUI Plugin is available through the jQuery Google Group.

Change Log

changes.txt