• overlays
  • Modal

overlays

Tailwind CSS Modal

A modal serves the purpose of presenting a dialog or box upon clicking a button.

Require FlyonUI JS
Class Name
Type
Description
overlayComponentCreate an overlay initalize instance.
modalComponentProvides structure and styling for the modal component.
modal-dialogPartBase class for modal content container.
modal-contentPartBase class for modal content.
modal-headerPartAdds basic style modal header.
modal-titlePartAdds basic style for modal title.
modal-bodyPartAdds basic style for modal body.
modal-footerPartAdds basic style for modal footer.
overlay-animation-targetModifierDefines an element within the popup. Once the animation of this element is complete, the popup will be fully hidden. This function does not take any parameters.
overlay-open:{tw-utility-class}VariantDefines classes will be applied to any elements inside the overlay when the it is open.
overlay-backdrop-open:{tw-utility-class}VariantDefines classes will be applied to backdrop when the overlay is open.
overlay-layout-open:{tw-utility-class}VariantDefines classes will be applied to any elements inside the body tag when the overlay is open.
modal-dialog-smSizeAdded to modal-dialog for small sized modal.
modal-dialog-mdSizeAdded to modal-dialog for medium (Default) sized modal.
modal-dialog-lgSizeAdded to modal-dialog for large sized modal.
modal-dialog-xlSizeAdded to modal-dialog for extra large sized modal.
modal-top-startPlacementMoves the modal to top-start position.
modal-topPlacementMoves the modal to top-center position.
modal-top-endPlacementMoves the modal to top-end position.
modal-middle-startPlacementMoves the modal to middle-start position.
modal-middlePlacementMoves the modal to middle-center position.
modal-middle-endPlacementMoves the modal to middle-end position.
modal-bottom-startPlacementMoves the modal to bottom-start position.
modal-bottomPlacementMoves the modal to bottom-center position.
modal-bottom-endPlacementMoves the modal to bottom-end position.

Basic examples

Default

Utilize the class overlay as the target for JavaScript to address the overlay component, and use the class modal for the overlay container. Use the Tailwind CSS display utility class hidden to keep the modal container hidden until it is opened.

Add modifier class overlay-open: with opacity class opacity-100 to both overlay container & component class modal-dialog so that it shows modal when opened.

Assign the value of the data-overlay attribute in any button to the id of the targeted overlay component, triggering the modal to appear upon being clicked.

The modal structure consists of the component class modal-dialog, which serves as the container for the modal content. Within this container, the component class modal-content encapsulates all the content of the modal.

This content is further styled using modifier classes such as modal-header, modal-title, modal-body and modal-footer, which collectively define the entire structure of the modal.

Utilize the provided example for basic modal.

Fullscreen

Utilize the provided example for a full screen modal.

Transparent

Utilize the provided example for a transparent modal.

Sizes

Size variants

Use the responsive classes modal-dialog-{size} with the modal-dialog component class to designate small, large, and extra-large modal sizes, where {size} can be replaced with sm, lg, or xl.

Utilize the provided example for a different sized modals.

Animated modals

Slide up modal

Use the overlay-open: modifier class along with margin utility classes to create modals with animation. Implement the provided example for a modal with a slide-up animation.

Apply the overlay-animation-target class to the target element to track its animation. The plugin will monitor all transitions of these elements and wait until they are complete before hiding the popup.

Slide down modal

Utilize the provided example for modal with slide down animation.

Scrolling behavior

Inside body

Utilize the given example to create a modal content that allows scrolling within its body.

Inside viewport

Utilize the provided example to implement modal content that remains within the viewport while scrolling.

The JavaScript part is necessary if you want the modal to close when clicking on the backdrop.

Placement

Positions

Utilize the responsive classes modal-{position} to position the modal in various positions, where {position} can be replaced with top-start, top, top-end, middle-start, middle, middle-end, bottom-start, bottom, or bottom-end.

Utilize the provided examples for placing modal in top-start, top(default) or top-end position.

Top

Middle

Utilize the provided examples for placing modal in middle-start, middle or middle-end position.

Bottom

Utilize the provided examples for placing modal in bottom-start, bottom or bottom-end position.

Illustrations

