@gibme/overlay

A simple, configurable loading overlay built on jQuery, Bootstrap utilities, and FontAwesome icons.

Requirements

• Node.js >= 22
• jQuery 4.x
• Bootstrap 5.x (CSS utilities)
• FontAwesome (via @gibme/fontawesome)

Installation

yarn add @gibme/overlay

or

npm install @gibme/overlay

Usage

Module Import

import { Overlay } from '@gibme/overlay';

Webpack / Browser Bundle

A pre-built webpack bundle (Overlay.min.js) is included in the package and exposes the Overlay global.

Show / Hide

// Show overlay on the document body (default)
Overlay.handle($(document.body), 'show');

// Hide it
Overlay.handle($(document.body), 'hide');

Custom Options

Overlay.handle($('#my-element'), 'show', {
    background: { color: 'rgba(0, 0, 0, 0.5)' },
    icon: { name: 'circle-notch', style: 'solid', animation: 'spin', color: '#fff' },
    text: { message: 'Loading...', color: '#fff' },
    fade: { in: 300, out: 200 },
    timeout: 5000 // auto-hide after 5 seconds
});

Update Text

Overlay.handle($('#my-element'), 'text', 'Please wait...');

Update Progress Bar

Overlay.handle($('#my-element'), 'progress', 50); // 50%

Update Icon

Overlay.handle($('#my-element'), 'icon', {
    name: 'check',
    style: 'solid',
    color: '#28a745'
});

Update Image

Overlay.handle($('#my-element'), 'image', {
    source: '/path/to/image.png',
    animation: 'spin',
    width: 100,
    height: 100
});

Check Overlay State

if (Overlay.isOpen($('#my-element'))) {
    // overlay is currently visible
}

Events

The overlay emits jQuery events on the parent element:

| Event | Description | |--------------------|--------------------------------| | overlay.show | Fired when the overlay begins showing | | overlay.shown | Fired after the overlay is fully visible | | overlay.hidden | Fired after the overlay is fully removed | | overlay.resize | Fired after an overlay resize | | overlay.text | Fired when overlay text changes | | overlay.icon | Fired when the icon changes | | overlay.image | Fired when the image changes | | overlay.progress | Fired when progress updates |

Default Options

| Option | Default | |----------------------|------------------------------| | Background color | rgba(255, 255, 255, 0.8) | | Icon | spinner (solid, spin-pulse)| | Icon color | #202020 | | Text color | #202020 | | Fade in/out | 400ms / 200ms | | Progress bar | Animated, striped, #a0a0a0 | | z-index | 2147483647 |

Documentation

Full API documentation is available at https://gibme-npm.github.io/overlay/.

License

MIT