1. Docs
  2. Modal

Modal Component

Learn how to create customizable modal dialogs with animations and advanced configuration options.

UnoCSS PresetTailwind Plugin
The Modal component allows you to easily create accessible, customizable modals in your web application. It provides flexible options for animations, content control, and more, giving you full control over how the modal behaves.

Installation

To get started with the modal component, install the @flexilla/modal package:

Structure

Markup Structure

  • modal-trigger: Element that triggers the modal, with the data-modal-target the value must be the targeted modal.
  • modal-element: A valid HTMLDialog Element The modal element, must have a id
  • data-modal-content: The modal content
  • data-close-modal: any element inside the modal-element to close the modal
Here is a basic example of how to structure your modal and trigger elements in HTML: 
<!-- Trigger Button -->
<button data-modal-target="myModal" aria-haspopup="dialog">Open Modal</button>
<!-- Modal Structure -->
<dialog data-modal-id="myModal" role="dialog" aria-hidden="true">
  <div data-modal-content class="modal-content">
    <button data-close-modal class="modal-close-btn" aria-label="Close Modal">X</button>
    <p>This is the modal content!</p>
  </div>
</dialog>
To add overlay
  • Adding a overlay element 
<dialog data-modal-id="myModal" id="myModal" role="dialog" aria-hidden="true">
    <div data-modal-overlay></div>
    ...
</dialog>
  • Let it be created by the library 
<dialog id="myModal" role="dialog" aria-hidden="true" data-modal-overlay="overlay classes">

Example

Initialization

Modal Options

The modal component provides a range of configuration options through the ModalOptions object. Here’s a breakdown of the available options:

defaultState

Specifies whether the modal should be open or closed by default.
  • Type: "open" | "close"
  • Default: "close"

animateContent

Define CSS animations for the modal content when showing and hiding the modal. You can specify both enterAnimation and exitAnimation (optional).
  • Type: ModalContentAnimations
  • Example:
  • Requirement: For this to work, you need to set the following CSS on the modal content element: 
/* do this if you want to add animation on enter and exit */
.myModalContent{
    animation: var(--un-modal-animation);
    animationFillMode: both;
}
/* if you want to add animation on enter only or on exit only then set it like this */
.myModalContent[data-state=open]{
    animation: var(--un-modal-animation);
    animationFillMode: both;
}
/* or  */
.myModalContent[data-state=close]{
    /* required animations rules  */
}
  • Animate on Enter only
Setting in Options 
animateContent: {
    enterAnimation: 'fadeScale .4s linear',
}
setting in data-attribute 
<dialog ...>
    <div data-modal-content data-enter-animation="fadeScale .4s linear" ...>
    </div>
</dialog>
  • Animate on enter and exit
Setting in Options 
animateContent:{
  enterAnimation: 'slideIn .4s linear',
  exitAnimation: 'slideOut .2s linear',
}
setting in data-attribute 
<dialog ...>
    <div data-modal-content 
      data-enter-animation="slideIn .4s linear"
      data-exit-animation="slideOut .2s linear"  ...>
    </div>
</dialog>

overlayClass

Add a custom class for the modal overlay (background layer).
  • Type: string
  • Example: 
{
  overlayClass: 'custom-overlay-class'
}

preventCloseModal

Disable close modal behavior while clicking outside modal content or pressing esc. If true, prevents the modal from being closed (useful for alerts or confirmations).
  • Type: boolean
  • Default: false

allowBodyScroll

If set to false, prevents scrolling of the body when the modal is open.
  • Type: boolean
  • Default: false

enableStackedModals

Allows multiple modals to be stacked on top of each other.
  • Type: boolean
  • Default: false

beforeHide

A function that executes before the modal is hidden. You can return an object with cancelAction: true to prevent the modal from closing.
  • Type: () => { cancelAction?: boolean; } | void
Example 
let isFailed = true

const modal = new Modal('#myModal', {
    beforeHide: () => {
        // you'll notice that the modal with not close if isFailed value is set to true
        if (isFailed) {
            isFailed = false
            return { cancelAction: true }
        }
    },
});

onShow

Callback function that triggers when the modal is shown.
  • Type: () => void

onHide

Callback function that triggers when the modal is hidden.
  • Type: () => void

onToggle

Callback function that triggers when the modal is toggled (open/close). It provides the isHidden state to indicate whether the modal is currently hidden.
  • Type: ({ isHidden }: { isHidden: boolean }) => void

Initialization Example

Here’s an example of initializing a modal with custom options: 
import { Modal } from '@flexilla/modal';

const modal = new Modal('#myModal', {
  defaultState: 'close',
  animateContent: {
    enterAnimation: 'fadeIn 0.3s ease',
    exitAnimation: 'fadeOut 0.3s ease',
  },
  overlayClass: 'custom-modal-overlay',
  allowBodyScroll: false,
  preventCloseModal: false,
  enableStackedModals: true,
  onShow() {
    console.log('Modal is shown');
  },
  onHide() {
    console.log('Modal is hidden');
  },
  onToggle({ isHidden }) {
    console.log('Modal toggled. Hidden:', isHidden);
  }
});

Methods

showModal()

Programmatically opens the modal. 
modal.showModal();

hideModal()

Programmatically closes the modal. 
modal.hideModal();