Toggle between modals

Utilize the provided example to implement modals that can be toggled between one another.

Modal with form

Utilize the provided example to implement modal with form.

Video modal (YouTube)

Utilize the provided example to incorporate a modal featuring a YouTube video.

Responsive

Use TailwindCSS classes for responsive design, such as sm:, md:, lg:, xl:, and 2xl:, along with the responsive class modal-{position} or modal-{size}, to switch the modal position or change sizes at specific breakpoints.

Utilize the provided example for a responsive modal that moves to bottom position after small breakpoint.

Destroy/Reinitialize

The destroy method is provided to facilitate the destruction of a modal element.

Options usage

Stacked overlays

In the trigger button, assign the value of the data-overlay-options attribute as an object. Within this object, set the isClosePrev key to false to keep the previous modal open, and set it to true to close the previous modal.

Utilize the provided example for stacked modals (overlays). In this scenario, the first two modals will close upon opening the third stacked modal, as isClosePrev is set to true for it which will close previous modals.

Focus management

Utilize the [--has-autofocus:{boolean}] option to manage autofocus within any modal. When set to false, it prevents the autofocus attribute from automatically assigning focus to any element within the modal. By default, its value is true.

Examine the provided example for focus management in modals.

Tab accessibility

Use the [--tab-accessibility-limited:{boolean}] option to manage Tab accessibility within overlay components. When set to false, it permits Tab navigation outside the modal to the entire browser, whereas when set to true, it confines Tab access within the modal only. By default, its value is true.

Examine the provided example for tab accessibility in modals.

Body scroll

Utilize the [--body-scroll:{boolean}] option to control the scrolling behavior of the layout beneath the overlay component. When set to true, it enables scrolling of the body, whereas when set to false, it disables body scrolling. By default, its value is false.

Examine the provided example for body scroll behavior in overlays.

Autohide

Utilize the [--auto-hide:{number}] option to enable the modal to automatically close itself after a specified duration of {number} milliseconds. Setting it to 0 will disable auto-closing. By default, its value is 0.

Examine the provided example for auto closing modal.

Custom backdrop

For customizing the backdrop, there are two methods available:

The first method involves using the backdrop modifier class overlay-backdrop-open:{custom-color}, where you can specify any color for the backdrop.

The second method entails assigning an object value to the data-overlay-options attribute in the trigger button. Within this object, set the backdropClasses key to transition duration-300 fixed inset-0 bg-success/70 overlay-backdrop to replace the existing backdrop classes with these customized ones.

To add additional classes to backdropClasses, use backdropExtraClasses. This will append the extra classes to the existing backdropClasses.

Examine the provided examples demonstrating both methods for setting the backdrop.

Keyboard control

Set the value of the data-overlay-keyboard attribute to false to disable the modal from closing when the Esc key is pressed. By default, this attribute’s value is true.

Examine the below given example for keyboard control in modals.

Layout affect

Utilize the [--is-layout-affect:{boolean}] option to inform plugin that overlay instance will affect site layout ..ie, it adds class overlay-body-open to the <body> of site if true. By default, its value is false.

When [--is-layout-affect:true], the overlay plugin enables customization of other layout components that are not part of the overlay component. This can be achieved by using the modifier class overlay-layout-open:{tw-utility-class}, where any custom class specified will be applied to the layout component when the overlay component is open.

Refer below example for layout affect in overlays.

Hidden class

In the trigger button, set the value of the data-overlay-options attribute to an object. Inside this object, specify the hiddenClass key as custom-class, which should be removed once the modal is opened. By default, it is set to the hidden class.

Refer below example for hiddenClass option usecase.

Autoclose & opened

The options [--auto-close:*] and [--opened:*], where * represents a number or breakpoints (sm, md, lg, xl, xxl), control the modal behavior upon window resizing. They determine whether the modal should automatically close on resize or remain open when the browser window is resized.

Configuring values at specific breakpoints or resolution levels enables this open-close behavior for the modal upon resizing.

Refer to the following examples to better understand the use cases of the autoclose and opened options when resizing the window .

Static backdrop

Here’s a more spaced-out and clearer version:

