Overlays

Modal

A modal is used to display a dialog or popup box that appears in response to a user action, typically after clicking a button.

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.

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

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.

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.

Placement

Positions — Top

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

Positions — Middle

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

Positions — 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 <a href="https://tailwindcss.com/docs/responsive-design#targeting-a-breakpoint-range" target="_blank" class="link link-primary">responsive design</a>, 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.

Destroy/Reinitialize

The `destroy` <a href="#destroy-method" class="link link-primary">method</a> 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.

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

Tab accessibility

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

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

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

Custom backdrop

For customizing the backdrop, there are two methods available:

Keyboard control

By default a modal closes when the <kbd class="kbd kbd-sm">Esc</kbd> key is pressed — open the dialog and hit Esc to dismiss it. Set the `data-overlay-keyboard` attribute to `false` to disable this behaviour.

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

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.

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.

Static backdrop

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

Disabled backdrop

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

JavaScript behavior

Methods — Method usage

The `HSOverlay` object is contained within the global `window` object.

JavaScript

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 — Event usage

METHOD| DESCRIPTION `on:open`| Called when modal is open. `on:close`| Called when modal is closed.

JavaScript

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

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

Class referenceThe component, style, color, state, size and modifier classes available for this component.

Class	Type	Description
`overlay`	component	Create an overlay initalize instance.
`modal`	component	Provides structure and styling for the modal component.
`modal-dialog`	part	Base class for modal content container.
`modal-content`	part	Base class for modal content.
`modal-header`	part	Adds basic style modal header.
`modal-title`	part	Adds basic style for modal title.
`modal-body`	part	Adds basic style for modal body.
`modal-footer`	part	Adds basic style for modal footer.
`overlay-animation-target`	modifier	Defines 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}`	variant	Defines classes will be applied to any elements inside the overlay when the it is open.
`overlay-backdrop-open:{tw-utility-class}`	variant	Defines classes will be applied to backdrop when the overlay is open.
`overlay-layout-open:{tw-utility-class}`	variant	Defines classes will be applied to any elements inside the body tag when the overlay is open.
`overlay-minified:{tw-utility-class}`	variant	Defines classes will be applied to any elements inside the body tag when the overlay is minfied (example: collapsible sidebar).
`modal-dialog-sm`	size	Added to modal-dialog for small sized modal.
`modal-dialog-md`	size	Added to modal-dialog for medium (Default) sized modal.
`modal-dialog-lg`	size	Added to modal-dialog for large sized modal.
`modal-dialog-xl`	size	Added to modal-dialog for extra large sized modal.
`modal-top-start`	placement	Moves the modal to top-start position.
`modal-top`	placement	Moves the modal to top-center position.
`modal-top-end`	placement	Moves the modal to top-end position.
`modal-middle-start`	placement	Moves the modal to middle-start position.
`modal-middle`	placement	Moves the modal to middle-center position.
`modal-middle-end`	placement	Moves the modal to middle-end position.
`modal-bottom-start`	placement	Moves the modal to bottom-start position.
`modal-bottom`	placement	Moves the modal to bottom-center position.
`modal-bottom-end`	placement	Moves the modal to bottom-end position.