@element-public/react-modal

Modal

Description

Modals are a window that appears in front of application or page content. They can contain longer content or forms than Dialog. All page functionality ceases until the modal is closed.

See live demos on storybook

Storybook Modal Demos

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-modal @element-public/themes

Please Note: You will need to add @element-public to your .npmrc!

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:

npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

Notes

Modals appear in front of a page to display other information temporarily. All page functionality behind the Modal window ceases until the Modal is closed. A Modal can be opened or closed with a Button or an Icon Button.

Usage

The Modal component can include many other components, such as Buttons, Icon Buttons, Textfield, and Stepper Indicator. For example, in the 'Basic' Modal story, the Modal includes various Icon Buttons and in the 'Form in Modal' story, the Modal includes a form with Buttons, Icon Buttons, and a Textfield to take user input. Other examples and use cases are shown in Storybook stories.

Modal is similar to Dialog but differs in that Modal can display more content than Dialog, which is usually a smaller window.

The Dialog component will be removed in a future version, but setting modalSize="dialog" will give all the features and size of a Dialog using the Modal component.

Modal Props

Name	Type	Default	Required	Description
defaultButton	string	'primary'	false	Button that is the default action, triggered by pressing the Enter key. Accepted Values: close, primary, action, footerSupplemental
hideCloseIcon	boolean	false	false	If true, the close icon in the upper left corner will not be rendered.
initialFocus	string	null	false	Button to initially focus on after the dialog has opened. If left null, the initial focus will be on the first focusable element in the modal. As an alternative you can add data-mdc-dialog-initial-focus to any element within the modal to make that element the initial focus. If it is a directional modal, the initial focus will be on the nextButton. Accepted Values: null, primary, action, footerSupplemental
mobileStackedButtons	boolean	false	false	If true, the buttons in the footer will be full width and stacked on mobile.
modalSize	string	'max'	false	String to determine the size of the modal. Accepted Values: fullscreen, max, xlarge, large, medium, small, dialog
noActions	boolean	null	false	Set to true if the modal will not have any actions. Should be used sparingly and the modal should be closed programmatically. For example, can be used to stop the user from interacting or navigating away while a payment is processing.
open	boolean	false	false	If true, the Modal will be visible on screen.
preventClose	boolean	false	false	Prevents the user from closing the dialog by hitting escape or clicking the scrim. Use caution when using this as the modal should always have a way for the user to close it.
returnFocusSelector	string	null	false	DOM selector to provide a target to return focus. Accepts any valid query (see mdn docs for Element.querySelector). If omitted focus will return to the last focused element upon closing.
scrollable	boolean	false	false	If true, wrapping will be disabled and a scrollable area will be created.
title	string	null	false	String for the modal title.

Modal Render Props

Name	Type	Default	Required	Description
actionButton	React.ReactNode	null	false	An action button that will not automatically trigger a dismiss or accept. It is meant to be used only in certain circumstances where more control of the modal is required such as validating forms. If primaryButton is sent with actionButton, actionButton will be ignored.
backButton	React.ReactNode	null	false	Button for any navigating to the previous page in a Directional modal.
badge	React.ReactNode	undefined	false	The custom modal label badge to be rendered.
children	React.ReactNode	null	false	Accepts any valid markup. Optionally, content may be used instead. If content and children are both set, content will take priority.
content	React.ReactNode	null	false	Primary content of the dialog. Accepts any valid markup. Optionally, children may be used instead. If content and children are both set, content will take priority.
dismissiveButton	React.ReactNode	null	false	Button to cancel or close the modal.
footerSupplemental	React.ReactNode	null	false	Button to be displayed in left corner of the modal footer. Should be a text button.
headerActions	React.ReactNode	null	false	Content to be displayed in right corner of the modal header. Should be a text button or a group of up to 3 icon buttons.
indicator	React.ReactNode	null	false	A slot for StepperIndicator.
nextButton	React.ReactNode	null	false	Button for navigating to the next page in a Directional modal or closing on the last page.
primaryButton	React.ReactNode	null	false	Button for the primary action of the modal.

Modal Events

Name	Default	Required	Params	Description
onClose	null	false	1. Name: event, Type: object, Description: The javascript event	Fired when the Dialog begins its closing animation. Where event.detail.action is the action which closed the dialog (close or accept).
onClosed	null	false	1. Name: event, Type: object, Description: The javascript event	Fired when the Dialog finishes its closing animation. Where event.detail.action is the action which closed the dialog (close or accept).
onOpen	null	false		Fired when the Dialog begins its opening animation.
onOpened	null	false		Fired when the Dialog finishes its opening animation.

Modal Breaking Changes

Description
actionIcons (removed): No longer needed. Use headerActions instead.
size (removed): See modalSize instead.
supplementalButton (removed): No longer needed. Use headerActions for a supplemental button in the header and footerSupplemental for a supplemental button in the footer.
type (removed): No longer needed. Use the render props or Slots in Vue for different button placement.