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 from Artifactory

• Verify that you have access to (https://docs.int.bayer.com/cloud/devops/artifactory/)[Bayer Artifactory]
  • Verify your token is correctly set up in your .npmrc as per the link above
• Verify you have the @element scope configured in your .npmrc
  • @element:registry=https://artifactory.bayer.com/artifactory/api/npm/npm-platforms-engineering/
• Install the component and themes bundles
  • npm i @element/react-components @element/themes
    • alternatively install the component individually along with the themes bundle npm i @element/react-modal @element/themes

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. | | preventPrimaryAccept | boolean | false | false | Prevents the default behavior which adds an event listener for the Enter key to the Primary button. Any onEnter/submission behavior will need to be added by the developer (including closing the Modal). | | 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. |