Overview

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( '<h1><img src="busy.gif" /> Just a moment...</h1>' );

Blocking with custom style:

$.blockUI( { 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?' + new Date().getTime() });
    }

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

        // embedded content used as message
        var messageElement = $('#domMessage');

        $('#pageDemo4').click(function() {
            $.blockUI(messageElement);
            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.

The following code is used on this page:

<script type="text/javascript">
    $(function() {
        $('#blockButton').click(function() {
            $('div.test').block();
        });
        $('#blockButton2').click(function() {
            $('div.test').block('<h1>Processing</h1>', { 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 whle keeping the UI blocked.

The following code is used on this page:

<script type="text/javascript">
    $(function() {
        // cache the question element
        var question = $('#question')[0];

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

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

            $.ajax({
                url: 'wait.php?' + new Date().getTime(), // prevent caching in IE
                complete: function() {
                    // unblock when remote call returns
                    $.unblockUI();
                }
            });
            return false;
        });

        $('#no').click($.unblockUI);
    });
</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.

Display Box

Display Box is a (very) poor man's Thickbox. Even that's a stretch, but the overlay concept is similar. Display Box mode lets you display an element above a page overlay. It does *not* block the UI but rather allows the displayed content to be dismissed with the ESC key or with a click on the overlay. The following code is used on this page:

<style type="text/css">
     // "displayBox" is the class name assigned to the display box container
    .displayBox img { background-color: #ddd; padding: 15px; border: 1px solid #888 }
</style>

<script type="text/javascript">
    $('#gecko').click(function() {
        $('<img width="500" height="500">')
            .attr('src', $(this).attr('href'))
            .appendTo('#main')
            .displayBox();
        return false;
    });
</script>

...

<a id="gecko" href="gecko.jpg"><img src="gecko.gif"><br>Click to Enlarge</a>

The displayBox method takes two optional arguments: a CSS object literal and a callback method. The CSS object is used to style the displayBox. The callback function is invoked when the displayBox is closed.

Default Settings

// override these in your code to change the default messages and styles
$.blockUI.defaults = {
    // the message displayed when blocking the entire page
    pageMessage:    '<h1>Please wait...</h1>',
    // the message displayed when blocking an element
    elementMessage: '', // none
    // styles for the overlay iframe
    overlayCSS:  { backgroundColor: '#fff', opacity: '0.5' },
    // styles for the message when blocking the entire page
    pageMessageCSS:    { width:'250px', margin:'-50px 0 0 -125px', top:'50%', left:'50%', textAlign:'center', color:'#000', backgroundColor:'#fff', border:'3px solid #aaa' },
    // styles for the message when blocking an element
    elementMessageCSS: { width:'250px', padding:'10px', textAlign:'center', backgroundColor:'#fff'},
    // styles for the displayBox
    displayBoxCSS: { width: '400px', height: '400px', top:'50%', left:'0%' },
    // allow body element to be stetched in ie6
    ie6Stretch: 1,
    // supress tab nav from leaving blocking content?
    allowTabToLeave: 0,
    // Title attribute for overlay when using displayBox
    closeMessage: 'Click to close',
    // use fadeIn effect
    fadeIn:  1,
    // fadeIn transition time in millis
    fadeInTime: 300,
    // use fadeOut effect when unblocking (can be overridden on unblock call)
    fadeOut:  1,
    // fadeOut transition time in millis
    fadeOutTime: 300
};

Overriding the Default Settings

The BlockUI Plugin provides a mechanism to easily update the default values for the message and styles so that you do not have to pass overrides on every call. Default settings are stored in the $.blockUI.defaults object which contains the following properties:

pageMessage

The message that is displayed when the entire page is being blocked. The default value is: <h1>Please wait<h1>

pageMessageCSS

The styles that get applied to the pageMessage

elementMessage

The message that is displayed over a blocked element. The default value is an empty string which indicates that no message is displayed.

elementMessageCSS

The styles that get applied to the elementMessage

overlayCSS

The styles that get applied to the overlay. The default value is: { backgroundColor: '#fff', opacity: '0.5' }

displayBoxCSS

The styles that get applied when invoking displayBox. The default value is: { width: '400px', height: '400px', top:'50%', left:'50%' }

fadeOut

true if unblocking should use a fade effect, otherwise false. The default value is true.
Note: This value can be overridden on the unblock call: $.unblockUI({ fadeOut:false });

fadeTime

The time, in milliseconds, of the fadeOut effect
Note: This value can be overridden on the unblock call: $.unblockUI({ fadeTime:'slow' });

Default settings that end in "CSS" are objects that contain CSS properties/values. Overrides can be placed in your own code. For example, to override the default page blocking message you might add this code to your page:

$.blockUI.defaults.pageMessage = "<h1>Bitte Wartezeit</h1>";

The default overlay background is white but it can be changed to any color you choose. For example, to use a blue overlay add this to your page:

$.extend($.blockUI.defaults.overlayCSS, { backgroundColor: '#00f' });

Or to change the styles of the page blocking message, add this:

$.extend($.blockUI.defaults.pageMessageCSS, { color: '#00a', backgroundColor: '#0f0' });

Frequently Asked Questions

What versions of jQuery is the BlockUI Plugin compatible with?

BlockUI is compatible with jQuery v1.1.1 and later.

Does the BlockUI Plugin have any dependencies on other plugins?

No.

Can I change the default message text used when blocking the page?

Yes. The default message is stored in $.blockUI.defaults.pageMessage. You can change it simply by assigning a new value, like this:

$.blockUI.defaults.pageMessage = "Please be patient...";

Can I change the color of the overlay?

Yes. The default overlay CSS is stored in $.blockUI.defaults.overlayCSS. The best way to change any of the CSS defaults is to use jQuery's exted method. For example, you can use a yellow overlay like this:

$.extend($.blockUI.defaults.overlayCSS, { backgroundColor: '#ff0' });

Does BlockUI support Opera 8?

Yes, but without the overlay. Opera did not support opacity until version 9 so a semi-transparent overlay is not possible in older versions.

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 it's disabled for that platform.

Download

The BlockUI Plugin is available in the jQuery Subversion repository: http://jqueryjs.googlecode.com/svn/trunk/plugins/blockUI/jquery.blockUI.js.

Support

Support for the BlockUI Plugin is available through the jQuery Mailing List. This is a very active list to which many jQuery developers and users subscribe.

Access to the jQuery Mailing List is also available through the Nabble Forums.