Tailwind CSS Overlay

The Overlay Tailwind plugin is an unstyled JavaScript utility for creating modals, drawers, and more, enhancing user interaction and content layout.

Installation

To get started, install Overlay plugin via npm, else you can skip this step if you are already using Preline UI as a package.

                      
                        npm i @preline/overlay

Example

Click "Open modal" button to trigger a modal/popup window on top of the current page.

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

                      
                        <button type="button" data-hs-overlay="#hs-unstyled-modal">
                          Open modal
                        </button>

                        <div id="hs-unstyled-modal" class="hs-overlay hidden size-full fixed top-0 start-0 z-[60] overflow-x-hidden overflow-y-auto pointer-events-none">
                          <div class="hs-overlay-open:opacity-100 hs-overlay-open:duration-500 opacity-0 transition-all sm:max-w-lg sm:w-full m-3 sm:mx-auto">
                            <div class="pointer-events-auto">
                              Modal content
                            </div>
                          </div>
                        </div>

JavaScript behavior

Options

Name	Description	Options	Default value
`data-hs-overlay`	Defines the modal.	—	—
`:hiddenClass`	Defines which classes will be added/removed when modal toggle.	string	`hidden`
`:isClosePrev`	Determines whether the previous open modal will be closed when the next one is opened.	boolean	`true`
`:backdropClasses`	Defines default backdrop classes.	string	`hs-overlay-backdrop transition duration fixed inset-0 bg-gray-900 bg-opacity-50 dark:bg-opacity-80 dark:bg-neutral-900`
`:backdropExtraClasses`	Allows to add additional classes besides those specified in `backdropClasses`.	string	—
`data-hs-overlay-backdrop-container`	Backdrop element selector.	—	`null`
`data-hs-overlay-keyboard`	When set to `false`, the modal will not close when pressing the ESC button on the keyboard.	boolean	`true`
`autofocus`	Focus the first input in a modal with the `autofocus` attribute on opening. Must be added to an input element inside a modal window.	—	—
`[--overlay-backdrop:*]`	When backdrop is set to `static`, the modal will not close when clicking outside it.	"static" \| null	`null`
`[--auto-hide:*]`	Milliseconds for auto-closing a modal.When set to `0`, the modal will not close.	number	`0`
`[--auto-close:*]`	Screen resolution at which the overlay will close automatically.	'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number	`null`
`[--opened:*]`	Screen resolution at which the plugin will apply functionality for the initially opened overlay.	'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number	`null`
`[--body-scroll:*]`	When set to `false`, the body scroll will be hidden as soon as the modal opens.	boolean	`true`
`[--tab-accessibility-limited:*]`	Restricts focus to elements within an overlay (or modal).	"true" \| "false"	`true`
`[--has-autofocus:*]`	Disables autofocus on the first focusable element when opening an overlay.	"true" \| "false"	`true`
`[--is-layout-affect:*]`	Informs the plugin that the instance affects to the website layout.	"true" \| "false"	`false`

Classes

Name	Description
`hs-overlay`	Defines overlays' content.
`hs-overlay-open`	Defines classes will be applied to any elements inside the `hs-overlay` when the overlay is open.
`hs-overlay-backdrop-open`	Defines classes will be applied to backdrop when the overlay is open.
`hs-overlay-layout-open`	Defines classes will be applied to any elements inside the body tag when the overlay is open.

Methods

The HSOverlay object is contained within the global window object

Method	Description
Public methods
`open()`	Force open modal.
`close()`	Force close modal.
Static methods
`HSOverlay.getInstance(target, isInstance)`	Returns the element associated to the `target`. `target` should be a Node or string (valid selector) `isInstance` boolean. Returns the instance instead of Node if `true`
`HSOverlay.open(target)`	Open modal. `target` should be a Node
`HSOverlay.close(target)`	Close modal. `target` should be a Node

Open item (public method).

                      
                        const modal = new HSOverlay(document.querySelector('#modal'));
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          modal.open();
                        });

Open item (static method).

                      
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          HSOverlay.open('#modal');
                        });

Open item (mixed).

                      
                        const { element } = HSOverlay.getInstance('#modal', true);
                        const openBtn = document.querySelector('#open-btn');

                        openBtn.addEventListener('click', () => {
                          element.open();
                        });

Events

Method	Description
`on:open`	Called when modal is open
`on:close`	Called when modal is closed

Open any modal event example.

                      
                        const el = HSOverlay.getInstance('#modal');

                        el.on('open', (instance) => {...});

Demo examples

Looking for prebuilt UI components based on the Tailwind CSS? Preline UI packs hundreds of component examples for all your website needs.

Check out Preline UI Dismiss

Tailwind CSS Overlay

Modal title

On this page