Use Modal components to create a dialog box overlay on top of the main content, temporarily blocking interaction with the rest of the application until the modal is closed. They’re useful for drawing the user’s attention to important information or tasks. Use them for alerts and notifications, confirmation dialogs, forms and input, content display, or for interacive tasks.
Preview
Once you created a Modal component, you can trigger it by calling the modal function with either a selector that targets the Modal component, or a configuration object. You can open modals in two different ways:
Open: Pass a configuration object with a trigger property that specifies a query selector for a trigger element, and pass a modal property to target the Modal component. Clicking on the trigger element will now open the component. The Astro example follows this approach.
Open via JS: Pass a query selector to the modal function that targets the component, and assign the function to a variable. You can call the open method on the assigned variable. This lets you trigger the component programmatically, for example, after a network request finishes. This approach is used in the Svelte/React examples above.
Titles
Modals can be configured to have titles and subtitles by using the title and subTitle props:
Configuring Close
A modal can be closed in four different ways. Using the close icon, clicking on the overlay, hitting the esc key on the keyboard, or calling the closeModal function from JavaScript. For example, the following modal can only be closed with the “Close” button inside the modal.
By default, every close option is enabled due to accessibility. Only disable these options if you’d like your users to take mandatory actions before navigating away.
Themes
Modals can also be created with four predefined themes: info, success, warning, and alert. To change the theme of your modal, set the theme prop:
Modal Events
When calling the modal function, you can also optionally pass an onOpen and onClose property to the configuration object to listen to open and close events:
Both methods has access to an object with the following properties:
trigger: The DOM node for the trigger element. This can be null if the modal was created without the trigger property, and instead, modalInstance.open is used as a means to reveal the modal.
modal: The DOM node for the Modal component.
API
Prop
Purpose
title
Set a title for the modal.
subTitle
Set a subtitle for the modal.
showCloseIcon
Shows a close icon in the top-right corner of the modal. Defaults to true.
closeOnEsc
Makes the modal closable by hitting the esc key. Defaults to true.
closeOnOverlay
Makes the modal closable by clicking on the overlay. Defaults to true.
id
Pass an ID for the modal.
className
Pass additional CSS classes for the modal.
theme
Set the theme of your modal. Can be one of info, success, warning, alert.
Property
Purpose
config.trigger
Query selector that targets the trigger element.
config.modal
Query selector that targets the Modal component.
config.onOpen
Callback function executed after a modal is opened.
config.onClose
Callback function executed after a modal is closed.