hq-modal/README.md

A simple component of modal

# 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:

```bash
npm install hq-modal --save-dev
```

##### Option 2 – Use from CDN

```html
<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:_**

```html
<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:_**

```html
<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:_**

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

---

## Usage

Initialization and basic configuration.

##### If using NPM, import the module:

```js
import HqModal from 'hq-modal';
```

##### If using CDN, just initialize:

## Initialization

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

---

## With configuration options

You can also pass in configuration options:

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

### Options reference

| Option          |   Type    | Default value          | Description                                         |
| --------------- | :-------: | ---------------------- | --------------------------------------------------- |
| maxWidth        | `string`  | `'500px'`              | Sets the modal window width.                        |
| background      | `string`  | `'rgba(0, 0, 0, 0.4)'` | Overlay background color (supports HEX, RGB, RGBA). |
| top             | `string`  | `'0px'`                | Top offset. (_use either `top` **or** `bottom`_)    |
| bottom          | `string`  | `'0px'`                | Bottom offset. (_use either `top` **or** `bottom`_) |
| left            | `string`  | `'0px'`                | Left offset. (_use either `left` **or** `right`_)   |
| right           | `string`  | `'0px'`                | Right offset. (_use either `left` **or** `right`_)  |
| showButtonClose | `boolean` | `false`                | Whether to show a built-in close button.            |

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

---

## Methods

After initializing hq-modal, we get an instance of the modal (e.g., the testName variable). This instance provides useful methods that can be used when needed.

| Method | Description            | Example         |
| ------ | ---------------------- | --------------- |
| show   | Shows the modal window | testName.show() |
| hide   | Hides the modal window | testName.hide() |

## 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**.