mui-use-dialogs

This package provides basic and common dialogs to be used with @mui/material!

Installation

npm install --save mui-use-dialogs

Demo

Usage

Setup DialogProvider

Wrap your app inside the DialogProvider component.

Note: If you're using Material UI ThemeProvider, make sure DialogProvider is a child of it.

import React from "react";
import { DialogProvider } from "mui-use-dialogs";

const App = () => {
  return (
    <DialogProvider>
      {/* your app... */}
    </DialogProvider>;
  )
};

export default App;

Import a Dialog

You can import whichever dialog hook you wish to use from mui-use-dialogs.

The hooks currently available are:

• useConfirm
• usePrompt

Note: These hooks return promises to allow you to use async/await.

See the example below or the demo on CodeSandbox on how to use one of these dialog hooks:

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

const MyComponent = () => {
    const confirmAsync = useConfirm();

    const handleClick = async () => {
        const confirmed = await confirmAsync(
            "Are you sure?" 
            /*, { ...options }*/,
        );

        if (!confirmed) return;
        console.log("The user has confirmed!");
    };

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

export default MyComponent;

Specifying Options

This library provides several way to specify the options for your dialog.

These methods are as follows:

• Within DialogProvider
• Within the hook itself (ex. useConfirm/usePrompt)
• Within the function call (ex. confirm(message, options))

DialogProvider

You may change the default options for dialogs at the DialogProvider level.
This will result in any hooks within that provider inheriting these options.

const App = () => {
  return (
    <DialogProvider
        prompt={ /* options for usePrompt */}
        confirm={ /* options for useConfirm */}>
      {/* your app... */}
    </DialogProvider>;
  )
};

The Hook (useConfirm/usePrompt)

You may also specify default options within the hook function for the dialogs.

import { useConfirm } from "mui-use-dialogs";

const MyComponent = () => {
    const confirmAsync = useConfirm({
        /* options */
    });
};

The Hook Function

Additionally, you may specify options within the returned function of The Hook.

import { useConfirm } from "mui-use-dialogs";

const MyComponent = () => {
    const confirmAsync = useConfirm();

    const handleClick = async () => {
        const confirmed = await confirmAsync("Are you sure?", {
            /* options */
        });
    };
};

Components & Props

DialogProvider

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

| Name | Type | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------ | | confirm | object | {} | Overrides the default options used by useConfirm | | prompt | object | {} | Overrides the default options used by usePrompt |

Common Options

| Name | Type | Default | Description | | --------------------- | --------------- | ------------------------------------- | ----------------------------------- | | title | string? | Varies | Dialog title text. | | label | string? | Varies | Dialog label text. | | rejectOnCancel | boolean | true | Throw an exception on cancel/close. | | autoFocus | boolean | true | Auto-focus the dialog. | | allowClose | boolean | false | Allow the user to close the dialog | | closeButtonShow | boolean | true | Show/hide the Close button | | closeButtonText | string? | 'Close' | Text of the Close Button | | closeButtonIcon | ReactNode? | CloseIcon @mui/icons-material/Close | Icon used for the Close Button | | slotProps | SlotPropsType | {} | Icon used for the Close Button |

SlotPropsType

| Name | Type | Description | | ------------------- | ----------------------------- | --------------------------------------- | | dialog | Partial<DialogProps> | Override props for <Dialog> | | dialogTitle | Partial<DialogTitleProps> | Override props for <DialogTitle> | | dialogContent | Partial<DialogContentProps> | Override props for <DialogContent> | | dialogActions | Partial<DialogActionsProps> | Override props for <DialogActions> | | closeButton | Partial<ButtonProps> | Override props for the Close <Button> |

useConfirm(message [, options]) => Promise<bool>

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

Confirm Options

| Name | Type | Default | Description | | ------------------- | ------------ | --------------------------------- | ----------------------------------------------------- | | title | string | Confirm | Dialog title text. | | message | string | 'Are you sure?' | Confirmation message displayed. Overrides label | | yesButtonText | string | 'OK' | Text shown for the Confirm Button. | | yesButtonIcon | ReactNode? | Check @mui/icons-material/Check | Icon in the Confirm Button. |

Slot Props

| Name | Type | Default - | Description | | --------------- | --------------------------------- | --------- | ---------------------------- | | message | Partial<DialogContentTextProps> | {} | Props for the dialog message | | yesButton | Partial<ButtonProps> | {} | Props for the Confirm Button |

usePrompt(message [, options]) => Promise<string | null>

This function opens a prompt dialog and returns a promise representing the user text (resolved on OK and rejected on Close).

Prompt Options

| Name | Type | Default | Description | | -------------------- | ------------ | ------------------------------- | ------------------------------------------------------------------------------- | | title | string | Prompt | Dialog title text. | | defaultText | string | undefined | Default text shown in the text field. | | saveButtonText | string | 'OK' | Text shown for the Save Button. | | saveButtonIcon | ReactNode? | Save @mui/icons-material/Save | Icon in the Save Button. | | saveOnEnter | boolean | true | Save the prompt on Enter key | | multiline | boolean | false | Whether or not the text field should allow/show multiple lines. | | minRows | number | Check | Minimum number of rows for the text field. Only used when multiline is true. | | **maxRows** | number |undefined | Maximum number of rows for the text field. Only used whenmultilineistrue. |

Slot Props

| Name | Type | Default - | Description | | --------------- | --------------------------------- | --------- | ---------------------------- | | message | Partial<DialogContentTextProps> | {} | Props for the dialog message | | yesButton | Partial<ButtonProps> | {} | Props for the Confirm Button |

rejectOnCancel

The rejectOnCancel prop is a little special! This prop determines the behavior for when a user clicks Close/Cancel/Whatever.

When rejectOnCancel is TRUE, an error will be thrown. Due to this, you will need to wrap The Hook Function in a try-catch block.

useConfirm with rejectOnCancel=true

import { useConfirm } from "mui-use-dialogs";

const Component = () => {
    const confirmAsync = useConfirm({ rejectOnCancel: true });

    const handleClick = async () => {
        try {
            // No need to use a variable since `confirm` will just throw an exception on fail..
            await confirmAsync("Are you sure?");

            // Confirmed! No error was thrown.
            console.log("The user confirmed!");
        } catch (error) {
            // NOT confirmed
            console.log("The user did not confirm!");
        }
    }
}

useConfirm with rejectOnCancel=false

import { useConfirm } from "mui-use-dialogs";

const Component = () => {
    const confirmAsync = useConfirm({ rejectOnCancel: false });

    const handleClick = async () => {
        // No need for a try-catch block since no exception will be thrown!
        // Need to use a variable to check the `confirm` response.
        const confirmed = await confirmAsync("Are you sure?");
        if (confirmed) {
            // Confirmed!
            console.log("The user confirmed!");
        } else {
            // NOT confirmed
            console.log("The user did not confirm!");
        }
    }
}

usePrompt with rejectOnCancel=true

import { usePrompt } from "mui-use-dialogs";

const Component = () => {
    const promptAsync = usePrompt({ rejectOnCancel: true });

    const handlePrompt = async () => {
        try {
            // Need to use a try-catch as an error will be thrown if "Cancel" is clicked.
            // No need to use a variable since `confirm` will just throw an exception on fail..
            const userPrompt = await promptAsync("Enter a prompt...");
            console.log(`The user entered the prompt: ${userPrompt}`);
        } catch (error) {
            // User closed out of the dialog.. Did not click "OK"
            console.log("The user cancelled out of the dialog...");
        }
    }
}

usePrompt with rejectOnCancel=false

import { usePrompt } from "mui-use-dialogs";

const Component = () => {
    const promptAsync = usePrompt({ rejectOnCancel: false });

    const handlePrompt = async () => {
        // No need for a try-catch!
        const userPrompt = await promptAsync ("Enter a prompt...");
        if(typeof userPrompt === "string"){
            console.log(`The user entered the prompt: ${userPrompt}`);
        } else { 
            // The user clicked Cancel
        }
    }
    // ...
}

Credits

This package was heavily based on jonatanklosko's material-ui-confirm. This package simply adds some more features.