mui-use-dialogs
TypeScript icon, indicating that this package has built-in type declarations

1.0.6 • Public • Published

mui-use-dialogs GitHub license npm version

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

Installation

npm install --save mui-use-dialogs

Demo

Edit 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 when multiline is `true.

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.

Package Sidebar

Install

npm i mui-use-dialogs

Weekly Downloads

3

Version

1.0.6

License

MIT

Unpacked Size

312 kB

Total Files

22

Last publish

Collaborators

  • bdavis17