Tailwind CSS Overlay Plugin API

Headless, unstyled Overlay plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

Installation

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

Terminal

                        
                          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/50 dark:bg-neutral-900/80`
`: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`
`[--auto-close-equality-type:*]`	This option determines the condition under which an overlay should automatically close based on the window's width. When set to `less-than`, the overlay will close if the window's width is less than or equal to the value defined in the `[--auto-close:]` option. Otherwise the overlay will close if the window's width is greater than or equal to the `[--auto-close:]` threshold. Should be added to the overlay (content).	'less-than' \| null	`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`
`[--has-dynamic-z-index:*]`	When set to `true`, each newly opened element in the group will receive an incremented `z-index` inline, ensuring it appears above previously opened elements with the same base `z-index`. Should be added to the overlay (content).	"true" \| "false"	`false`
`[--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.
`updateToggles()`	Updates the toggle buttons.
`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 { element } = HSOverlay.getInstance('#modal', true);

                        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 Plugin API

On this page