Dialog

Description

Dialogs inform users about a task and can contain critical information, require decisions, or involve multiple tasks. A dialog is a type of modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.

See live demos on storybook

Storybook Dialog 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-dialog @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

A notable prop for Dialog is preventClose which prevents the user from closing the dialog by hitting escape or clicking the scrim. This limits the use of Dialog to forcing the user to click a button to close the window, instead of navigating the window with keyboard input.

Usage

Dialogs are often used with other components, like a Button to open or close the Dialog window or a selection input, like Radio or Checkbox, to gather data within the Dialog window.

Dialog Props

| Name | Type | Default | Required | Description | | ------------------- | ------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | className | string | undefined | false | The css class name to be passed through to the component markup. | | contentId | string | empty string | false | Custom id for the content container. If one is not specified a random id will be generated. | | headerId | string | empty string | false | Custom id for the header container. If one is not specified a random id will be generated. | | open | boolean | false | false | If true, the dialog will be visible on screen. | | preventClose | boolean | false | false | Prevents the user from closing the dialog by hitting escape or clicking the scrim. | | 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. | | stackedButtons | boolean | false | false | If true, the cancel button will be rendered beneath the accept button instead of side-by-side. Stacking of buttons happens automatically in cases where the button text is too long for all buttons to fit on a single line. Setting this prop to true is only required if you want to override this behavior. |

Dialog Render Props

| Name | Type | Default | Required | Description | | ------------ | --------------- | ------- | -------- | -------------------------------------------------------------------------------------- | | acceptButton | React.ReactNode | null | false | Button for the approving action of the dialog. When pressed, the dialog will close. | | actions | React.ReactNode | null | false | slot/element for adding action buttons | | cancelButton | React.ReactNode | null | false | Button for the cancel/close action of the dialog. When pressed, the dialog will close. | | content | React.ReactNode | null | false | Primary content of the dialog. Optional, children may be used instead. | | header | React.ReactNode | null | false | Title information displayed at the top of the dialog. |

Dialog Events

| Name | Default | Required | Params | Description | | --------- | ------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------- | | onAction | null | false | | Fired only when the closing action was triggered via dialog interaction. | | onClosed | null | false | | Fired when the Dialog finishes its closing animation. Where action is the action which closed the dialog. | | onClosing | null | false | | Fired when the dialog begins its closing animation. action represents the action which closed the dialog. | | onOpened | null | false | | Fired when the dialog finishes its opening animation. | | onOpening | null | false | | Fired when the dialog begins its opening animation. |

Dialog Breaking Changes

| Description | | ---------------------------------------------- | | dialogButton (removed): Use actions instead. | | onClose (removed): Renamed to onClosing. |

Dialog Action Props

| Name | Type | Default | Required | Description | | ------- | ------------------------------------------ | ------------ | -------- | ------------------------------------ | | action | string | empty string | false | Dialog action | | focused | boolean | null | false | Focus element on dialog upon open | | tag | string|React.ElementType|React.Component | 'div' | true | Base component that will be rendered |

Dialog Action Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ----------- | | children | React.ReactNode | null | false | children |

Dialog Action Breaking Changes

| Description | | -------------------------------------- | | component (removed): Renamed to tag. |

Dialog Button Props

| Name | Type | Default | Required | Description | | ------------ | ------------------------------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | buttonSize | string | 'themeDefault' | false | One of 'xsmall', 'small', 'medium', 'large' and 'xlarge' will change the size of the button. Defaults according to your theme.Accepted Values: xsmall, small, medium, large, xlarge, themeDefault | | className | string | undefined | false | The css class name to be passed through to the component markup. | | disabled | boolean | false | false | Prevent the user from interacting with the component. | | elevation | string | 'default' | false | Sets elevation of the button. Default will be the theme default.Accepted Values: default, elevated, flat | | fullWidth | boolean | false | false | Applies a full-width style where the textfield will fill it's container. | | href | string | null | false | The button will render as an anchor tag. If the tag prop is set, that prop will take precedence. | | label | string | null | false | The displayed text. Expects a valid string. If label and children are both set, label will take priority. | | leadingIcon | string|function|React.ReactNode | undefined | false | Adds the given Icon to the left of the button text. May not be used with trailingIcon - if leadingIcon and trailingIcon are both set, leadingIcon will take priority. Expects the name of a valid Material.io icon, however an icon component may be passed in instead for more control, | | tag | string|React.ElementType|React.Component | null | false | By default a button or anchor tag will be rendered, this allows another tag/component to be used instead. A block type element/component is suggested. | | themeColor | string | 'primary' | false | Sets the theme color for the button. Most commonly used when the control is placed on a darker surface.Accepted Values: primary, secondary, danger, success, on-unknown-black, on-unknown-white, on-primary, on-secondary, on-success, on-dangerDeprecated Values: onUnknownBlack, onUnknownWhite | | trailingIcon | string|function|React.ReactNode | undefined | false | Adds the given Icon to the right of the button text. May not be used with leadingIcon - if leadingIcon and trailingIcon are both set, leadingIcon will take priority. Expects the name of a valid Material.io icon, however an icon component may be passed in instead for more control. | | type | string | 'button' | false | This applies the html button type (button, submit, reset) or the anchor media type when used with the href property.Accepted Values: button, submit, reset | | variant | string | 'filled' | false | Applies the selected style to the button. rounded-small and rounded-micro are only available on select themes.Accepted Values: filled, outlined, danger, text, success, rounded-small, rounded-micro |

Dialog Button Deprecated Props

| Name | Type | Default | Required | Deprecated | Description | | ---------- | --------- | --------- | -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | altColor | boolean | undefined | false | Use themeColor='secondary' instead. | Preview feature, this may change. Apply alternative button color scheme (defined by the individual theme). | | customRef | reference | undefined | false | forwardRef has been implemented for Button. | Reference to the DOM button. This enables a greater level of integration. | | danger | boolean | undefined | false | Use variant='danger' instead. | Apply danger style to the button. | | filled | boolean | undefined | false | Use variant='filled' instead. | Apply a filled-in style. Previously called primary. | | outlined | boolean | undefined | false | Use variant='outlined'. | Apply outlined style to the button. Previously called secondary. | | primary | boolean | undefined | false | Use variant='filled' instead. | Apply primary style to the Button. | | secondary | boolean | undefined | false | Use 'variant=outlined' instead. | Apply secondary style to the Button. | | tertiary | boolean | undefined | false | Use variant='embedded' instead. | Apply tertiary style to the Button. | | text | boolean | undefined | false | Use variant='text' instead. | Apply unfilled, un-outlined style to the Button. Previously called tertiary. | | unelevated | boolean | undefined | false | Use `elevation='flat' instead. | Remove elevation. |

Dialog Button Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | React.ReactNode | null | false | Content to be rendered inside the button. Can be used instead label of to provide more flexibility. Accepts any valid markup. Warning, if Label is set, it will be used instead of child content. |

Dialog Button Events

| Name | Default | Required | Params | Description | | ------- | --------- | -------- | ------ | ----------------------------------------- | | onClick | undefined | false | | The primary interaction event for button. |