Dialog

When to UseCopy Anchor Link

• for a short form that changes one record, such as “Rename project”
• for a task that users have to finish or cancel before anything else
• to show a command palette, as CommandDialog in Command does

When Not to UseCopy Anchor Link

• to ask for a response before an action that can’t be undone (use an Alert Dialog)
• for a panel docked to one side of the screen (use a Sheet)
• for a panel that users swipe away (use a Drawer)
• for content that belongs to one control and keeps the page interactive (use a Popover)

AnatomyCopy Anchor Link

* The title is the Dialog’s accessible name. If the design shows no title, visually hide it and keep it in the markup.

DialogContent renders the portal, the overlay, and the close button, so you don’t need to add them. The figure is 352px wide, so its footer shows the stacked layout that is used below 640px.

BehaviorCopy Anchor Link

By default, a Dialog is modal: Base UI keeps focus in the popup, locks the page’s scroll, and prevents clicks from reaching the page. If you want the page to stay interactive, set modal={false} on Dialog. If you want the Dialog to stay open when users click the overlay, set disablePointerDismissal.

FooterCopy Anchor Link

From 640px, the Buttons in the footer are placed in a row at its end. Below 640px, they are stacked in reverse order. Write the main action last so that it is at the end of the row and at the top of the stack.

OverflowCopy Anchor Link

The popup is at most as tall as the screen. If the content is taller, the popup scrolls. To keep the header and the footer in view, place the content between them in a region that scrolls.

ContentCopy Anchor Link

The label of the close button is labels.dialog.close, which is “Close” by default. To translate it, use the Summit Provider.

AccessibilityCopy Anchor Link

Base UI’s Dialog sets the role, moves focus in and out, and closes when users press Escape. You provide the title that names the Dialog.

RequirementsCopy Anchor Link

If showCloseButton is false, keep a DialogClose in the popup. The ARIA Authoring Practices Guide strongly recommends a visible button that closes a dialog. The overlay is hidden from assistive technology, so if there is no such button, Escape is the only way for screen reader users to close the Dialog, and users on a touch screen have no Escape key.

InstallationCopy Anchor Link

npx shadcn@latest add @summit/dialog

The CLI also adds @summit/button and @summit/summit-provider.

UsageCopy Anchor Link

import { Button } from '@/components/ui/button';
import {
    Dialog,
    DialogClose,
    DialogContent,
    DialogDescription,
    DialogFooter,
    DialogHeader,
    DialogTitle,
    DialogTrigger,
} from '@/components/ui/dialog';

<Dialog>
    <DialogTrigger render={<Button variant="outline" />}>Rename project</DialogTrigger>
    <DialogContent>
        <DialogHeader>
            <DialogTitle>Rename project</DialogTitle>
            <DialogDescription>The new name shows on invoices and reports.</DialogDescription>
        </DialogHeader>
        <DialogFooter>
            <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
            <DialogClose render={<Button />}>Save</DialogClose>
        </DialogFooter>
    </DialogContent>
</Dialog>;

Hide the Close ButtonCopy Anchor Link

To remove the close button in the corner, set showCloseButton={false} on DialogContent. To add an outline Button with the same label to the footer, set showCloseButton on DialogFooter.

<DialogContent showCloseButton={false}>
    <DialogTitle>Rename project</DialogTitle>
    <DialogFooter showCloseButton />
</DialogContent>

Change the WidthCopy Anchor Link

By default, the width is sm:max-w-xl. To change it, pass another width in className on DialogContent.

<DialogContent className="sm:max-w-sm">
    <DialogTitle>Rename project</DialogTitle>
</DialogContent>

API ReferenceCopy Anchor Link

The parts accept the props of their matching parts in Base UI’s Dialog, where DialogContent is Dialog.Popup and DialogOverlay is Dialog.Backdrop. DialogHeader and DialogFooter accept the props of a div. See the Base UI Dialog documentation for the props of each part.

DialogContentCopy Anchor Link

DialogFooterCopy Anchor Link