@element-public/react-dialog

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 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-dialog @element/themes

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 background 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	The value to pass to the action handler. For example 'ok', 'cancel', etc.
focused	boolean	null	false	Set focus on this element 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. Use only one icon per button. Place icons in the leading position by default. Expects the name of a valid Material 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-danger Deprecated Values: onUnknownBlack, onUnknownWhite
trailingIcon	string|function|React.ReactNode	undefined	false	Adds the given Icon to the right of the button text. Use only one icon per button. Place icons in the leading position by default. Expects the name of a valid Material 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.