Modal

Overview

Modals display information in a window or help a user focus on a task without navigating them away from the page. A user can’t perform other actions until the modal is dismissed.

Installation

npm install @patternfly/pfe-modal

Usage

With a trigger

The trigger slot can be used with a trigger element, like a button, to provide a mechanism to open a modal without any additional JavaScript.

<pfe-modal>
  <button slot="trigger">Open modal</button>
  <h2 slot="header">Modal with a header</h2>
  <p>Lorem ipsum dolor sit amet, <a href="#foo">consectetur adipisicing</a> elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
  <pfe-cta>
    <a href="#bar">Learn more</a>
  </pfe-cta>
</pfe-modal>

Without a trigger

Using pfe-modal without utilizing the trigger slot requires additional JavaScript to programmatically open a modal. Uses for this type of modal are meant for scenarios where a modal needs to be programmatically triggered: a user is being logged out, a user needs to accept terms before continuing, etc.

<pfe-modal>
  <h2 slot="header">Modal with a header</h2>
  <p>Lorem ipsum dolor sit amet, <a href="#foo">consectetur adipisicing</a> elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
  <pfe-cta>
    <a href="#bar">Learn more</a>
  </pfe-cta>
</pfe-modal>

Slots

Default Slot

The default slot can contain any type of content. When the header is not present this unnamed slot appear at the top of the modal window (to the left of the close button). Otherwise it will appear beneath the header.

trigger

The only part visible on page load, the trigger opens the modal window. The trigger can be a button, a cta or a link. While it is part of the modal web component, it does not contain any intrinsic styles.

header

The header is an optional slot that appears at the top of the modal window. It should be a header tag (h2-h6).

Attributes

width

The width controls the width of the modal. There are three options: small, medium and large. The default is large.

DOM Property

width

Type

'small' | 'medium' | 'large'

Default

'large'

open

DOM Property

open

Type

boolean

Default

false

trigger

Optional ID of the trigger element

DOM Property

trigger

Type

string | undefined

Default

unknown

DOM Properties

returnValue

Type

string | undefined

Default

unknown

Methods

setTrigger(element: HTMLElement)

toggle()

Manually toggles a modal.

document.querySelector('pfe-modal').toggle();

show()

Manually opens a modal.

document.querySelector('pfe-modal').open();

showModal()

close(returnValue: string)

Manually closes a modal.

document.querySelector('pfe-modal').close();

Events

open

Fires when a user clicks on the trigger or manually opens a modal.

Event Type:

ModalOpenEvent

close

Fires when either a user clicks on either the close button or the overlay or manually closes a modal.

Event Type:

ModalCloseEvent

CSS Custom Properties

CSS Shadow Parts

overlay

The modal overlay which lies under the dialog and above the page body

dialog

The dialog element

content

The container for the dialog content

close-button

The modal's close button