1. Plugins
  2. Overlay

Plugins

Tailwind CSS Overlay

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

Overlay

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>
                      
                    

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

Plugins UI Mockups
Check out Preline UI Components