Dialog

A modal dialog with header, body, and footer sections supporting controlled state.

Usage#

import { 
  Dialog, 
  DialogTrigger, 
  DialogHeader, 
  DialogBody, 
  DialogFooter, 
} from '@backstage/ui';

<DialogTrigger>
  <Button>Open Dialog</Button>
  <Dialog>
    <DialogHeader>Title</DialogHeader>
    <DialogBody>Content</DialogBody>
    <DialogFooter>
      <Button variant="secondary" slot="close">Close</Button>
    </DialogFooter>
  </Dialog>
</DialogTrigger>

API reference#

DialogTrigger#

Wraps a trigger element and the dialog content to handle open/close state.

Prop	Type	Default	Description
children	ReactNode	-	Trigger element and dialog content.
isOpen	boolean	-	Whether the overlay is open by default (controlled).
defaultOpen	boolean	-	Whether the overlay is open by default (uncontrolled).
onOpenChange	(isOpen: boolean) => void	-	Handler that is called when the overlay's open state changes.

Inherits all React Aria DialogTrigger props.

Dialog#

The main dialog container that renders as a modal overlay.

Prop	Type	Default	Description
children	ReactNode	-	Dialog content (DialogHeader, DialogBody, DialogFooter).
isOpen	boolean	-	Whether the overlay is open (controlled mode).
defaultOpen	boolean	-	Initial open state (uncontrolled mode).
onOpenChange	(isOpen: boolean) => void	-	Called when the open state changes.
width	numberstring	400	Fixed width in pixels (number) or CSS units (string).
height	numberstring	auto	Fixed height in pixels (number) or CSS units (string).
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

Inherits all React Aria Modal props.

DialogHeader#

Displays the dialog title with a built-in close button.

Prop	Type	Default	Description
children	ReactNode	-	Dialog title text.
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

Inherits all React Aria Heading props.

DialogBody#

The main content area of the dialog with optional scrolling.

Prop	Type	Default	Description
children	ReactNode	-	Main content of the dialog.
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

DialogFooter#

Contains action buttons or other footer content.

Prop	Type	Default	Description
children	ReactNode	-	Action buttons or footer content.
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

If you want to close the dialog while pressing a button, you can use the slot="close" prop on the button.

<Button slot="close">Close</Button>

Examples#

Fixed Width and Height#

Dialog with a fixed height body that scrolls when content overflows.

Dialog with Form#

Forms can be embedded in the dialog body.

Dialog with no trigger and controlled by props#

You can also control the dialog using your own states.

const [isOpen, setIsOpen] = useState(false);

<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <DialogHeader>Create New User</DialogHeader>
  <DialogBody>
    Your content
  </DialogBody>
  <DialogFooter>
    <Button variant="secondary" slot="close">Cancel</Button>
    <Button variant="primary" slot="close">Create User</Button>
  </DialogFooter>
</Dialog>

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.