11/10/2010 jQuery BlockUI Plugin (v2)

‹‹ homejQuery BlockUI Plugin (v2)

Overview
Page Blocking
Element Blocking
Modal Dialogs
Demos
Options
FAQ
Download and Support

Updates posted
Overview on twitter

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

Default Message Custom Message Custom Style DOM Element as Message

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

www.malsup.com/jquery/block/#demos 1/7
11/10/2010 jQuery BlockUI Plugin (v2)
</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.

Block Block with Message Unblock

Test link - click me!

Option 1 lorem ipsum dolor sit amet consectetuer adipiscing elit sed lorem leo lorem
leo consectetuer adipiscing elit sed lorem leo rhoncus sit amet Option 1 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
test textarea

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.

Show Dialog

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

www.malsup.com/jquery/block/#demos 2/7
11/10/2010 jQuery BlockUI Plugin (v2)
$.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

Run Login Form

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

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

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

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

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

Run Tall Content

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

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

Run Image Box

$(document).ready(function() {
$('#demo5').click(function() {
$.blockUI({
message: $('img#displayBox'),
css: {
top: ($(window).height() - 500) /2 + 'px',

www.malsup.com/jquery/block/#demos 3/7
11/10/2010 jQuery BlockUI Plugin (v2)
Run Non-
$(document).ready(function() {
centered $('#demo6').click(function() {
message $.blockUI({
centerY: 0,
css: { top: '10px', left: '', right: '10px' }
});

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

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

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

Run Click
$(document).ready(function() {
overlay to $('#demo9').click(function() {
unblock $.blockUI();
(This demo $('.blockOverlay').attr('title','Click to unblock').click($.unblockUI);
});
will not
});
automatically
unblock, you
must click
the overlay.)

Run Auto-
$(document).ready(function() {
Unblock $('#demo10').click(function() {
Sets a timer $.blockUI({
to unblock message: '<h1>Auto-Unblock!</h1>',
timeout: 2000
after a
});
specified });
timeout. });

Run Growl (the

$(document).ready(function() {
hard way) $('#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'

www.malsup.com/jquery/block/#demos 4/7
11/10/2010 jQuery BlockUI Plugin (v2)
$.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.

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

For more details on using this feature see theme.html

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

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

www.malsup.com/jquery/block/#demos 5/7
11/10/2010 jQuery BlockUI Plugin (v2)
// (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)
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!' });

www.malsup.com/jquery/block/#demos 6/7
11/10/2010 jQuery BlockUI Plugin (v2)
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

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

www.malsup.com/jquery/block/#demos 7/7