Modal
Dialog boxes overlay on top of the main content
Source ↗️ Report Issue ↗️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.
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 amodal
property to target theModal
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 theopen
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:
Transparent Modals
The Modal
component can also receive a transparent
prop that can make the modal transparent. This can be used to display components in a modal without the modal’s background, for example to block interactions with a loading indicator:
Spinner
component here. 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 benull
if the modal was created without thetrigger
property, and instead,modalInstance.open
is used as a means to reveal the modal.modal
: The DOM node for theModal
component.
API
Prop | Default | Purpose |
---|---|---|
title | - | Set a title for the modal. |
subTitle | - | Set a subtitle for the modal. |
showCloseIcon | true | Shows a close icon in the top-right corner of the modal. |
closeOnEsc | true | Makes the modal closable by hitting the esc key. |
closeOnOverlay | true | Makes the modal closable by clicking on the overlay. |
transparent | false | Sets the modal to transparent, removing background, borders, and padding. |
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. |
instance.open | Open the modal programmatically. |
instance.remove | Remove the event listeners created for the modal. |
Request improvement for this page