Overview

BlockUI has recently received a much needed update. This documentation is for the new 2.0 version of the plugin. If you need documentation for the old v1.xx versions, you can find it here. This version of BlockUI requires jQuery v1.2.3 or later!

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

$.blockUI();

$.blockUI({ message: '<h1><img src="busy.gif" /> Just a moment...</h1>' });

$.blockUI({ css: { backgroundColor: '#f00', color: '#fff'} });

$.unblockUI();

$().ajaxStart($.blockUI).ajaxStop($.unblockUI);

Page Blocking Examples

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

The following code is used on this page:

<script type="text/javascript">
    $(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

The following code is used on this page:

<script type="text/javascript">
    $(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>

Demos

Each of the demos below will display for 2 seconds.

jQuery('#demo1').click(function() {
    jQuery.blockUI({ message: $('#loginForm') });
    
    setTimeout(jQuery.unblockUI, 2000);
});    
        

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

jQuery('#demo3').click(function() {
    jQuery.blockUI({ overlayCSS: { backgroundColor: '#00f' } });
    
    setTimeout(jQuery.unblockUI, 2000);
});    
        

jQuery('#demo4').click(function() {
    jQuery.blockUI({ 
        message: jQuery('#tallContent'), 
        css: { top: '20%' } 
    });
    
    setTimeout(jQuery.unblockUI, 2000);
});    
        

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

jQuery('#demo6').click(function() {
    jQuery.blockUI({ 
        centerY: 0,
        css: { top: '10px', left: '', right: '10px' }
    });
    
    setTimeout(jQuery.unblockUI, 2000);
});    
        

jQuery('#demo7').click(function() {
    jQuery.blockUI({ message: null });
    
    setTimeout(jQuery.unblockUI, 2000);
});    
        

jQuery('#demo8').click(function() {
    jQuery.blockUI();
    
    setTimeout(function() {
        jQuery.unblockUI({
            onUnblock: function(){ alert('onUnblock'); }
        });
    }, 2000);
});    
        

Options

// 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' 
    },
    
    // 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,
    
    // fadeOut time in millis; set to 0 to disable fadeout on unblock
    fadeOut:  400,
    
    // suppresses the use of overlay styles on FF/Linux (due to significant performance issues with opacity)
    applyPlatformOpacityRules: true
};

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

// change message border
$.blockUI.defaults.css.border = '5px solid red';

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

Local Overrides

// change message border
$.blockUI({ css: { border = '5px solid red'} });

...

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

...

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

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.

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

The old version of blockUI is still available in the jQuery repository: http://jqueryjs.googlecode.com/svn/trunk/plugins/blockUI/jquery.blockUI.js.
The old docs can be found here.

Support

Change Log