# ray-dialog-box

> ray dialog

Latest version **1.0.5** (published 2024-03-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install ray-dialog-box
pnpm add ray-dialog-box
yarn add ray-dialog-box
bun add ray-dialog-box
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2024-03-05 |
| First published | 2018-01-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 201.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | ilex.h |
| Maintainers | ilex.h |
| Keywords | ray dialog, alert, prompt |

## Links

- npm: https://www.npmjs.com/package/ray-dialog-box
- npm.io page: https://npm.io/package/ray-dialog-box

## Alternatives

- [react-native-root-siblings](https://npm.io/package/react-native-root-siblings.md) — 102.9K weekly downloads
- [post-robot](https://npm.io/package/post-robot.md) — 93.7K weekly downloads
- [@praxisui/dialog](https://npm.io/package/@praxisui/dialog.md) — 2.0K weekly downloads
- [easy-toggle-state](https://npm.io/package/easy-toggle-state.md) — 350 weekly downloads
- [ngx-lightbox-evp](https://npm.io/package/ngx-lightbox-evp.md) — 19 weekly downloads

## Recent versions

- 1.0.5 (latest) — 2024-03-05
- 1.0.4 — 2018-02-27
- 1.0.3 — 2018-02-27
- 1.0.2 — 2018-01-11
- 1.0.1 — 2018-01-11
- 1.0.0 — 2018-01-11

## README

RayDialog
-----------

A beautiful, responsive, customizable, accessible (WAI-ARIA) replacement for JavaScript's popup boxes. Zero dependencies.

---


Installation
------------

```bash
npm install --save ray-dialog-box
```

Usage
-----

```html
<script src="/lib/ray-dialog-box"></script>
<link rel="stylesheet" type="text/css" href="/lib/raydialog.css">

<!-- Include a polyfill for ES6 Promises (optional) for IE11, UC Browser and Android browser support -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/core-js/2.4.1/core.js"></script>
```

Or:

```js
// ES6 Modules or TypeScript
import rayd from 'ray-dialog-box'

// CommonJS
const rayd = require('ray-dialog-box')
```

Please note that TypeScript is supported, so you don't have to install a third-party declaration file.


Examples
--------

The most basic message:

```js
rayd('Hello world!')
```

A message signaling an error:

```js
rayd('Oops...', 'Something went wrong!', 'error')
```

Handling the result of RayDialog modal:

```js
rayd({
  title: 'Are you sure?',
  text: 'You will not be able to recover this imaginary file!',
  type: 'warning',
  showCancelButton: true,
  confirmButtonText: 'Yes, delete it!',
  cancelButtonText: 'No, keep it'
}).then(function() {
  rayd(
    'Deleted!',
    'Your imaginary file has been deleted.',
    'success'
  )
}, function(dismiss) {
  // dismiss can be 'overlay', 'cancel', 'close', 'esc', 'timer'
  if (dismiss === 'cancel') {
    rayd(
      'Cancelled',
      'Your imaginary file is safe :)',
      'error'
    )
  }
})
```

Handling Dismissals
-------------------

When an alert is dismissed by the user, the Promise returned by `rayd()` will reject with a string documenting the reason it was dismissed:

| String      | Description                                             | Related configuration |
| ----------- | ------------------------------------------------------- | --------------------- |
| `'overlay'` | The user clicked the overlay.                           | `allowOutsideClick`   |
| `'cancel'`  | The user clicked the cancel button.                     | `showCancelButton`    |
| `'close'`   | The user clicked the close button.                      | `showCloseButton`     |
| `'esc'`     | The user pressed the <kbd>Esc</kbd> key.                | `allowEscapeKey`      |
| `'timer'`   | The timer ran out, and the alert closed automatically.  | `timer`               |

If rejections are not handled, it will be logged as an error. To avoid this, add a rejection handler to the Promise. Alternatively, you can use `.catch(rayd.noop)` as a quick way to simply suppress the errors:

```js
rayd(...)
  .catch(rayd.noop)
```

Modal Types
-----------

| `success`      | `error`   | `warning`  | `info`     | `question`   |


Configuration
-------------

| Argument                | Default value        | Description |
| ----------------------- | -------------------- | ----------- |
| `title`                 | `null`               | The title of the modal, as HTML. It can either be added to the object under the key "title" or passed as the first parameter of the function. |
| `titleText`             | `null`               | The title of the modal, as text. Useful to avoid HTML injection. |
| `text`                  | `null`               | A description for the modal. It can either be added to the object under the key "text" or passed as the second parameter of the function. |
| `html`                  | `null`               | A HTML description for the modal. If `text` and `html` parameters are provided in the same time, "text" will be used. |
| `type`                  | `null`               | The type of the modal. RayDialog comes with [5 built-in types](#modal-types) which will show a corresponding icon animation: `warning`, `error`, `success`, `info` and `question`. It can either be put in the array under the key `type` or passed as the third parameter of the function. |
| `target`                | `'body'`             | The container element for adding modal into. |
| `input`                 | `null`               | Input field type, can be `'text'`, `'email'`, `'password'`, `'number'`, `'tel'`, `'range'`, `'textarea'`, `'select'`, `'radio'`, `'checkbox'`, `'file'` and `'url'`. |
| `width`                 | `'500px'`            | Modal window width, including paddings (`box-sizing: border-box`). Can be in `px` or `%`. |
| `padding`               | `20`                 | Modal window padding. |
| `background`            | `'#fff'`             | Modal window background (CSS `background` property). |
| `customClass`           | `null`               | A custom CSS class for the modal. |
| `timer`                 | `null`               | Auto close timer of the modal. Set in ms (milliseconds). |
| `animation`             | `true`               | If set to `false`, modal CSS animation will be disabled. |
| `emphasize`             | `false`              | If set to `true`, modal will use emphasize animation. |
| `allowOutsideClick`     | `true`               | If set to `false`, the user can't dismiss the modal by clicking outside it. |
| `allowEscapeKey`        | `true`               | If set to `false`, the user can't dismiss the modal by pressing the <kbd>Esc</kbd> key. |
| `allowEnterKey`         | `true`               | If set to `false`, the user can't confirm the modal by pressing the <kbd>Enter</kbd> or <kbd>Space</kbd> keys, unless they manually focus the confirm button. |
| `showConfirmButton`     | `true`               | If set to `false`, a "Confirm"-button will not be shown. It can be useful when you're using `html` parameter for custom HTML description. |
| `showCancelButton`      | `false`              | If set to `true`, a "Cancel"-button will be shown, which the user can click on to dismiss the modal. |
| `confirmButtonText`     | `'OK'`               | Use this to change the text on the "Confirm"-button. |
| `cancelButtonText`      | `'Cancel'`           | Use this to change the text on the "Cancel"-button. |
| `confirmButtonColor`    | `'#3085d6'`          | Use this to change the background color of the "Confirm"-button (must be a HEX value). |
| `cancelButtonColor`     | `'#aaa'`             | Use this to change the background color of the "Cancel"-button (must be a HEX value). |
| `confirmButtonClass`    | `null`               | A custom CSS class for the "Confirm"-button. |
| `cancelButtonClass`     | `null`               | A custom CSS class for the "Cancel"-button. |
| `buttonsStyling`        | `true`               | Apply default styling to buttons. If you want to use your own classes (e.g. Bootstrap classes) set this parameter to `false`. |
| `reverseButtons`        | `false`              | Set to `true` if you want to invert default buttons positions ("Confirm"-button on the right side). |
| `focusCancel`           | `false`              | Set to `true` if you want to focus the "Cancel"-button by default. |
| `showCloseButton`       | `false`              | Set to `true` to show close button in top right corner of the modal. |
| `showLoaderOnConfirm`   | `false`              | Set to `true` to disable buttons and show that something is loading. Useful for AJAX requests. |
| `preConfirm`            | `null`               | Function to execute before confirm, should return Promise. |
| `imageUrl`              | `null`               | Add an image for the modal. Should contain a string with the path or URL to the image. |
| `imageWidth`            | `null`               | If imageUrl is set, you can specify imageWidth to describes image width in px. |
| `imageHeight`           | `null`               | Custom image height in px. |
| `imageClass`            | `null`               | A custom CSS class for the image. |
| `inputPlaceholder`      | `''`                 | Input field placeholder. |
| `inputValue`            | `''`                 | Input field initial value. |
| `inputOptions`          | `{}` or `Promise`    | If `input` parameter is set to `'select'` or `'radio'`, you can provide options. Object keys will represent options values, object values will represent options text values. |
| `inputAutoTrim`         | `true`               | Automatically remove whitespaces from both ends of a result string. Set this parameter to `false` to disable auto-trimming. |
| `inputAttributes`       | `{}`                 | HTML input attributes (e.g. `'min'`, `'max'`, `'autocomplete'`, `'accept'`), that are added to the input field. Object keys will represent attributes names, object values will represent attributes values. |
| `inputValidator`        | `null`               | Validator for input field, should return Promise. |
| `inputClass`            | `null`               | A custom CSS class for the input field. |
| `progressSteps`         | `[]`                 | Progress steps, useful for modal queues. |
| `currentProgressStep`   | `null`               | Current active progress step. The default is `rayd.getQueueStep()`. |
| `progressStepsDistance` | `'40px'`             | Distance between progress steps. |
| `onOpen`                | `null`               | Function to run when modal opens, provides modal DOM element as the first argument. |
| `onClose`               | `null`               | Function to run when modal closes, provides modal DOM element as the first argument. |
| `useRejections`         | `true`               | Determines whether dismissals (outside click, cancel button, close button, esc key) should reject, or resolve with an object of the format `{ dismiss: reason }`. Set it to `false` to get a cleaner control flow when using `await`. |

You can redefine default params by using `rayd.setDefaults(customParams)` where `customParams` is an object.


Methods
-------

| Method                                          | Description |
| ----------------------------------------------- | ----------- |
| `rayd.isVisible()`                              | Determine if modal is shown. |
| `rayd.setDefaults({Object})`                    | If you end up using a lot of the same settings when calling RayDialog, you can use setDefaults at the start of your program to set them once and for all! |
| `rayd.resetDefaults()`                          | Resets settings to their default value. |
| `rayd.close()` or `rayd.closeModal()`           | Close the currently open RayDialog modal programmatically. |
| `rayd.getTitle()`                               | Get the modal title. |
| `rayd.getContent()`                             | Get the modal content. |
| `rayd.getImage()`                               | Get the image. |
| `rayd.getConfirmButton()`                       | Get the "Confirm" button. |
| `rayd.getCancelButton()`                        | Get the "Cancel" button. |
| `rayd.enableButtons()`                          | Enable "Confirm" and "Cancel" buttons. |
| `rayd.disableButtons()`                         | Disable "Confirm" and "Cancel" buttons. |
| `rayd.enableConfirmButton()`                    | Enable the "Confirm"-button only. |
| `rayd.disableConfirmButton()`                   | Disable the "Confirm"-button only. |
| `rayd.enableLoading()` or `rayd.showLoading()`  | Disable buttons and show loader. This is useful with AJAX requests. |
| `rayd.disableLoading()` or `rayd.hideLoading()` | Enable buttons and hide loader. |
| `rayd.clickConfirm()`                           | Click the "Confirm"-button programmatically. |
| `rayd.clickCancel()`                            | Click the "Cancel"-button programmatically. |
| `rayd.showValidationError(error)`               | Show validation error message. |
| `rayd.resetValidationError()`                   | Hide validation error message. |
| `rayd.getInput()`                               | Get the input DOM node, this method works with `input` parameter. |
| `rayd.disableInput()`                           | Disable input. A disabled input element is unusable and un-clickable. |
| `rayd.enableInput()`                            | Enable input. |
| `rayd.queue([Array])`                           | Provide array of RayDialog parameters to show multiple modals, one modal after another or a function that returns alert parameters given modal number. |
| `rayd.getQueueStep()`                           | Get the index of current modal in queue. When there's no active queue, `null` will be returned. |
| `rayd.insertQueueStep()`                        | Insert a modal to queue, you can specify modal positioning with second parameter. By default a modal will be added to the end of a queue. |
| `rayd.deleteQueueStep(index)`                   | Delete a modal at `index` from queue. |
| `rayd.getProgressSteps()`                       | Progress steps getter. |
| `rayd.setProgressSteps([])`                     | Progress steps setter. |
| `rayd.showProgressSteps()`                      | Show progress steps. |
| `rayd.hideProgressSteps()`                      | Hide progress steps. |


Browser compatibility
---------------------

| IE11* | Edge | Chrome | Firefox | Safari | Opera | Android Browser* | UC Browser* |
|-------|------|--------|---------|--------|-------|------------------|-------------|
|  ✅   |   ✅  |   ✅   |     ✅   |   ✅   |    ✅   |        ✅        |      ✅      |

\* ES6 Promise polyfill should be included, see [usage example](#usage).

Note that RayDialog **does not** and **will not** provide support or functionality of any kind on IE10 and lower.

---
_Source: https://npm.io/package/ray-dialog-box · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._