Documentation

Everything you need to use OpenModal in your project.

Getting Started

OpenModal is a lightweight, framework-agnostic modal library built with vanilla ES6. It uses animate.css for entry/exit animations and works with any CSS framework or custom styles.

Installation

npm

npm install open-modal

CDN

<link rel="stylesheet" href="dist/open-modal.css">
<script type="module">
  import OpenModal from './dist/open-modal.js'
</script>

Peer Dependency

OpenModal requires animate.css v4.x for animations. Add it via CDN or npm:

<link rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">

Basic Usage

1. HTML structure

You need a trigger button, a container div, and a content div:

<button id="showModal">Open Modal</button>

<div class="open-modal hide">
  <div class="modal-content">
    <p>Your content here</p>
    <button id="cancelButton">Close</button>
  </div>
</div>

2. JavaScript

import OpenModal from 'open-modal'

const modal = new OpenModal()
modal.init()

In the example above, all options use their default values: the show button has id showModal, the close button has id cancelButton, the container uses class open-modal, and the content uses class modal-content.

Configuration

All options are passed as an object to the constructor:

const modal = new OpenModal({
  btnShowId: 'myButton',
  containerBackground: 'rgba(0,0,0,0.5)',
  contentEffects: {
    contentInEffects: 'animate__fadeInDown',
    contentOutEffects: 'animate__fadeOutUp',
  },
})

Option	Default	Description
`btnShowId`	`"showModal"`	ID of the button that opens the modal
`btnCancelId`	`"cancelButton"`	ID of the button that closes the modal
`containerClass`	`"open-modal"`	CSS class of the modal backdrop container
`contentClass`	`"modal-content"`	CSS class of the modal content wrapper
`hideClass`	`"hide"`	Class that hides the modal (`display: none`)
`containerBackground`	`false`	Background color/opacity for the backdrop (e.g. `"rgba(0,0,0,0.5)"`)
`containerEffects`	`false`	Object with `containerInEffects` and `containerOutEffects`
`contentEffects`	`false`	Object with `contentInEffects` and `contentOutEffects`
`effectPrefix`	`"animate__animated"`	Base class for animate.css animations
`trigger`	`false`	Optional callback function called before opening

API Reference

`constructor(options)`

Creates a new OpenModal instance. See the Configuration section for all available options.

`.init()`

Initializes the modal by registering click listeners on the show and cancel buttons. Call this once per instance.

`.updateEffects(contentIn, contentOut)`

Changes the animation effects in real time without recreating the instance. Useful for dynamic effect switching.

modal.updateEffects('animate__fadeIn', 'animate__fadeOut')

`.clearAnimateClasses(className)`

Removes all animate__* classes from elements matching the given CSS class. Used internally to reset animation state.

Effects

OpenModal ships with 17 animation pairs. Each pair defines both an entrance and an exit animation. You can mix and match any combination.

See the full interactive demo on the Effects Explorer page.

Examples

Custom Effects

const modal = new OpenModal({
  btnShowId: 'myBtn',
  btnCancelId: 'myCloseBtn',
  containerBackground: 'rgba(45, 106, 79, 0.4)',
  containerEffects: {
    containerInEffects: 'animate__fadeIn',
    containerOutEffects: 'animate__fadeOut',
  },
  contentEffects: {
    contentInEffects: 'animate__bounceInLeft',
    contentOutEffects: 'animate__bounceOutRight',
  },
})
modal.init()

With Bootstrap

const bsModal = new OpenModal({
  btnShowId: 'bsBtn',
  btnCancelId: 'bsClose',
  containerClass: 'modal-backdrop',
  contentClass: 'modal-dialog',
  hideClass: 'd-none',
})

Dynamic Effect Switching

// Create instance once
const modal = new OpenModal({ ... })
modal.init()

// Switch effects dynamically
document.querySelector('#effect-select').addEventListener('change', (e) => {
  modal.updateEffects(
    `animate__${e.target.value}In`,
    `animate__${e.target.value}Out`
  )
})

Migration from v1.1.x

Version 1.2.0 introduced several improvements and fixes:

Removed initObject() and window.OPM — no more shared global state
Removed the implicit init() call inside the cancel handler — call init() only once
Added updateEffects() — change animations in real time
Added clearAnimateClasses() — reset animation state
Animation classes — the animate__animated base class is no longer removed during transitions

If you relied on window.OPM or re-called init() manually, update your code to use the new API.