React Dialog: examples and API

Preview

Live preview

Changes apply to this preview only.

Width adapts to the available space

"use client";

import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger
} from "@pimolu/react";

export function DialogExample() {
  return (
    <Dialog>
      <DialogTrigger>
        <Button>Review the invitation</Button>
      </DialogTrigger>
      <DialogContent size="sm">
        <DialogHeader>
          <DialogTitle>You are invited.</DialogTitle>
          <DialogDescription>
            Join the Orbit design workspace and build something together.
          </DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose>
            <Button appearance="outline" variant="neutral">Close invitation</Button>
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Anatomy

Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter and DialogClose, composed in the order a dialog is read.

Open preview

Sizes

Enumerated from dialogVariantMap: sm, md and lg cap the panel width.

Open preview

Forms

A controlled dialog with a name field and a checkbox; Save closes it from the page.

Open preview

Usage

Compose DialogTrigger and DialogContent with a title and description. A trigger child must forward its props and ref; Pimolu Button does.

Use open/onOpenChange when your workflow owns dismissal. DialogClose can wrap an existing button without creating a nested button.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluDialogProps

Type source

PimoluDialogProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Trigger, content, header, footer and close controls.
`open`	`boolean \| undefined`	—	Controlled open state. Omit to let the component own it.
`defaultOpen`	`boolean \| undefined`	`false`	Initial open state when uncontrolled. Defaults to false.
`onOpenChange`	`((open: boolean) => void) \| undefined`	—	Called whenever the component asks to open or close.

childrenRequired: ReactNode
No default extracted.
Trigger, content, header, footer and close controls.
open: boolean | undefined
No default extracted.
Controlled open state. Omit to let the component own it.
defaultOpen: boolean | undefined
Default: false
Initial open state when uncontrolled. Defaults to false.
onOpenChange: ((open: boolean) => void) | undefined
No default extracted.
Called whenever the component asks to open or close.

PimoluDialogTriggerProps

Type source

PimoluDialogTriggerProps public API
Name	Type	Default	Description
`children`Required	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	The element that opens the dialog: any element, or a component that passes down the props it receives. It gets the ARIA state, the click handler and the ref, and the handlers it already had keep working.

childrenRequired: ReactElement<unknown, string | JSXElementConstructor<any>>
No default extracted.
The element that opens the dialog: any element, or a component that passes down the props it receives. It gets the ARIA state, the click handler and the ref, and the handlers it already had keep working.

PimoluDialogContentProps

Type source

PimoluDialogContentProps public API
Name	Type	Default	Description
`children`	`ReactNode`	—	Header, body and footer of the dialog.
`size`	`"sm" \| "md" \| "lg" \| undefined`	`"md"`	Maximum width of the panel. Defaults to "md".
`closeOnOverlayClick`	`boolean \| undefined`	`true`	Close when the overlay is pressed. Defaults to true.
`closeOnEscape`	`boolean \| undefined`	`true`	Close on Escape. Defaults to true.
`showCloseButton`	`boolean \| undefined`	`true`	Render the close button in the top corner. Defaults to true.
`closeLabel`	`string \| undefined`	`"Close"`	Accessible name of the corner close button. Defaults to "Close".
`role`	`"dialog" \| "alertdialog" \| undefined`	`"dialog"`	Semantics of the panel. Defaults to "dialog".
`aria-label`	`string \| undefined`	—	Accessible name of the dialog. Use it only when there is no `DialogTitle`; a title automatically names the dialog.
`aria-labelledby`	`string \| undefined`	—	Overrides the id registered by `DialogTitle`.
`aria-describedby`	`string \| undefined`	—	Overrides the id registered by `DialogDescription`.
`className`	`string \| undefined`	—	Class applied to the panel.

children: ReactNode
No default extracted.
Header, body and footer of the dialog.
size: "sm" | "md" | "lg" | undefined
Default: "md"
Maximum width of the panel. Defaults to "md".
closeOnOverlayClick: boolean | undefined
Default: true
Close when the overlay is pressed. Defaults to true.
closeOnEscape: boolean | undefined
Default: true
Close on Escape. Defaults to true.
showCloseButton: boolean | undefined
Default: true
Render the close button in the top corner. Defaults to true.
closeLabel: string | undefined
Default: "Close"
Accessible name of the corner close button. Defaults to "Close".
role: "dialog" | "alertdialog" | undefined
Default: "dialog"
Semantics of the panel. Defaults to "dialog".
aria-label: string | undefined
No default extracted.
Accessible name of the dialog. Use it only when there is no `DialogTitle`; a title automatically names the dialog.
aria-labelledby: string | undefined
No default extracted.
Overrides the id registered by `DialogTitle`.
aria-describedby: string | undefined
No default extracted.
Overrides the id registered by `DialogDescription`.
className: string | undefined
No default extracted.
Class applied to the panel.

PimoluDialogHeaderProps

Type source

PimoluDialogHeaderProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

PimoluDialogTitleProps

Type source

PimoluDialogTitleProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`id`	`string \| undefined`	—	Explicit id, instead of the generated one.
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
id: string | undefined
No default extracted.
Explicit id, instead of the generated one.
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

PimoluDialogDescriptionProps

Type source

PimoluDialogDescriptionProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`id`	`string \| undefined`	—	Explicit id, instead of the generated one.
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
id: string | undefined
No default extracted.
Explicit id, instead of the generated one.
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

PimoluDialogFooterProps

Type source

PimoluDialogFooterProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`className`	`string \| undefined`	—	Public Pimolu prop; see the source declaration for details.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
className: string | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.

PimoluDialogCloseProps

Type source

PimoluDialogCloseProps public API
Name	Type	Default	Description
`children`Required	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	The element that closes the dialog: any element, or a component that passes down the props it receives. Its own click handler still runs.

childrenRequired: ReactElement<unknown, string | JSXElementConstructor<any>>
No default extracted.
The element that closes the dialog: any element, or a component that passes down the props it receives. Its own click handler still runs.

Accessibility

Use DialogTitle to name the panel and DialogDescription for context.
Verify focus is contained, Escape dismisses it and focus returns to the trigger. Avoid opening a modal without a clear way to close it.

Read the accessibility guide →

Preview

More examples

Anatomy

Sizes

Forms

Usage

API reference

PimoluDialogProps

PimoluDialogTriggerProps

PimoluDialogContentProps

PimoluDialogHeaderProps

PimoluDialogTitleProps

PimoluDialogDescriptionProps

PimoluDialogFooterProps

PimoluDialogCloseProps

Accessibility

Related components