‹‹ homejQuery BlockUI Plugin

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({ 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: 
$(document).ajaxStart($.blockUI).ajaxStop($.unblockUI);

[1] Using the XMLHttpRequest object in synchronous mode causes the entire browser to lock until the remote call completes. This is usually not a desirable behavior.

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
    $(document).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 Simple Modal by Eric Martin or jqModal 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: $('#displayBox'),
            css: {
                top:  ($(window).height() - 400) /2 + 'px',
                left: ($(window).width() - 400) /2 + 'px',
                width: '400px'
            }
        });

        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: 2000
        });
    });
});
Growl (the hard way) 
$(document).ready(function() {
    $('#demo11').click(function() {
        $.blockUI({
            message: $('div.growlUI'),
            fadeIn: 700,
            fadeOut: 700,
            timeout: 2000,
            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.

jQuery UI Theme
Use jQuery UI themes to style the messaege		 
$(document).ready(function() {
    $('#demo13').click(function() {
        $.blockUI({
            theme:     true,
            title:    'This is your title',
            message:  '<p>This is your message.</p>',
            timeout:   2000
        });
    });   
});

For more details on using this feature see theme.html

onBlock callback 
$(document).ready(function() {
    $('#demo14').click(function() {
        $.blockUI({
            fadeIn: 1000,
            timeout:   2000,
            onBlock: function() {
                alert('Page is now blocked; fadeIn complete');
            }
        });
    });   
});
onOverlayClick callback Click overlay to unblock. 
$(document).ready(function() {
    $('#demo15').click(function() {
        $.blockUI({
            onOverlayClick: $.unblockUI
        });
    });   
});

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>',

    title: null,        // title string; only used when theme == true
    draggable: true,    // only used when theme == true (requires jquery-ui.js to be loaded)

    theme: false, // set to true to use with jQuery UI themes

    // 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'
    },

    // minimal style set used when themes are used
    themedCSS: {
        width:  '30%',
        top:    '40%',
        left:   '35%'
    },

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

    // style to replace wait cursor before unblocking to correct issue
    // of lingering wait cursor
    cursorReset: 'default',

    // styles applied when using $.growlUI
    growlCSS: {
        width:    '350px',
        top:      '10px',
        left:     '',
        right:    '10px',
        border:   'none',
        padding:  '5px',
        opacity:   0.6,
        cursor:    null,
        color:    '#fff',
        backgroundColor: '#000',
        '-webkit-border-radius': '10px',
        '-moz-border-radius':    '10px'
    },
    
    // IE issues: 'about:blank' fails on HTTPS and javascript:false is s-l-o-w
    // (hat tip to Jorge H. N. de Vasconcelos)
    iframeSrc: /^https/i.test(window.location.href || '') ? 'javascript:false' : 'about:blank',

    // force usage of iframe in non-IE browsers (handy for blocking applets)
    forceIframe: false,

    // 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,

    // enable if you want key and mouse events to be disabled for content that is blocked
    bindEvents: true,

    // be default blockUI will supress tab navigation from leaving blocking content
    // (if bindEvents is true)
    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)
    // no longer needed in 2012
    // applyPlatformOpacityRules: true,

    // callback method invoked when fadeIn has completed and blocking message is visible
    onBlock: null,

    // 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,

    // class name of the message block
    blockMsgClass: 'blockMsg',

    // if it is already blocked, then ignore it (don't unblock and reblock)
    ignoreIfBlocked: false
};
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.
Can I use blockUI with TypeScript?
Yes. BlockUI user Joseph Atkinson has kindly provided a TypeScript declaration file for that purpose.
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.

You can also follow the development on Github: 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 Forum.

Change Log

changes.txt

The BlockUI Plugin and this documentation are the work of Mike Alsup. Send comments to jquery at malsup dot com.