Skip to main content

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

GitHub Workflow Status

pie-modal is a Web Component built using the Lit library. 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 customized through a set of properties.


Installation

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

# npm
$ npm i @justeattakeaway/pie-modal
# yarn
$ yarn add @justeattakeaway/pie-modal

Playground


Props

PropOptionsDescriptionDefault
ariaAn object representing the aria labels for the close & back buttons within the modal as well as the isLoading state labels (aria-label & aria-busy).
hasBackButtontrue
false
If true, the modal includes a back button which closes the modal when clicked.false
hasStackedActionsfalse
true
If true, the action buttons will be stacked (full width) at narrow breakpoints.false
headingThe heading text of the modal.
headingLevelh1
h2
h3
h4
h5
h6
The HTML tag to use for the modal's headingh2
isDismissibletrue
false
If true, the modal includes a close button and can be dismissed by clicking on the backdrop or pressing the Esc key.false
isFooterPinnedfalse
true
When false, the modal footer will scroll with the content inside the modal body.true
isFullWidthBelowMidfalse
true
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
isLoadingfalse
true
When true, displays a loading spinner in the modalfalse
isOpenfalse
true
Controls if the modal element is open or closedfalse
leadingActionAn object representing the leading action of the modal.
positiontop
center
The position of the modal; this controls where it will appear on the page.center
returnFocusAfterCloseSelectorIf 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.
sizesmall
medium
large
Determines the maximum width of the modal. Large modals will expand to fill the entire page at narrow viewports.medium
supportingActionAn object representing the supporting action of the modal.

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-modal'
<!-- 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-modal';

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

// React templates (using Next 13)
import { PieModal } from '@justeattakeaway/pie-modal/dist/react';

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

Changelog