This package provides basic and common dialogs to be used with @mui/material!
npm install --save mui-use-dialogs
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;
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;
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)
)
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>;
)
};
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 */
});
};
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 */
});
};
};
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 |
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 |
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>
|
This function opens a confirmation dialog and returns a promise representing the user choice (resolved on confirmation and rejected on cancellation).
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. |
Name | Type | Default - | Description |
---|---|---|---|
message |
Partial<DialogContentTextProps> |
{} |
Props for the dialog message |
yesButton |
Partial<ButtonProps> |
{} |
Props for the Confirm Button |
This function opens a prompt dialog and returns a promise representing the user text (resolved on OK and rejected on Close).
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. |
Name | Type | Default - | Description |
---|---|---|---|
message |
Partial<DialogContentTextProps> |
{} |
Props for the dialog message |
yesButton |
Partial<ButtonProps> |
{} |
Props for the Confirm Button |
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.
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!");
}
}
}
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!");
}
}
}
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...");
}
}
}
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
}
}
// ...
}
This package was heavily based on jonatanklosko's material-ui-confirm. This package simply adds some more features.