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.

bui-DialogOverlay
bui-Dialog
bui-DialogInner
bui-DialogContent

Changelog#

Version 0.14.0#

Changes

Dialog Added ModalOverlay to Dialog so overlay styles are applied to the actual overlay rather than the modal content, and fixed dismissing via outside click in the process. #33785

Version 0.13.0#

Breaking Changes

Dialog Breaking Simplified the neutral background prop API for container components. The explicit neutral-1, neutral-2, neutral-3, and neutral-auto values have been removed from ProviderBg. They are replaced by a single 'neutral' value that always auto-increments from the parent context, making it impossible to skip or pin to an explicit neutral level. #33002

Migration Guide:

Replace any explicit bg="neutral-1", bg="neutral-2", bg="neutral-3", or bg="neutral-auto" props with bg="neutral". To achieve a specific neutral level in stories or tests, use nested containers — each additional bg="neutral" wrapper increments by one level.
```
// Before
<Box bg="neutral-2">...</Box>

// After
<Box bg="neutral">
  <Box bg="neutral">...</Box>
</Box>
```
Dialog Breaking Removed --bui-bg-popover CSS token. Popover, Tooltip, Menu, and Dialog now use --bui-bg-app for their outer shell and Box bg="neutral-1" for content areas, providing better theme consistency and eliminating a redundant token. #32979

Migration Guide:

Replace any usage of --bui-bg-popover with --bui-bg-neutral-1 (for content surfaces) or --bui-bg-app (for outer shells):
```
- background: var(--bui-bg-popover);
+ background: var(--bui-bg-neutral-1);
```

Changes

Dialog Migrated all components from useStyles to useDefinition hook. Exported OwnProps types for each component, enabling better type composition for consumers. #33050
Dialog Fixed Dialog content overflowing when no height prop is set. The dialog now grows with its content and scrolls when content exceeds the viewport height. #33352
DialogBody Extended AlertProps, ContainerProps, DialogBodyProps, and FieldLabelProps with native div element props to allow passing attributes like aria-* and data-*. #33095

Version 0.9.0#

Changes

Dialog Fixed dialog backdrop appearance in dark mode. #31673