Dialog

Dialog components of the RCL

Table of Contents

• PanBasicDialog
• PanAdvancedDialog
  • Behavior on small screens
• PanDialogActionsArray
• Examples

PanBasicDialog

A modal dialog sized to its content (minimum width 280px, maximum width sm). It shows a title, your content, and a row of action buttons at the bottom. It is the right choice for confirmations and short forms.

Clicking the backdrop or pressing Escape calls closeFn. The dialog surface is rendered as an HTML form element.

Prop	Type	Default	What it does
titleLabel	string	required	Text shown as the dialog title. Translate it before passing it in.
isOpen	boolean	required	Whether the dialog is visible. The parent component owns this state.
closeFn	() => void	required	Function called to close the dialog. It is called when the user clicks the backdrop or presses Escape. Your code should use it to set isOpen to false.
children	ReactNode	none	The content of the dialog: any React nodes (text, form fields, lists…).
actionsButtonArray	ReactElement[]	none	Array of buttons rendered in the footer, in order. Normally the result of PanDialogActionsArray(...), but any array of React elements works.
requiredFieldsLabel	boolean	false	When true, a note is shown above the content explaining that required fields are marked (translation key library:pankosmia-rcl:required_field). Use it when the dialog contains a form with required fields.
dividers	boolean	false	When true, a horizontal divider is drawn between the title and the content, and between the content and the buttons.

PanAdvancedDialog

A modal dialog with a colored title bar (primary theme color), full width up to the sm breakpoint, and a divider above the buttons. It is meant for longer content and forms.

Behavior on small screens

Below the sm breakpoint the dialog goes full screen. A close icon appears at the start of the title bar and calls closeFn. The footer is hidden, and the second button of actionsButtonArray (the action button created by PanDialogActionsArray) is moved to the end of the title bar. Keep the main action in second position so that it stays reachable on mobile. Unlike PanBasicDialog, clicking the backdrop or pressing Escape does not close this dialog.

Prop	Type	Default	What it does
titleLabel	string	required	Text shown as the dialog title. Translate it before passing it in.
isOpen	boolean	required	Whether the dialog is visible. The parent component owns this state.
closeFn	() => void	required	Function called when the user clicks the close icon shown in the title bar on small screens. Your code should use it to set isOpen to false. It is not called from the backdrop or Escape.
children	ReactNode	none	The content of the dialog: any React nodes (text, form fields, lists…).
actionsButtonArray	ReactElement[]	none	Array of buttons rendered in the footer, in order. Normally the result of PanDialogActionsArray(...), but any array of React elements works.
requiredFieldsLabel	boolean	false	When true, a note is shown above the content explaining that required fields are marked (translation key library:pankosmia-rcl:required_field). Use it when the dialog contains a form with required fields.

PanDialogActionsArray

Despite its name it is a plain function, not a component: call it like PanDialogActionsArray({ ... }). It returns an array of two elements, [closeButton, actionButton], to pass to the actionsButtonArray prop of PanBasicDialog or PanAdvancedDialog. The close button is always first. The action button is second; when onlyCloseButton is true that slot is null.

Prop	Type	Default	What it does
actionFn	() => void	required	Function run when the action button is clicked. Not used when onlyCloseButton is true.
actionLabel	string	required	Label of the action button. Translate it before passing it in.
closeFn	() => void	required	Function run when the close button is clicked. It is also called after actionFn when closeOnAction is true.
closeLabel	string	required	Label of the close button (for example Cancel or Close). Translate it before passing it in.
isDisabled	boolean	none	When true, the action button is disabled. Typically used while a form is invalid. The close button is never disabled by this prop.
closeOnAction	boolean	true	When true, closeFn is called right after actionFn. Set it to false when the action is asynchronous or can fail and your code must close the dialog itself.
onlyCloseButton	boolean	false	When true, only the close button is created (for information-only dialogs). The second array slot is null.
actionVariant	string	none	MUI Button variant of the action button: text, outlined or contained. When omitted, MUI’s default (text) is used.
closeVariant	string	none	MUI Button variant of the close button: text, outlined or contained. When omitted, MUI’s default (text) is used.
isLoading	boolean	none	When true, the close button is disabled and shows a small spinner. Note that this is applied to the close button only, not to the action button.
loadingLabel	string	none	Label that replaces the close button label while isLoading is true. If omitted, the normal label stays.

Examples

A dialog with a confirm action. The same pattern works for PanAdvancedDialog:

const [open, setOpen] = useState(false);

<PanBasicDialog
  titleLabel="Delete this item?"
  isOpen={open}
  closeFn={() => setOpen(false)}
  actionsButtonArray={PanDialogActionsArray({
    actionLabel: "Delete",
    actionFn: () => deleteItem(),
    closeLabel: "Cancel",
    closeFn: () => setOpen(false),
    actionVariant: "contained",
  })}
>
  <Typography>This cannot be undone.</Typography>
</PanBasicDialog>

Working demos are in src/componentDemos/V1.0 of the core-client-rcl repository.