Search documentation v0.6.1

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.

Preview
How to use Modals in Astro
---
import { Button, Modal } from 'webcoreui/astro'
---
<Button className="button">Show modal</Button>
<Modal className="modal">
Modal with text only.
</Modal>
<script>
import { modal } from 'webcoreui'
modal({
trigger: '.button',
modal: '.modal'
})
</script>
How to use Modals in Svelte
<script>
import { onMount } from 'svelte'
import { Button, Modal } from 'webcoreui/svelte'
import { modal } from 'webcoreui'
let modalInstance
onMount(() => {
modalInstance = modal('.modal')
})
</script>
<Button onClick={() => modalInstance.open()}>
Show modal
</Button>
<Modal className="modal">
Modal with text only.
</Modal>
How to use Modals in React
import React, { useState, useEffect } from 'react'
import { Button, Modal } from 'webcoreui/react'
import { modal } from 'webcoreui'
const Component = () => {
const [modalInstance, setModalInstance] = useState(null)
useEffect(() => {
setModalInstance(modal('.modal'))
}, [])
return (
<React.Fragment>
<Button onClick={() => modalInstance.open()}>
Show modal
</Button>
<Modal className="modal">
Modal with text only.
</Modal>
</React.Fragment>
)
}
export default Component

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:

  1. 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.
  2. 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:

<Modal
title="Information"
subTitle="Before continuing, please read carefully"
>
<p>This modal was created with the <code>title</code> and <code>subTitle</code> props.</p>
</Modal>

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.

---
import { Button, Modal } from 'webcoreui/astro'
---
<Button className="button">Show modal with close button</Button>
<Modal
className="modal"
title="Alert"
subTitle="This modal can only be closed with the button below."
showCloseIcon={false}
closeOnEsc={false}
closeOnOverlay={false}
>
<p>...</p>
<Button className="close">Close modal</Button>
</Modal>
<script>
import { modal, closeModal } from 'webcoreui'
modal({
trigger: '.button',
modal: '.modal'
})
const closeButton = document.querySelector('.close')
closeButton.addEventListener('click', () => closeModal('.modal'))
</script>
<script>
import { onMount } from 'svelte'
import { Button, Modal } from 'webcoreui/svelte'
import { modal, closeModal } from 'webcoreui'
let modalInstance
onMount(() => {
modalInstance = modal('.modal')
})
</script>
<Button onClick={() => modalInstance.open()}>
Show modal with close button
</Button>
<Modal
className="modal"
title="Alert"
subTitle="This modal can only be closed with the button below."
showCloseIcon={false}
closeOnEsc={false}
closeOnOverlay={false}
>
<p>...</p>
<Button onClick={() => closeModal('.modal')}>Close modal</Button>
</Modal>
import React, { useState, useEffect } from 'react'
import { Button, Modal } from 'webcoreui/react'
import { modal, closeModal } from 'webcoreui'
const Component = () => {
const [modalInstance, setModalInstance] = useState(null)
useEffect(() => {
setModalInstance(modal('.modal'))
}, [])
return (
<React.Fragment>
<Button onClick={() => modalInstance.open()}>
Show modal with close button
</Button>
<Modal
className="modal"
title="Alert"
subTitle="This modal can only be closed with the button below."
showCloseIcon={false}
closeOnEsc={false}
closeOnOverlay={false}
>
<p>...</p>
<Button onClick={() => closeModal('.modal')}>Close modal</Button>
</Modal>
</React.Fragment>
)
}
export default Component

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
className="info-modal"
title="Information"
subTitle="Before continuing, please read carefully"
theme="info"
>
<p>This modal was created with <code>theme</code> set to <code>info</code>.</p>
</Modal>
<Modal
className="success-modal"
title="Success"
subTitle="Before continuing, please read carefully"
theme="success"
>
<p>This modal was created with <code>theme</code> set to <code>success</code>.</p>
</Modal>
<Modal
className="warning-modal"
title="Warning"
subTitle="Before continuing, please read carefully"
theme="warning"
>
<p>This modal was created with <code>theme</code> set to <code>warning</code>.</p>
</Modal>
<Modal
className="alert-modal"
title="Alert"
subTitle="Before continuing, please read carefully"
theme="alert"
>
<p>This modal was created with <code>theme</code> set to <code>alert</code>.</p>
</Modal>

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:

<Modal
className="loading-modal"
showCloseIcon={false}
transparent={true}
>
<Spinner
width={5}
size={50}
/>
</Modal>
You can read more about the documentation of the Spinner component here.

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:

modal({
trigger: '.trigger',
modal: '.modal',
onOpen: ({ trigger, modal }) => {
console.log('Modal opened')
},
onOpen: ({ trigger, modal }) => {
console.log('Modal closed')
}
})

Both methods has access to an object with the following properties:

API

type ModalProps = {
title?: string
subTitle?: string
showCloseIcon?: boolean
closeOnEsc?: boolean
closeOnOverlay?: boolean
transparent?: boolean
id?: string
className?: string
theme?: 'info'
| 'success'
| 'warning'
| 'alert'
}
PropDefaultPurpose
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.
JavaScript API
type Event = {
trigger: Element | null
modal: HTMLElement
}
type Modal = {
trigger: string
modal: string
onOpen?: (event: Event) => unknown
onClose?: (event: Event) => unknown
}
const modal: (config: Modal | string) => {
open: () => void
remove: () => void
} | void
const closeModal: (modal: string) => void
PropertyPurpose
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

Modal with text only. Close by clicking on the X icon, on the overlay, or hitting esc on your keyboard.

Information
Before continuing, please read carefully

This modal was created with the title and subTitle props.

Alert
This modal can only be closed with the button below.

The default close options have been disabled. You can only close the modal by using the button below.

Information
Before continuing, please read carefully

This modal was created with theme set to info.

Success
Before continuing, please read carefully

This modal was created with theme set to success.

Warning
Before continuing, please read carefully

This modal was created with theme set to warning.

Alert
Before continuing, please read carefully

This modal was created with theme set to alert.