hq-modal

Hq-Modal is an exceptionally simple utility for managing and configuring modal windows on a web page. It helps you quickly set up and trigger modals.

The library allows you to:

• Set the modal window width
• Control its position on the page
• Customize the overlay color
• Show or hide the close button
• Fix content shift when opening a modal
• Close modals on Escape key or outside click
• Block scrolling and interaction with the background
• Responsive: works well on mobile without blocking content
• Lightweight (~2KB minified), with zero dependencies

Installation

Several usage and installation options:

Option 1 – NPM

Install via npm:

npm install hq-modal --save-dev

Option 2 – Use from CDN

<script src="https://unpkg.com/hq-modal@latest/dist/hq-modal.umd.js"></script>

Setup

1 – Define the modal window

In HTML, define the modal block using data-hq-modal-block="test-name" and hidden.

Replace "test-name" with any name you like.

Example:

<div data-hq-modal-block="test-name" hidden>
  <!-- modal content -->
</div>

2 – Add modal trigger elements

To trigger the modal, assign the attribute data-hq-modal-button="test-name" to any element.

"test-name" should match the name used in the previous step.

Example:

<button data-hq-modal-button="test-name">Open Modal</button>

Optional close buttons inside modal

If you'd like to add extra close buttons inside the modal, assign the attribute data-hq-modal-close to them.

Note: This is for internal buttons only. The built-in close button is controlled by the showButtonClose option during initialization.

Example:

<button data-hq-modal-close>Close</button>

Usage

Initialization and basic configuration:

If using NPM, import the module:

import HqModal from 'hq-modal';

If using CDN, just initialize:

Initialization

const testName = new HqModal('test-name');

With configuration options

You can also pass in configuration options:

const testName = new HqModal('test-name', {
  maxWidth: '400px',
  background: 'rgba(0, 0, 0, 0.5)',
  top: '10px',
  left: '100px',
  showButtonClose: true,
});

Options reference

⚠️ Note: top and bottom should not be used together — choose one. Same applies to left and right.

Requirements and Compatibility

• Can be used as an ES module
• Can also be used as a UMD bundle (hq-modal.umd.js is included or via CDN)
• Works in all modern browsers

License

This project is licensed under the MIT License.