Showing a modal dialog useImperativeHandle() React hook

[koistya]

Take Material UI's Dialog component as an example that has open: boolean React prop as a way to manage its open/closed state. In Material UI documentation you will find a usage example similar to this:

import * as React from "react";
import { Button, Container, Dialog, DialogActions, DialogContent, DialogTitle } from "@mui/material";

export function Example(): JSX.Element {
  const [open, setOpen] = React.useState(false);
  const handleOpen = React.useCallback(() => setOpen(true), []);
  const handleClose = React.useCallback(() => setOpen(false), []);
  const handleAction = React.useCallback(() => { ... }, []);

  return (
    <Container>
       <Button onClick={handleOpen}>Open Dialog</Button>

       <Dialog open={state.open} onClose={handleClose}>
         <DialogTitle>...</DialogTitle>
        <DialogContent>
          ...
        </DialogContent>
        <DialogActions>
          <Button onClick={handleClose}>Cancel</Button>
          <Button onClick={handleAction}>OK</Button>
        </DialogActions>
      </Dialog>
    </Container>
  );
}

In the original example, the dialog is used in place. Normally, you want to extract dialog in a standalone component, for example:

import * as React from "react";
import { Button, Container, Dialog, DialogActions, DialogContent, DialogProps, DialogTitle } from "@mui/material";

export function ConfirmDialog(props: ConfirmDialogProps): JSX.Element {
  const [state, setState] = ...
  const handleClose = ...
  const handleConfirm = ...

  return (
    <Dialog open={state.open} {...props}>
      <DialogTitle>...</DialogTitle>
      <DialogContent>
        ...
      </DialogContent>
      <DialogActions>
          <Button onClick={handleClose}>Cancel</Button>
          <Button onClick={handleConfirm}>OK</Button>
      </DialogActions>
    </Dialog>
  );
}

export type ConfirmDialogProps = Omit<DialogProps, "open">;

Afterwards, the original example could be reduced to the following:

import * as React from "react";
import { ConfirmDialog } from "../dialogs/ConfirmDialog.js";

export function Example(): JSX.Element {
  const handleOpen = ...
  const handleAction = ...

  return (
    <Container>
       <Button onClick={handleOpen}>Open Dialog</Button>
       <ConfirmDialog onConfirm={handleAction} />
    </Container>
  );
}

If the dialog can be used without a need to manage its state in-place that code would look nice and clean.

There are multiple ways to implement it, e.g. by introducing a top-level DialogProvider component + useDialog(...) React hook, alternatively you can add an imperative handler to the dialog itself so that it can be opened using dialogRef.current?.open() method available on the dialog instance.

import * as React from "react";
import { ConfirmDialog } from "../dialogs/ConfirmDialog.js";

export function Example(): JSX.Element {
  const dialogRef = React.useRef<DialogElement>(null);
  const handleOpen = React.useCallback(() = dialogRef.current?.open(), []);
  const handleAction = ...

  return (
    <Container>
       <Button onClick={handleOpen}>Open Dialog</Button>
       <ConfirmDialog ref={dialogRef} onConfirm={handleAction} />
    </Container>
  );
}

Now let's see how the implementation of this dialog including .open() method implemented with useImeprativeHandle(ref, ...), useState() React hooks looks like:

import * as React from "react";
import { Button, Dialog, DialogActions, DialogContent, DialogProps, DialogTitle } from "@mui/material";

export const ConfirmDialog = React.forwardRef<
  DialogElement,
  ConfirmDialogProps
>(function ConfirmDialog(props, ref): JSX.Element {
  const { onClose, onConfirm, ...other } = props;
  const [state, setState] = React.useState<State>({ open: false });
  const handleClose = useHandleClose(setState, onClose);
  const handleConfirm = useHandleConfirm(setState, onConfirm);

  React.useImperativeHandle(ref, () => ({
    open() {
      setState({ open: true });
    },
  }));

  return (
    <Dialog open={state.open} onClose={handleClose} {...other}>
      <DialogTitle>...</DialogTitle>
      <DialogContent>...</DialogContent>
      <DialogActions>
        <Button onClick={handleClose}>Cancel</Button>
        <Button onClick={handleConfirm}>OK</Button>
      </DialogActions>
    </Dialog>
  );
});

function useHandleClose(setState: SetState, handleClose?: CloseHandler) {
  return React.useCallback<CloseHandler>(function (event, reason) {
    setState({ open: false });
    handleClose?.(event, reason ?? "backdropClick");
  }, []);
}

function useHandleConfirm(setState: SetState, handleConfirm?: ConfirmHandler) {
  return React.useCallback(async function () {
    await handleConfirm?.();
    setState({ open: false });
  }, []);
}

type State = { open: boolean; error?: Error };
type SetState = React.Dispatch<React.SetStateAction<State>>;
type CloseHandler = NonNullable<DialogProps["onClose"]>;
type ConfirmHandler = () => Promise<void> | void;

export type DialogElement = { open: () => void };

export type ConfirmDialogProps = Omit<DialogProps, "open"> & {
  onConfirm?: ConfirmHandler;
};

There are pros and cons of this approach, on the good side is that it's fully self-contained and doesn't rely on any external state management solutions.

[teetotum]

I found your blog post today, which brought me here. We have both hit upon the same idea; I wrote a blog post early in 2022 describing an imperative approach to Dialogs (and other components) in React.
After I wrote the post I started actually using this approach in different projects and gathered some experience with it.

What I discovered was that when starting out with a purely imperative way to open a dialog and everything seemed splendit at first, that after some time and growing number of use-cases the purely imperative API wasn't enough anymore and I added a declarative way of setting the dialog state.

One example started out as:

• there is a component (lets term this compoenent the caller) that shows a list of items, the user can click any item
• when clicked it should open a dialog showing additional information, conceptually the item is just a button that triggers an action
• the dialog state is not reflected anywhere in the caller side
  -> the imperative approach fits like a glove, no state is needed outside of it, only a ref

UI design and requirements were refined over time and changed:

• the clicked item should be highlighted and stay highlighted as long as the dialog is open
• the dialog can be closed via its own X-icon button
• or via Esc key
• or by clicking anywhere into the void
  -> suddenly it wasn't enough anymore that the dialog managed its own state internally, a visual state in the caller was directly tied to the state of the dialog. A declarative approach was a better fit now.

And I believe I stumbled upon one valuable insight there:

Whether a declarative or an imperative API is better suited doesn't depend so much on the nature of my component, but rather on the nature of how it is used.

Which led me to refine my dialog components: they will now usually offer both ways of interacting with them.
If I can't support both approaches because it would make the component too complex, I will default to the declarative approach.

I still think an imperative API can make the caller code very clean and I try to accomodate it, but I don't consider it wise to only offer an imperative API without the declarative alternative.

However, supporting both approaches does increase complexity considerably inside the dialog implementation.
If you are interested in how I tackled that I put up a gist and if you happen to find a way to simplify it I would appreciate it if you shared your thoughts.