Modal

A modal is a surface that overlays the page’s main content and is used to display information, gather input or confirm actions.

Overview

pie-modal is a Web Component built using Lit. It offers a simple and accessible modal component for web applications, which uses the native HTML dialog element under the hood.

This component can be easily integrated into various frontend frameworks and customised through a set of properties.

Installation

To install pie-modal in your application, run the following on your command line:

npm i @justeattakeaway/pie-webc

yarn add @justeattakeaway/pie-webc

Props

Prop	Options	Description	Default
aria		An object representing the aria labels for the `close` and `back` buttons within the modal as well as the `isLoading` state labels (`aria-label` & `aria-busy`).
hasBackButton	`true` `false`	If true, the modal includes a back button which closes the modal when clicked.	`false`
hasStackedActions	`true` `false`	If true, the action buttons will be stacked (full width) at narrow breakpoints.	`false`
heading		The heading text of the modal.
headingLevel	`h1` `h2` `h3` `h4` `h5` `h6`	The HTML tag to use for the modal's heading.	`h2`
isDismissible	`true` `false`	If true, the modal includes a close button and can be dismissed by clicking on the backdrop or pressing the `Esc` key.	`false`
isFooterPinned	`true` `false`	When false, the modal footer will scroll with the content inside the modal body.	`true`
isFullWidthBelowMid	`true` `false`	If true and the page is narrower than the mid breakpoint, a medium-sized modal will take up the full width of the screen.	`false`
isLoading	`true` `false`	When true, displays a loading spinner in the modal.	`false`
isOpen	`true` `false`	Controls if the modal element is open or closed.	`false`
`leadingAction.text`	-	The text to display inside the leading action button. The button won't render without this.
`leadingAction.variant`	See pie-button's variants	The variant of the leading action button.	`"primary"`
`supportingAction.text`	-	The text to display inside the supporting action button. The button won't render without this.
`supportingAction.variant`	See pie-button's variants	The variant of the supporting action button.	`"ghost"`
position	`"center"` `"top"`	The position of the modal; this controls where it will appear on the page.	`"center"`
returnFocusAfterCloseSelector		If provided, focus will be sent to the first element that matches this selector when the modal is closed. If not provided, the `dialog` element will return focus to the element that opened the modal.
size	`"small"` `"medium"` `"large"`	Determines the maximum width of the modal. Large modals will expand to fill the entire page at narrow viewports.	`"medium"`

Events

Event	Type	Description
`pie-modal-open`	`CustomEvent`	Triggered when the modal is opened.
`pie-modal-close`	`CustomEvent`	Triggered when the modal is closed.
`pie-modal-back`	`CustomEvent`	Triggered when the modal back button is clicked.
`pie-modal-leading-action-click`	`CustomEvent`	Triggered when the modal leading action is clicked.
`pie-modal-supporting-action-click`	`CustomEvent`	Triggered when the modal supporting action is clicked.

Legacy browser support

pie-modal uses the Dialog element which might not be supported by legacy browsers.

To support them, pie-modal uses the dialog-polyfill package. It works automatically and doesn't need any setup.

The polyfill comes with a few limitations, as noted on its documentation page:

Dialogs should not be contained by parents that create a stacking context

The browser's chrome may not always be accessible via the tab key
Changes to the CSS top/bottom values while open aren't retained
For more details, check the package documentation mentioned above.

Examples

For HTML:

// import as module into a js file e.g. main.js
import '@justeattakeaway/pie-webc/components/modal.js'

<!-- pass js file into <script> tag -->
<pie-modal heading='My Awesome Heading' headingLevel='h3'>Click me!</pie-modal>
<script type="module" src="/main.js"></script>

For Native JS Applications, Vue, Angular, Svelte etc.:

// Vue templates (using Nuxt 3)
import '@justeattakeaway/pie-webc/components/modal.js';

<pie-modal heading="My Awesome Heading" headingLevel="h3">Click me!</pie-modal>

For React Applications. When using the React version of the component, please make sure you also include React as a dependency in your project as well. See Peer Dependencies section.

import { PieModal } from '@justeattakeaway/pie-webc/react/modal.js';

<PieModal heading='My Awesome Heading' headingLevel='h3'>Click me!</PieModal>