material-ui-confirm

Material-UI confirm

Confirming user choice is a good thing to do, it should also be easy to do.

This package provides simple confirmation dialogs built on top of @mui/material and straightforward to use thanks to React Hooks.

Installation

npm install --save material-ui-confirm

Demo

Usage

Wrap your app inside the ConfirmProvider component.
Note: If you're using Material UI ThemeProvider, make sure ConfirmProvider is a child of it.

import React from "react";
import { ConfirmProvider } from "material-ui-confirm";

const App = () => {
  return <ConfirmProvider>{/* ... */}</ConfirmProvider>;
};

export default App;

Call the useConfirm hook wherever you need the confirm function.
Note: A component calling useConfirm must be a child of ConfirmProvider.

import React from "react";
import Button from "@mui/material/Button";
import { useConfirm } from "material-ui-confirm";

const Item = () => {
  const confirm = useConfirm();

  const handleClick = async () => {
    const { confirmed, reason } = await confirm({
      description: "This action is permanent!",
    });

    if (confirmed) {
      /* ... */
    }

    console.log(reason);
    //=> "confirm" | "cancel" | "natural" | "unmount"
  };

  return <Button onClick={handleClick}>Click</Button>;
};

export default Item;

API

ConfirmProvider

This component is required in order to render a dialog in the component tree.

Props

Name	Type	Default	Description
defaultOptions	object	{}	Overrides the default options used by confirm.
useLegacyReturn	boolean	false	When set to true, restores the confirm behaviour from v3: the returned promise is resolved on confirm, rejected on cancel, and kept pending on natural close.

useConfirm() => confirm

This hook returns the confirm function.

confirm([options]) => Promise<{ confirmed: boolean; reason: "confirm" | "cancel" | "natural" | "unmount"; }>

This function opens a confirmation dialog and returns a promise representing the user choice (resolved on confirmation and rejected on cancellation).

Options

Name	Type	Default	Description
title	ReactNode	'Are you sure?'	Dialog title.
description	ReactNode	''	Dialog content, automatically wrapped in DialogContentText.
content	ReactNode	null	Dialog content, same as description but not wrapped in DialogContentText. Supersedes description if present.
confirmationText	ReactNode	'Ok'	Confirmation button caption.
cancellationText	ReactNode	'Cancel'	Cancellation button caption.
dialogProps	object	{}	Material-UI Dialog props.
dialogActionsProps	object	{}	Material-UI DialogActions props.
confirmationButtonProps	object	{}	Material-UI Button props for the confirmation button.
cancellationButtonProps	object	{}	Material-UI Button props for the cancellation button.
titleProps	object	{}	Material-UI DialogTitle props for the dialog title.
contentProps	object	{}	Material-UI DialogContent props for the dialog content.
allowClose	boolean	true	Whether natural close (escape or backdrop click) should close the dialog. When set to false force the user to either cancel or confirm explicitly.
confirmationKeyword	string	undefined	If provided the confirmation button will be disabled by default and an additional textfield will be rendered. The confirmation button will only be enabled when the contents of the textfield match the value of confirmationKeyword
confirmationKeywordTextFieldProps	object	{}	Material-UI TextField props for the confirmation keyword textfield.
acknowledgement	string	undefined	If provided shows the acknowledge checkbox with this string as checkbox label and disables the confirm button while the checkbox is unchecked.
acknowledgementFormControlLabelProps	object	{}	Material-UI FormControlLabel props for the form control label.
acknowledgementCheckboxProps	object	{}	Material-UI Checkbox props for the acknowledge checkbox.
hideCancelButton	boolean	false	Whether to hide the cancel button.
buttonOrder	string[]	["cancel", "confirm"]	Specify the order of confirm and cancel buttons.

Useful notes

Confirm by pressing Enter

You can get this behavior by adding the autoFocus property to the confirmation button. This way the button is focused as soon as the dialog opens and hitting Enter naturally triggers a click.

Locally

const MyComponent = () => {
  // ...

  const handleClick = async () => {
    const { confirmed } = await confirm({
      confirmationButtonProps: { autoFocus: true },
    });

    if (confirmed) {
      /* ... */
    }
  };

  // ...
};

Globally

const App = () => {
  return (
    <ConfirmProvider
      defaultOptions={{
        confirmationButtonProps: { autoFocus: true },
      }}
    >
      {/* ... */}
    </ConfirmProvider>
  );
};

Changelog

4.0.0

This release changes the API, affecting all usages of confirm function. Previously the promise returned by confirm would be resolved on confirm and rejected on cancel. This has changed and the promise is now always resolved ⚠️.

You can upgrade to the new version and maintain the previous behaviour by setting a provider attribute:

<ConfirmProvider useLegacyReturn>
  {/* ... */}
</ConfirmProvider>

Migrating

Given this code from v3:

confirm({ ... })
  .then(() => console.log("confirm"))
  .catch(() => console.log("cancel"));

You can achieve the same behaviour in v4, like so:

confirm({ ... })
  .then(({ confirmed, reason }) => {
    if (confirmed) {
      console.log("confirm")
    } else if (reason === "cancel") {
      console.log("cancel")
    }
  });

The promise is also resolved on natural close (backdrop click, escape) or when the parent unmounts, in both cases with a distinct reason. In most cases you may only be interested in the confirmed code path, in which case you would only check confirmed and ignore the reason.

With this new API, it is guaranteed the callback eventually runs, which helps to avoid leaks if the callback is supposed to free certain resources. It is also more suitable for use with async/await (which required a try/catch):

const { confirmed } = await confirm({ description: "This action is permanent!" });

if (confirmed) {
  /* ... */
}

Breaking changes

• Always resolve the promise with confirmation status and close reason (#124)