@medmain/react-modal

Medmain's React Modal

Modal class can display a dialog window to ask for confirmation or to notify the user about an important action.

All methods used to display the modal return a Promise that resolves with a value when the modal is closed, by either pushing a button or using the "Escape" keyboard key.

Get started

const GetStarted = () => {
  const start = async () => {
    const answer = await modal.confirm('Do you want to delete it?', {width: 700});
    console.info(answer); // => true or false
  };
  return (
    <div>
      <RadiumStarterRoot>
        {modal.createElement()}
        <Button onClick={start}>START</Button>
      </RadiumStarterRoot>
    </div>
  );
};

API Documentation

Overview

• Constructor
• .dialog() method
• .confirm() method
• .alert() method

Constructor

Create an instance of the Modal class, setting the default labels of the OK and Cancel buttons.

const modal = new Modal(options);

options argument is an object with 2 properties:

Key	Type	Default value	Description
okButtonTitle	string or function	"OK"	Label of the primary button, used to confirm the action
cancelButtonTitle	string or function	"Cancel"	Label of the button used to cancel the action

dialog(options) method

Display a modal window with a title, a message and the buttons provided by the user. Resolve with any value associated with the button pushed to close the

const answer = await modal.dialog(options);

One argument: an options object with the following properties:

Key	Type	Default value	Description
title	String	undefined	Title of the modal window
message	String or function	undefined	Message displayed in the modal, under the title
width	String	undefined	Style width attribute E.g. "400px"
padding	String	undefined	Style padding attribute E.g. "1rem"
buttons	Array	[]	Array of buttons objects
render	React component	undefined	Custom component to be displayed instead of the built-in component

There are 2 ways to call the dialog() method:

• Using the built-in dialog component, the user provides the title, the message and the buttons attributes.
• Using the render attribute, the user provides the component to be displayed. The component accepts a close props to let the user close the modal.

Example of "built-in" component

const answer = await modal.dialog({
  title: 'Please confirm',
  message: 'Is it OK?',
  buttons: [
    {value: 1, title: 'Option 1'},
    {value: 2, title: 'Option 2', isDefault: true}
  ]
});
console.info(answer);
}}

Example of custom component, using the render attribute

const answer = await modal.dialog({
  render: ({close}) => (
    <div>
      <p>This dialog renders a custom component.</p>
      <Button onClick={() => close('A')}>Option A</Button>
      <Button onClick={() => close('B')}>Option B</Button>
    </div>
  )
});
console.info(answer);

The 2 following methods confirm and alert extend dialog behavior and can be considered as handy "shortcut" to perform some usual tasks.

alert(message, options) method

Display a modal window with a single button that closes the window. Return a Promise that resolves when the modal is closed.

Used to display messages that the user can only dismiss by pushing the button, "success" or "error" messages for example.

await modal.alert(message, options);

Arguments:

• message: the message displayed in the modal, as a String or a function, to allow JSX syntax
• options (optional): object used to customize the default behavior

Key	Type	Default value	Description
title	String	undefined	Title of the modal window
width	String	undefined	Style width attribute E.g. "400px"
padding	String	undefined	Style padding attribute E.g. "1rem"
okButton	button object	Default OK button	Button object to override the behavior of the default "OK" button

confirm(message, options) method

Display a modal window with a given message and 2 buttons.

Return a Promise that resolves with the value assigned to one of 2 buttons that was clicked. By default the OK button makes the Promise resolves with true and the Cancel button makes the Promise resolve with false.

Useful to ask for user confirmation before an important action.

The arguments are the same as for .alert() method, except the extra cancelButton option.

const answer = await modal.confirm(message, options);

Arguments:

• message: the message displayed in the modal, as a String or a function, to allow JSX syntax
• options (optional): object used to customize the default behavior

Key	Type	Default value	Description
title	String	undefined	Title of the modal window
width	String	undefined	Style width attribute E.g. "400px"
padding	String	undefined	Style padding attribute E.g. "1rem"
okButton	button object	Default OK button	Button object to override the behavior of the default "OK" button
cancelButton	button object	Default Cancel button	Button object to override the behavior of the default "Cancel" button

Minimal example:

const answer = await modal.confirm('Are your really sure?');
if (answer) {
  // OK button was clicked
} else {
  // Cancel button was clicked
}

Button object

All methods accept button objects to setup the buttons displayed in the modal footer. Buttons are used to make the modal Promise resolve with a given value when the modal is closed.

For every button, provide either a value or a custom onClick handler, calling by yourself the close argument of the handler.

{
  value,
  title,
  onClick,
  isDefault
}

Key	Type	Default value	Description
value	Any	true	Value resolved by the Promise modal when clicked
title	String or function	undefined	Button label as a string or a function () => <span>OK</span>
onClick	Function ({close}) => {}	undefined	Function called to customize the behavior when the button is clicked
isDefault	Boolean	false	Set to true to assign primary button style and listen to keyboard ENTER key