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.

<script src="https://cdnjs.cloudflare.com/ajax/libs/cash/8.1.1/cash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/knighttower@latest/packages/block-ui/dist/browser/blockui.js"></script>

Via npm

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

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

Blocking the Entire Page

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

// With configuration
$.blockui.on({
    content: '<h4>Loading...</h4>',
    loader: '<div class="custom-loader"></div>',
    css: {
        color: '#fff',
        backgroundColor: '#444',
    },
    overlayCSS: {
        opacity: 0.8,
    },
});

Unblocking the Page

$.blockui.off();

Blocking Specific Elements

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

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

Unblocking an Element

$(element).unblock();

Configuration Options

Extend the default configuration to apply custom styles globally.

$.extend(true, $.blockui.defaults, {
    content: '<h4>Please wait...</h4>',
    loader: '<div class="spinner"></div>',
    css: {
        color: '#555',
    },
    overlayCSS: {
        opacity: 0.7,
    },
});

Default Configuration

| Option | Type | Default Value | Description | |-------------------|-------------------|-----------------------------------|-----------------------------------------------| | content | string | <h4>Please wait...</h4> | 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

Custom Loader and Overlay Styles

$.blockui.on({
    content: '<h3>Loading...</h3>',
    loader: '<div class="my-loader"></div>',
    overlayCSS: {
        backgroundColor: '#333',
        opacity: 0.9,
    },
});

Blocking with Timeout

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

Custom Z-Index and Callbacks

$.blockui.on({
    content: '<h4>Processing...</h4>',
    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:

<style>
.x-ldr, .x-ldr div {
    box-sizing: border-box;
}
.x-ldr {
    display: inline-block;
    position: relative;
    width: 80px;
    height: 30px;
}
.x-ldr div {
    position: absolute;
    width: 12px;
    height: 12px;
    border-radius: 50%;
    background: #a6a8b5;
    animation: x-ldr2 0.6s infinite;
}
</style>

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:

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