BlockUI.js Documentation

BlockUI.js is a lightweight JavaScript library designed for blocking user interactions with a specific element or the entire page. This library can be used with jQuery or Cash.js (the latter is preferred due to its smaller size). It is heavily inspired/based on the jQuery BlockUI plugin but fully refactored and modified, although it retains most of its functionality API.

---

Installation

To use BlockUI.js, include the library and either jQuery or Cash.js in your project. Cash.js is recommended for its smaller footprint and performance benefits.

``html


`
#### Via npm

`javascript
npm i @knighttower/block-ui
`
there are also EMS and CJS via jsdelivr https://www.jsdelivr.com/package/npm/@knighttower/block-ui


or from the monorepo
`javascript
npm i knighttower
`

---

Features

- Block entire page or specific elements.
- Customizable messages, loaders, and styles.
- Configurable overlay, loader, and animations.
- Supports onBlock, onUnblock, and onOverlayClick callbacks.
- Handles keyboard navigation when blocked.
- Automatic z-index adjustments for compatibility.

---

Usage

$3

`javascript
// Basic usage
$.blockui.on('Please wait...');

// With configuration
$.blockui.on({
content: '

Loading...

',
loader: '

',
css: {
color: '#fff',
backgroundColor: '#444',
},
overlayCSS: {
opacity: 0.8,
},
});
`

$3

`javascript
$.blockui.off();
`

---

$3

`javascript
// Block an element
$(element).block();

// Custom block message for an element
$(element).block({
content: 'Loading...',
css: {
color: '#888',
},
});
`

$3

`javascript
$(element).unblock();
`

---

Configuration Options

Extend the default configuration to apply custom styles globally.

`javascript
$.extend(true, $.blockui.defaults, {
content: '

Please wait...

',
loader: '

',
css: {
color: '#555',
},
overlayCSS: {
opacity: 0.7,
},
});
`

$3

| Option | Type | Default Value | Description |
|-------------------|-------------------|-----------------------------------|-----------------------------------------------|
| content | string |

Please wait...

| The message displayed in the block UI. |
| loader | string | Custom HTML for loader. | The loading animation content. |
| tag | string | 'div' | The tag for the message container. |
| css | object | Styling for the block content. | Styles for the blocking element. |
| overlayCSS | object | Styling for the overlay. | Styles for the overlay background. |
| fadeIn | number | 200 | Fade-in duration in milliseconds. |
| fadeOut | number | 400 | Fade-out duration in milliseconds. |
| timeout | number | 0 | Auto unblock after timeout milliseconds. |
| zindex | string or number| 'auto' | Determines the z-index value. |
| onBlock | function | null | Callback when blocking starts. |
| onUnblock | function | null | Callback when unblocking completes. |
| onOverlayClick | function | null | Callback for overlay clicks. |

---

Examples

$3

`javascript
$.blockui.on({
content: '

Loading...

',
loader: '

',
overlayCSS: {
backgroundColor: '#333',
opacity: 0.9,
},
});
`

$3

`javascript
$(element).block({
content: 'Please wait...',
timeout: 3000, // Unblock after 3 seconds
});
`

$3

`javascript
$.blockui.on({
content: '

Processing...

',
zindex: 9999,
onBlock: function () {
console.log('BlockUI activated');
},
onUnblock: function () {
console.log('BlockUI deactivated');
},
});
`

---

Loader Styling Example

By default, the library provides a minimal loader:

`html

`

Override it by providing custom loader HTML or CSS.

---

Event Callbacks

| Event | Description |
|-----------------|-------------------------------------------|
| onBlock | Invoked when blocking begins. |
| onUnblock | Invoked after unblocking is completed. |
| onOverlayClick| Triggered when the overlay is clicked. |

Example:

`javascript
$.blockui.on({
onBlock: function () {
console.log('Blocking started');
},
onUnblock: function () {
console.log('Blocking ended');
},
onOverlayClick: function () {
alert('Overlay clicked!');
},
});
`

---

Notes

- Cash.js is recommended due to its smaller size compared to jQuery.
- The library automatically handles browser quirks and sets proper z-index for seamless overlays.
- Supports nested elements and ensures tab key constraint during blocking.
- Extend the default configuration globally using $.extend`.
---

Enjoy using BlockUI.js to create seamless UI interactions! 🎉