Skip to content

Migrating to V3

Introducing React Dialog Async V3! This new major version includes an improved API, new features for more flexible use, and much more polished documentation. There are also a number of breaking changes, outlined below.

show and hide methods removed from useDialog()

Section titled “show and hide methods removed from useDialog()”

The methods returned by useDialog() have changed. show and hide were deprecated in 2.4.0, and have been removed in 3.0.0 in favour of open and close.

const myDialog = useDialog(MyDialog);
await myDialog.show(...);
await myDialog.open(...);
await myDialog.hide();
await myDialog.close();
  • customKey has been removed. This option was not used internally, and was a legacy option from early versions of the library.

  • hideOnHookUnmount has been renamed to persistOnUnmount. This should be more intuitive, as setting this option to true will persist the dialog when the hook unmounts.

const myDialog = useDialog(MyDialog, {
customKey: 'my-dialog',
hideOnHookUnmount: false
persistOnUnmount: true
});

In previous versions of the library, <DialogOutlet/> was optional, and if it was not required, dialogs would be rendered as children of the <DialogProvider/>.

In V3, this is not longer the case, and <DialogOutlet/> is now required for dialogs to render. If one is not found, an error will be thrown when attempting to open a dialog.

<DialogProvider>
<App />
<DialogOutlet />
</DialogProvider>

mounted prop removed from dialog components

Section titled “mounted prop removed from dialog components”

The mounted prop passed to dialog components has been removed. This prop was always set to true, which made it effectively useless.

export const MyDialog = ({ mounted }: AsyncDialogProps) => {
export const MyDialog = ({ }: AsyncDialogProps) => {
// ...
}

open and focused props renamed to isOpen and isFocused

Section titled “open and focused props renamed to isOpen and isFocused”

The open and focused props passed to dialog components have been renamed to isOpen and isFocused respectively. This is to make it more clear that these props are booleans, and to differentiate them from the open() method returned by useDialog().

export const MyDialog = ({ open, focused }: AsyncDialogProps) => {
export const MyDialog = ({ isOpen, isFocused }: AsyncDialogProps) => {
// ...
}

defaultUnmountDelayInMs now defaults to 300ms

Section titled “defaultUnmountDelayInMs now defaults to 300ms”

The defaultUnmountDelayInMs option for <DialogProvider/> now defaults to 300. This is to provide a better out-of-the-box experience, as most dialogs will have some form of exit animation.

If you want to retain the previous behaviour, explicitly set this option to 0.

<DialogProvider
defaultUnmountDelayInMs={0}
/>