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 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
Prop | Options | Description | Default |
---|---|---|---|
aria | An object representing the aria labels for the close & 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 | false true | 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 | false true | When false, the modal footer will scroll with the content inside the modal body. | true |
isFullWidthBelowMid | false 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 |
isLoading | false true | When true, displays a loading spinner in the modal | false |
isOpen | false true | Controls if the modal element is open or closed | false |
leadingAction | An object representing the leading action of the modal. | ||
position | top center | 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 |
supportingAction | An 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>