Skip to content

Latest commit

 

History

History
148 lines (111 loc) · 9.91 KB

README.md

File metadata and controls

148 lines (111 loc) · 9.91 KB

Material-UI confirm GitHub license npm version Actions Status Coverage Status

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

Edit 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 = () => {
    confirm({ description: "This action is permanent!" })
      .then(() => {
        /* ... */
      })
      .catch(() => {
        /* ... */
      });
  };

  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.

useConfirm() => confirm

This hook returns the confirm function.

confirm([options]) => Promise

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 = () => {
    confirm({ confirmationButtonProps: { autoFocus: true } })
      .then(() => {
        /* ... */
      })
      .catch(() => {
        /* ... */
      });
  };

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