RayDialog

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

Installation

npm install --save ray-dialog-box

Usage

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

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

rayd('Hello world!')

A message signaling an error:

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

Handling the result of RayDialog modal:

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

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 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 Esc key. | | allowEnterKey | true | If set to false, the user can't confirm the modal by pressing the Enter or Space 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.

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