You can use the [--overlay-backdrop:{string}] option to control the modal backdrop behavior. The {string} can be set to static, false, or null. By default, the value is null.When set to static, the modal’s backdrop becomes unclickable, meaning the modal won’t close when clicking outside its area.

When using the static option, include the attribute data-overlay-keyboard="false" to disable closing the modal via the Esc key.

Here’s an example demonstrating how to create a static backdrop modal.

Disabled backdrop

When [--overlay-backdrop:{string}] is set to false, it creates a modal with a no backdrop.

JavaScript behavior

Options

PARAMETERS
DESCRIPTION
OPTIONS
DEFAULT VALUE
Data Options
data-overlayServes as a toggle button for the modal.--
data-overlay-optionsDefines the modal. Should be added to the button (trigger).--
:hiddenClassDefines which classes will be added/removed when modal toggle.stringhidden
:isClosePrevDetermines whether the previous open modal will be closed when the next one is opened.booleantrue
:emulateScrollbarSpaceIf true, then adds right padding to the body equal to the size of the scrollbar.booleanfalse
:backdropClassesDefines which classes will be added to the modals’ backdrop.stringtransition duration-300 fixed inset-0 bg-base-content/60 overlay-backdrop
:backdropExtraClassesAllows to add additional classes besides those specified in backdropClasses.string-
:backdropParentAllows to specify the selector of the element where the backdrop will be generated.string-
:moveOverlayToBodyMoves the overlay to the body tag if the screen width is less than the value specified.number / nullnull
data-overlay-backdrop-containerBackdrop element selector.-null
data-overlay-keyboardWhen set to false, the modal will not close when pressing the ESC button on the keyboard.booleantrue
Class Options
autofocusFocus 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. When set to false the backdrop will be disabled.‘static’, null, ‘false’null
[--auto-hide:*]Milliseconds for auto-closing a modal. When set to 0, the modal will not close.number0
[--auto-close:*]Screen resolution at which the overlay will close automatically.‘sm’, ‘md’, ’lg’, ‘xl’, ‘xxl’, numbernull
[--auto-close-equality-type:*]This option controls when the overlay closes based on window width. “Less-than” closes it when the width is ≤ [--auto-close:], otherwise it closes when the width ≥ [--auto-close:].Add to the overlay content.’less-than’/nullnull
[--opened:*]Screen resolution at which the plugin will apply functionality for the initially opened overlay.‘sm’, ‘md’, ’lg’, ‘xl’, ‘xxl’, numbernull
[--body-scroll:*]When set to false, the body scroll will be hidden as soon as the modal opens.booleantrue
[--tab-accessibility-limited:*]Restricts focus to elements within an overlay (or modal).booleantrue
[--has-autofocus:*]Disables autofocus on the first focusable element when opening an overlay.booleantrue
[--has-dynamic-z-index:*]When set to true, each new element in the group gets an incremented z-index, ensuring it appears above previous elements. Add to the overlay content.booleanfalse
[--is-layout-affect:*]Informs the plugin that the instance affects to the website layout.booleanfalse

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.

Method usage

Here’s a demonstration of how to utilize methods on overlays such as modals and drawers. To test other methods, just copy them into your browser’s console and then click the Open modal using methods button.

Open item (public method).

<button class="--prevent-on-load-init" data-overlay="#id">
...
</button>

// This method is used in above example.
const modal = new HSOverlay(document.querySelector('#modal-target'));
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-target');
});

Open item (mixed).

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

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

Destroy Instance(public).

const modals = document.querySelectorAll('[data-overlay="#destroy-modal"]')
const destroy = document.querySelector('#destroy-btn')

destroy.addEventListener('click', () => {
  modals.forEach(el => {
    const { element } = HSOverlay.getInstance(el, true)
    element.destroy()
  })
})

Events

METHOD
DESCRIPTION
on:openCalled when modal is open.
on:closeCalled when modal is closed.

Event usage

Here’s a demonstration of how to utilize events on overlays like modals and drawers. To test these events, just copy them into your browser’s console and see the output in the console when the modal opens and closes.

Open any overlay event example.

const { element } = HSOverlay.getInstance('#modal-target-2', true)

element.on('open', instance => { console.log('open') })
element.on('close', instance => { console.log('close') })