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

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