Overview

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();

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

Page Blocking Examples

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

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

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>

Demos

Most of the demos below will display for 2 seconds

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

        setTimeout($.unblockUI, 2000);
    });
});
        

$(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);
    });
});
        

$(document).ready(function() {
    $('#demo3').click(function() {
        $.blockUI({ overlayCSS: { backgroundColor: '#00f' } });

        setTimeout($.unblockUI, 2000);
    });
});
        

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

        setTimeout($.unblockUI, 2000);
    });
});
        

$(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);
    });
});
        

$(document).ready(function() {
    $('#demo6').click(function() {
        $.blockUI({
            centerY: 0,
            css: { top: '10px', left: '', right: '10px' }
        });

        setTimeout($.unblockUI, 2000);
    });
});
        

$(document).ready(function() {
    $('#demo7').click(function() {
        $.blockUI({ message: null });

        setTimeout($.unblockUI, 2000);
    });
});
        

$(document).ready(function() {
    $('#demo8').click(function() {
        $.blockUI();

        setTimeout(function() {
            $.unblockUI({
                onUnblock: function(){ alert('onUnblock'); }
            });
        }, 2000);
    });
});
        

$(document).ready(function() {
    $('#demo9').click(function() {
        $.blockUI();
        $('.blockOverlay').attr('title','Click to unblock').click($.unblockUI);
    });
});
        

$(document).ready(function() {
    $('#demo10').click(function() {
        $.blockUI({
            message: '<h1>Auto-Unblock!</h1>',
            timeout: 2000
        });
    });
});
        

$(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'
            }
        });
    });
});
        

$(document).ready(function() {
   $('#demo12').click(function() {
       $.growlUI('Growl Notification', 'Have a nice day!');
   });
});
       

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
}
    

$(document).ready(function() {
    $('#demo13').click(function() {
        $.blockUI({
            theme:     true,
            title:    'This is your title',
            message:  '<p>This is your message.</p>',
            timeout:   2000
        });
    });   
});
       

$(document).ready(function() {
    $('#demo14').click(function() {
        $.blockUI({
            fadeIn: 1000,
            timeout:   2000,
            onBlock: function() {
                alert('Page is now blocked; fadeIn complete');
            }
        });
    });   
});
       

$(document).ready(function() {
    $('#demo15').click(function() {
        $.blockUI({
            onOverlayClick: $.unblockUI
        });
    });   
});
       

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

    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
};

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
$.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

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

Change Log