@knighttower/block-ui v1.16.0

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

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

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