Modal

Dialog boxes overlay on top of the main content

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

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

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

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:

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:

<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:

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

type ModalProps = {
    title?: string
    subTitle?: string
    showCloseIcon?: boolean
    closeOnEsc?: boolean
    closeOnOverlay?: boolean
    transparent?: boolean
    id?: string
    className?: string
    theme?: 'info'
        | 'success'
        | 'warning'
        | 'alert'
}

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

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

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.

<- Menu Pagination ->

Request improvement for this page

Modal

Titles

Configuring Close

Themes

Transparent Modals

Modal Events

API