Modal dialog using the native <dialog> element. Modal and inline content starts with theme body text defaults. Ancestor surface/group membership ends as a whole, including group-owned state. Explicit props and unrelated contexts remain unchanged. Place intentional groups and complete required providers inside the dialog.
Preview loads on approachPreview loads on approach
Exact source · dialog-showcase
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
import {Dialog, DialogHeader} from '@astryxdesign/core/Dialog';
import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';
// Remove isInline for production — dialogs should be modal.
export default function DialogShowcase() {
return (
<Dialog isOpen isInline onOpenChange={() => {}}>
<Layout
header={<DialogHeader title="Modal Title" onOpenChange={() => {}} />}
content={
<LayoutContent>
<Text type="body">Dialog content goes here.</Text>
</LayoutContent>
}
/>
</Dialog>
);
}
Usage
Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped. For cases where you want to show a dialog without managing open state, use the useImperativeDialog hook: call dialog.show(content) and render dialog.element in your tree.
Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.
Include a clear title in the header so users immediately understand what the dialog is asking.
Use purpose="form" for dialogs with inputs so the user can't accidentally lose data by clicking the backdrop.
Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.
Use a dialog for simple messages that could be shown inline or as a toast notification.
Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.
Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.
Preferred width of the dialog in pixels or any CSS value. Standard dialogs clamp to their container and the dynamic viewport with spacing-token gutters so narrow viewports keep content on screen.
maxHeight
number | string · default '75dvh'
Maximum height of the dialog. Defaults to a dynamic viewport value so browser UI changes are reflected where supported.
position
DialogPosition
Static position for the dialog; centered by default when omitted. Use logical start/end for inline offsets so positioned dialogs mirror correctly under RTL.
variant
'standard' | 'fullscreen' · default 'standard'
Dialog variant: fullscreen expands to fill the entire viewport.
purpose
'required' | 'form' | 'info' · default 'info'
Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.
padding
0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10
Internal padding of the dialog using the spacing scale step.
isInline
boolean · default false
Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only.
Anatomy
Header · required
Title, optional subtitle, and close button. The title receives focus on open and labels the dialog via aria-labelledby.
Body · required
The main content area: text, forms, lists, or any layout.
Footer · optional
Action buttons like Save/Cancel or Accept/Decline, aligned to the end.
Backdrop · required
Semi-transparent overlay behind the dialog that blocks page interaction.
