useDialogs

Imperative APIs to open and interact with dialogs.

Toolpad Core offers a set of abstractions that makes interacting with dialogs simpler. It has an imperative API to open and close dialogs, and allows dialogs to be stacked on top of each other.

First thing you need to do is install the DialogsProvider at the root of your application.

import { DialogsProvider } from '@toolpad/core/useDialogs';

function App({ children }) {
  return <DialogsProvider>{children}</DialogsProvider>;
}

To get access to the dialogs API you first have to call the useDialogs hook.

import { useDialogs } from '@toolpad/core/useDialogs';

function MyApp() {
  const dialogs = useDialogs();
  // ...
}

Basic dialog

Dialogs are React components that taken open and onClose properties and return a Dialog component. The open property reflects the open state of the dialog and you can call the onClose handler to close it.

function MyCustomDialog({ open, onClose }: DialogProps) {
  return (
    <Dialog fullWidth open={open} onClose={() => onClose()}>
      <DialogTitle>Custom dialog</DialogTitle>
      <DialogContent>I am a custom dialog</DialogContent>
      <DialogActions>
        <Button onClick={() => onClose()}>Close me</Button>
      </DialogActions>
    </Dialog>
  );
}

Now you can call the dialogs.open function and pass the component as a first parameter.

await dialogs.open(MyCustomDialog);

await dialogs.open(MyCustomDialog);

Press Enter to start editing

With dialog payload

You can pass a payload to the dialog with the second parameter. The payload stays constant for the lifetime of the dialog.

Payload

await dialogs.open(MyCustomDialog, payload);

await dialogs.open(MyCustomDialog, payload);

Press Enter to start editing

With dialog result

A dialog can return a value with the onClose handler. The promise returned by the open method is resolved with the value that was passed to onClose.

const result = await dialogs.open(MyCustomDialog);
await dialogs.alert(`Your name is "${result}"`);

const result = await dialogs.open(MyCustomDialog);
await dialogs.alert(`Your name is "${result}"`);

Press Enter to start editing

Stacked dialogs

Dialogs can be stacked. A dialog can open other another dialog which comes to the foreground upon opening. Closing the latter reveals the former again.

await dialogs.open(MyCustomDialog, payload + 1);

await dialogs.open(MyCustomDialog, payload + 1);

Press Enter to start editing

System dialogs

Toolpad comes with a set of system dialogs that improve on the native window.alert, window.confirm, and window.prompt APIs. These APIs are very similar, but they create dialogs that follow your application theme.

Alert

Analog to window.alert it opens a dialog with a message for the user. The only action to be taken is to acknowledge the message after which the dialog closes. The dialog title and button text are customizable with the title and okText properties.

await dialogs.alert('Hello World');

await dialogs.alert('Hello World');

Press Enter to start editing

Confirm

Analog to window.confirm it opens a dialog with a question for the user. The user can either confirm or cancel and the dialog result is a boolean which is true when the user confirmed. The dialog title and button texts are customizable with the title, okText, and cancelText properties.

const confirmed = await dialogs.confirm('Are you sure?', {
  okText: 'Yes',
  cancelText: 'No',
});
if (confirmed) {
  await dialogs.alert("Then let's do it!");
} else {
  await dialogs.alert('Ok, forget about it!');
}

const confirmed = await dialogs.confirm('Are you sure?', {
  okText: 'Yes',
  cancelText: 'No',
});
if (confirmed) {
  await dialogs.alert("Then let's do it!");
} else {
  await dialogs.alert('Ok, forget about it!');
}

Press Enter to start editing

Prompt

Analog to window.prompt it opens a dialog inquiring the user for some input text. The user can fill the input box and upon confirmation the promise returned from the prompt call is resolved with its value. The dialog title and button texts are customizable with the title, okText, and cancelText properties.

const name = await dialogs.prompt("What's your name?");
if (name) {
  await dialogs.alert(`Hi there, ${name}`);
}

const name = await dialogs.prompt("What's your name?");
if (name) {
  await dialogs.alert(`Hi there, ${name}`);
}

Press Enter to start editing

Advanced Examples

Complex payload

The payload can be an object which contains anything - including a React Component. This allows you to pass arbitrary data and components to your dialog. For instance, to render a form with location-dependent fields inside a dialog:

Country

const uuid = await dialogs.open(TransactionDialog, {
  component: country === 'usa' ? <PayloadUSA /> : <PayloadIndia />,
  data: csrfToken,
});

const uuid = await dialogs.open(TransactionDialog, {
  component: country === 'usa' ? <PayloadUSA /> : <PayloadIndia />,
  data: csrfToken,
});

Press Enter to start editing

Hook API

useDialogs()

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<DialogsProvider />