Dialog

Installation

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @lumi-ui/dialog
Copy

Basic Usage

Copyimport {
  Dialog,
  DialogClose,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogContent,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

Copyexport function DialogDemo() {
  return (
    <Dialog>
      <DialogTrigger>Show Alert Dialog</DialogTrigger>
      <DialogContent showCloseButton>
        <DialogHeader>
          <DialogTitle>Are you absolutely sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone. This will permanently delete your
            account and remove your data from our servers.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose>Cancel</DialogClose>
          <DialogClose>Continue</DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Anatomy

Copy<Dialog>   
  <DialogTrigger />
  <DialogContent>     
    <DialogHeader>     
      <DialogTitle />     
      <DialogDescription />     
    </DialogHeader>
    <DialogScrollArea />     
    <DialogFooter>     
      <DialogClose />     
    </DialogFooter>   
  </DialogContent> 
</Dialog>

Cookbook

Controlled Dialog

By default, Dialog is an uncontrolled component that manages its own state.

Copy<Dialog>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>
   <DialogHeader>
      <DialogTitle>Example dialog</DialogTitle>
   </DialogHeader>
   <DialogFooter>
      <DialogClose>Close</DialogClose>
   </DialogFooter>
  </DialogContent>
</Dialog>

Use open and onOpenChange props if you need to access or control the state of the dialog. For example, you can control the dialog state in order to open it imperatively from another place in your app.

Copyconst [open, setOpen] = React.useState(false);
 
<Dialog open={open} onOpenChange={setOpen}>
  <DialogTrigger>Open</DialogTrigger>
  <DialogContent>
    <form 
      // Close the dialog once the form data is submitted           
      onSubmit={
        async () => {             
          await submitData();             
          setOpen(false);   
        }
      }
    >
      ...
    </form>
  </DialogContent>
</Dialog>

It’s also common to use onOpenChange if your app needs to do something when the dialog is closed or opened. This is recommended over useEffect when reacting to state changes.

Copy<Dialog
  open={open}
  onOpenChange={(open) => {
    // Do stuff when the dialog is closed
    if (!open) {
      doStuff();
    }
    // Set the new state
    setOpen(open);
  }}
>

Open from Dropdown menu

In order to open a dialog using a menu, control the dialog state and open it imperatively using the onClick handler on DropdownMenuItem.

Nested dialogs

You can nest dialogs within one another normally.

Close confirmation

This example shows a nested confirmation dialog that opens if the text entered in the parent dialog is going to be discarded.

To implement this, both dialogs should be controlled. The confirmation dialog may be opened when onOpenChange callback of the parent dialog receives a request to close. This way, the confirmation is automatically shown when the user clicks the backdrop, presses the Esc key, or clicks a close button.

Inside scroll dialog

Use <DialogScrollArea> inside <DialogContent> to make an inner container scrollable while the popup stays fully on screen.

Outside scroll dialog

The dialog can be made scrollable by using <DialogViewport> as an outer scrollable container for <DialogPopup> while the popup can extend past the bottom edge. The scrollable area uses the Scroll Area component to provide custom scrollbars.

Placing elements outside the popup

When adding elements that should appear “outside” the colored popup area, continue to place them inside <DialogPopup>, but create a child element that has the popup styles. This ensures they are kept in the tab order and announced correctly by screen readers.

<DialogPopup> has pointer-events: none, while inner content (the colored popup and close button) has pointer-events: auto so clicks on the backdrop continue to be registered.

Detached triggers

A dialog can be controlled by a trigger located either inside or outside the <Dialog> component. For simple, one-off interactions, place the <DialogTrigger> inside <Dialog>, as shown in the demo example at the top of this page.

However, if defining the dialog’s content next to its trigger is not practical, you can use a detached trigger. This involves placing the <DialogTrigger> outside of <Dialog> and linking them with a handle created by the createDialogHandle function.

Copyimport { createDialogHandle } from "@/components/ui/dialog"
 
const demoDialog = createDialogHandle();
 
<DialogTrigger handle={demoDialog}>Open</DialogTrigger>
 
<Dialog handle={demoDialog}>
  ...
</Dialog>

Multiple triggers

A single dialog can be opened by multiple trigger elements. You can achieve this by using the same handle for several detached triggers, or by placing multiple <DialogTrigger> components inside a single <Dialog>.

Copy<Dialog>
  <DialogTrigger>Trigger 1</DialogTrigger>
  <DialogTrigger>Trigger 2</DialogTrigger>
  ...
</Dialog>

Copyconst demoDialog = createDialogHandle();
 
<DialogTrigger handle={demoDialog}>Trigger 1</DialogTrigger>
<DialogTrigger handle={demoDialog}>Trigger 2</DialogTrigger>
<Dialog handle={demoDialog}>
  ...
</Dialog>

The dialog can render different content depending on which trigger opened it. This is achieved by passing a payload to the <DialogTrigger> and using the function-as-a-child pattern in <Dialog>.

Controlled mode with multiple triggers

You can control the dialog’s open state externally using the open and onOpenChange props on <Dialog>. This allows you to manage the dialog’s visibility based on your application’s state. When using multiple triggers, you have to manage which trigger is active with the triggerId prop on <Dialog> and the id prop on each <DialogTrigger>.

Note that there is no separate onTriggerIdChange prop. Instead, the onOpenChange callback receives an additional argument, eventDetails, which contains the trigger element that initiated the state change.

API Reference

Migration Guide

Trigger Composition (render prop)

Radix UI uses the asChild pattern to merge the trigger logic with a child element. Base UI uses the render prop for changing HTML tags or using custom triggers.

Copy// Before:
<DialogTrigger asChild>
  <Button>Open</Button>
</DialogTrigger>
 
// After:
<DialogTrigger render={<Button>Open</Button>} />

Example

Copy<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Edit Profile</Button>
  </DialogTrigger>
  <DialogContent className="sm:max-w-[425px]">
    <DialogHeader>
      <DialogTitle>Edit profile</DialogTitle>
    </DialogHeader>
    <div className="grid gap-4 py-4">
      {/* Form content */}
    </div>
    <DialogFooter>
      <Button type="submit">Save changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>