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" aria-haspopup="dialog" aria-expanded="false" aria-controls="hs-unstyled-modal" 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" role="dialog" tabindex="-1" aria-labelledby="hs-unstyled-modal-label">
                          <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">
                              <h3 id="hs-unstyled-modal-label">Title</h3>
                              Modal content
                            </div>
                          </div>
                        </div>

JavaScript behavior

Data Options

Name	Description	Options	Default value
`data-hs-overlay-options`	Defines the modal. Should be added to the button (trigger).	—	—
`:hiddenClass`	Defines which classes will be added/removed when modal toggle.	string	`hidden`
`:emulateScrollbarSpace`	If `true`, then adds right padding to the body equal to the size of the scrollbar.	boolean	`false`
`: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	—
`:backdropParent`	Allows to specify the selector of the element where the backdrop will be generated.	string	—
`:moveOverlayToBody`	Moves the overlay to the body tag if the screen width is less than the value specified.	number \| null	`null`
`data-hs-overlay-backdrop-container`	Backdrop element selector. Should be added to the overlay (content).	—	`null`
`data-hs-overlay-keyboard`	When set to `false`, the modal will not close when pressing the ESC button on the keyboard. Should be added to the overlay (content).	boolean	`true`

Classes Options

Name	Description	Options	Default value
`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. Should be added to the input inside the overlay (content).	—	—
`[--overlay-backdrop:*]`	When backdrop is set to `static`, the modal will not close when clicking outside it. Should be added to the overlay (content).	"static" \| null	`null`
`[--auto-hide:*]`	Milliseconds for auto-closing a modal.When set to `0`, the modal will not close. Should be added to the overlay (content).	number	`0`
`[--auto-close:*]`	Screen resolution at which the overlay will close automatically. Should be added to the overlay (content).	'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number	`null`
`[--opened:*]`	Screen resolution at which the plugin will apply functionality for the initially opened overlay. Should be added to the overlay (content).	'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. Should be added to the overlay (content).	boolean	`true`
`[--tab-accessibility-limited:*]`	Restricts focus to elements within an overlay (or modal). Should be added to the overlay (content).	"true" \| "false"	`true`
`[--has-autofocus:*]`	Disables autofocus on the first focusable element when opening an overlay. Should be added to the overlay (content).	"true" \| "false"	`true`
`[--is-layout-affect:*]`	Informs the plugin that the instance affects to the website layout. Should be added to the overlay (content).	"true" \| "false"	`false`

Selectors

Name	Description
`hs-overlay-animation-target`	Defines an element inside the popup, after the end of whose animation the popup will be completely hidden. Has no parameters.
`hs-overlay`	Defines overlays' content.

Tailwind Modifiers

Name	Description
`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.
`destroy()`	Destroys the instance, removes generated markup (if any), removes added classes and attributes.
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('[data-hs-overlay="#modal"]', true);

                        el.element.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 Components

Tailwind CSS Overlay

On this page