An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Dialog.tsx
* @input Uses React, DialogHTMLAttributes, ReactNode, container (Layout), DialogContext, layerTextReset,
* layerStructureReset, modalOutlet, interactionModality, chainEventHandlers, holdEntranceInput
* @output Exports Dialog component, DialogProps, DialogVariant, DialogPurpose types
* @position Core implementation; consumed by index.ts, tested by Dialog.test.tsx
*
* The standard variant treats `width` as the preferred surface width, then
* clamps it to the dynamic viewport with spacing-token gutters so narrow
* viewports keep content and controls on screen without changing the public API.
* Fullscreen dialogs add safe-area protection to the default padding fallback
* while preserving explicit prop/theme padding overrides, and fade in without
* the centered-dialog translate/scale motion.
* Initial focus is applied after showModal; an explicit descendant request
* takes priority over a header's default title request.
*
* Under reduced motion the entrance never travels or scales
* (docs/design/reduced-motion.md): on a touch screen the dialog fades in
* where it lands, in 200 ms or less; with a mouse it appears at once.
*
* Initial focus and the focus returned on close follow the last input
* (docs/architecture/interaction-modality.md INV1): the shared focus indicator
* is hidden after a pointer press and shown after a key press.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
* - /packages/core/src/Dialog/__tests__/DialogTouchEntrance.interaction.browser.spec.ts (the touch entrance hold)
* - /packages/core/src/Dialog/index.ts (exports if types change)
* - /apps/storybook/stories/Dialog.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/Dialog/ (showcase blocks)
*/
import {
useCallback,
useEffect,
useId,
useLayoutEffect,
useMemo,
useRef,
useState,
type ReactNode,
} from 'react';
import {useIsHydrating} from '../hooks/useIsHydrating';
import {useSettledOpen} from '../hooks/useSettledOpen';
import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
import {useScrollLock} from '../hooks/useScrollLock';
import {layerTextReset} from '../Layer/layerTextReset.stylex';
import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
import {LayerContentBoundary} from '../Layer/layerScopedContext';
import {layerClickBoundary} from '../Layer/layerClickBoundary';
import {LayerDepthProvider} from '../Layer/LayerDepthContext';
import {holdEntranceInput} from '../Layer/holdEntranceInput';
import {useLayerDismissal} from '../Layer/useLayerDismissal';
import {useBackdropPress} from '../Layer/useBackdropPress';
import {useFocusRegionContainment} from '../hooks/useFocusTrap';
import {useModalOutlet} from '../Layer/modalOutlet';
import {
colorVars,
radiusVars,
durationVars,
easeVars,
shadowVars,
spacingVars,
} from '../theme/tokens.stylex';
import {container} from '../Layout/container.stylex';
import {containerCornerStyles} from '../Layout/containerCorners.stylex';
import type {SpacingToken} from '../Layout/container.stylex';
import {
paddingStyles,
containerPaddingInlineVarStyles,
containerPaddingBlockStartVarStyles,
containerPaddingBlockEndVarStyles,
spacingStepToToken,
overlayPaddingReset,
} from '../Layout/padding.stylex';
import type {SpacingStep} from '../utils/types';
import {mergeProps} from '../utils/mergeProps';
import {chainEventHandlers} from '../utils/chainEventHandlers';
import {createDevWarnings} from '../utils/devWarning';
import {DialogContext} from './DialogContext';
import {themeProps} from '../utils/themeProps';
import type {DialogVariantMap} from './index';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {useInteractionModalityTracking} from '../utils/interactionModality';
import {
focusForLastInput,
prepareFocusReturnOnRemoval,
returnFocusForLastInput,
} from '../utils/focusReturn';
import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
import {useMergedRefs} from '../hooks/useMergedRefs';
type PointerHandler = (event: React.PointerEvent<HTMLDialogElement>) => void;
/**
* Calculate a directional translate offset for dialog entry animation.
* Returns a normalized vector from the trigger element toward the viewport
* center, scaled to the given distance.
*/
function getDialogDirection(
triggerEl: HTMLElement,
distance = 16,
): {x: number; y: number} {
const rect = triggerEl.getBoundingClientRect();
// The trigger's own window: its rect is measured in that window's viewport,
// which is not the page's when the dialog renders into a second document.
const view = triggerEl.ownerDocument.defaultView ?? window;
const dx = rect.left + rect.width / 2 - view.innerWidth / 2;
const dy = rect.top + rect.height / 2 - view.innerHeight / 2;
const dist = Math.sqrt(dx * dx + dy * dy) || 1;
return {
x: Math.round((dx / dist) * distance),
y: Math.round((dy / dist) * distance),
};
}
/**
* Dialog variant type
* - standard: Normal dialog with configurable width/height
* - fullscreen: Takes up the entire viewport
*
* Extensible via module augmentation of DialogVariantMap.
*/
export type DialogVariant = keyof DialogVariantMap;
/**
* Dialog purpose type - controls dismissal behavior
* - required: Mandatory flows (security, permissions) - disables all exit methods
* - form: User forms/flows - prevents backdrop click, allows escape
* - info: Informational flows - allows all exit methods
*/
export type DialogPurpose = 'required' | 'form' | 'info';
/** Block-axis offsets — always allowed, independent of inline direction. */
interface DialogBlockPosition {
top?: number | string;
bottom?: number | string;
}
/**
* Static position for a dialog. The inline axis is logical XOR physical — the
* type forbids mixing the two, so a single dialog can't be positioned both ways:
* - Logical `start`/`end` map to `inset-inline-*` and mirror under RTL (preferred).
* Block-axis `top`/`bottom` may be combined with either.
*/
export interface DialogPosition extends DialogBlockPosition {
/** Logical inline-start offset (`inset-inline-start`); mirrors under RTL. */
start?: number | string;
/** Logical inline-end offset (`inset-inline-end`); mirrors under RTL. */
end?: number | string;
}
const enterDirectional = stylex.keyframes({
from: {
opacity: 0,
transform:
'translate(var(--dialog-dir-x, 0px), var(--dialog-dir-y, 16px)) scale(0.95)',
},
to: {opacity: 1, transform: 'translate(0, 0) scale(1)'},
});
const enterFullscreen = stylex.keyframes({
from: {opacity: 0},
to: {opacity: 1},
});
const dialogFullscreenSafeAreaBlockStartPadding = `var(--astryx-dialog-padding-block-start, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))))`;
const dialogFullscreenSafeAreaBlockEndPadding = `var(--astryx-dialog-padding-block-end, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-bottom, 0px))))`;
const dialogFullscreenSafeAreaInlineStartPaddingLtr = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
const dialogFullscreenSafeAreaInlineStartPaddingRtl = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
const dialogFullscreenSafeAreaInlineEndPaddingLtr = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
const dialogFullscreenSafeAreaInlineEndPaddingRtl = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
/** @internal Verified by Dialog.test.tsx; not re-exported from the package entry point. */
export const dialogFullscreenSafeAreaPaddingContract = {
blockStart: dialogFullscreenSafeAreaBlockStartPadding,
blockEnd: dialogFullscreenSafeAreaBlockEndPadding,
inlineStart: {
ltr: dialogFullscreenSafeAreaInlineStartPaddingLtr,
rtl: dialogFullscreenSafeAreaInlineStartPaddingRtl,
},
inlineEnd: {
ltr: dialogFullscreenSafeAreaInlineEndPaddingLtr,
rtl: dialogFullscreenSafeAreaInlineEndPaddingRtl,
},
} as const;
/**
* Dialog styles using native <dialog> element
* Uses ::backdrop pseudo-element for overlay
*/
const styles = stylex.create({
dialog: {
position: 'fixed',
margin: 'auto',
padding: 0,
// The backdrop does not blur the page. Forced colors override the
// backdrop's colour, so a 1px border keeps the modal separate from the
// page. It is a border, not an outline: the focus ring
// (focusOutlineProps) owns the outline longhands on this element.
borderWidth: {
default: 0,
'@media (forced-colors: active)': 1,
},
borderStyle: {
default: 'none',
'@media (forced-colors: active)': 'solid',
},
borderColor: {
default: null,
'@media (forced-colors: active)': 'CanvasText',
},
backgroundColor: colorVars['--color-background-surface'],
'--_dialog-radius': radiusVars['--radius-container'],
borderRadius: 'var(--_dialog-radius)',
boxShadow: shadowVars['--shadow-high'],
display: 'none',
flexDirection: 'column',
height: 'fit-content',
overscrollBehavior: 'contain',
opacity: 0,
// Under reduced motion on a touch screen the entrance is the shared
// reduced-motion cross-fade, 200 ms on easeInOut whatever the theme's
// duration (design:reduced-motion DR2, DR4). Moves to
// reducedMotionFadeConsts once that is on main.
animationDuration: {
default: durationVars['--duration-medium-max'],
'@media (prefers-reduced-motion: reduce) and (pointer: coarse)': '200ms',
},
animationTimingFunction: {
default: easeVars['--ease-standard'],
'@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
'cubic-bezier(0.42, 0, 0.58, 1)',
},
animationFillMode: 'backwards' as const,
},
// Applied via isOpen prop — avoids :where([open]) attribute selectors
// which have zero specificity and can lose to default styles depending
// on CSS source order in the build output.
open: {
display: 'flex',
opacity: 1,
// Under `prefers-reduced-motion: reduce` the dialog never travels or
// scales in (design:reduced-motion DR1): on a touch screen it fades in
// where it lands (DR2), and with a mouse it appears at once (DR3).
animationName: {
default: enterDirectional,
'@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
enterFullscreen,
'@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
'none',
},
},
// A dialog present on page load opens where it rests (spec:AST-013 FR13).
openSettled: {
animationName: 'none',
},
// No backdrop-filter: a full-viewport blur is costly to repaint.
backdrop: {
'::backdrop': {
backgroundColor: colorVars['--color-overlay'],
},
},
fullscreen: {
width: '100dvw',
height: '100dvh',
maxWidth: '100dvw',
maxHeight: '100dvh',
'--_dialog-radius': '0px',
borderRadius: 0,
// Nothing of the page shows around a full-screen dialog: no edge.
borderWidth: 0,
margin: 0,
inset: 0,
},
fullscreenOpen: {
animationName: {
default: enterFullscreen,
'@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
enterFullscreen,
'@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
'none',
},
},
fullscreenSafeArea: {
paddingBlockStart: dialogFullscreenSafeAreaBlockStartPadding,
paddingBlockEnd: dialogFullscreenSafeAreaBlockEndPadding,
paddingInlineStart: {
default: dialogFullscreenSafeAreaInlineStartPaddingLtr,
':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineStartPaddingRtl,
},
paddingInlineEnd: {
default: dialogFullscreenSafeAreaInlineEndPaddingLtr,
':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineEndPaddingRtl,
},
},
inner: {
display: 'flex',
flexDirection: 'column',
flex: '1 1 auto',
minHeight: 0,
overflow: 'hidden',
borderRadius: 'inherit',
},
innerCorners: {
'--_container-corner-block-start': 'var(--_dialog-radius)',
'--_container-corner-block-end': 'var(--_dialog-radius)',
},
// Inline wrapper mirrors the dialog's visual styles without <dialog> behavior
inlineWrapper: {
padding: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: colorVars['--color-background-surface'],
'--_dialog-radius': radiusVars['--radius-container'],
borderRadius: 'var(--_dialog-radius)',
boxShadow: shadowVars['--shadow-high'],
display: 'flex',
flexDirection: 'column',
height: 'fit-content',
overscrollBehavior: 'contain',
},
});
const STANDARD_DIALOG_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
const STANDARD_DIALOG_VIEWPORT_MAX_WIDTH = `calc(100dvw - ${STANDARD_DIALOG_VIEWPORT_GUTTER} - ${STANDARD_DIALOG_VIEWPORT_GUTTER})`;
const STANDARD_DIALOG_MAX_WIDTH = `min(100%, ${STANDARD_DIALOG_VIEWPORT_MAX_WIDTH})`;
function formatSizeValue(value: number | string): string {
return typeof value === 'number' ? `${value}px` : value;
}
function resolveDialogSizing(
width: number | string,
maxHeight: number | string,
) {
return {
width: formatSizeValue(width),
maxWidth: STANDARD_DIALOG_MAX_WIDTH,
maxHeight: formatSizeValue(maxHeight),
};
}
const dynamicStyles = stylex.create({
sizing: (width: string, maxWidth: string, maxHeight: string) => ({
width,
maxWidth,
maxHeight,
}),
position: (
top: string,
insetInlineStart: string,
insetInlineEnd: string,
bottom: string,
) => ({
// Assigns pre-resolved offsets from resolveDialogPositionOffsets(). This
// literal has no logic — StyleX can't analyze a helper, so the values
// (logical start/end → inset-inline-*, physical left/right, `auto`
// fallbacks) are computed at the call site and passed in.
margin: 0,
top,
insetInlineStart,
insetInlineEnd,
bottom,
}),
});
/**
* Format position value - numbers become pixels, strings pass through, undefined becomes null
*/
function formatPosition(value: number | string): string {
return typeof value === 'number' ? `${value}px` : value;
}
/**
* Map a {@link DialogPosition} to resolved CSS offsets. Logical `start`/`end`
* become `inset-inline-*` (mirror under RTL); each unset offset falls back to
* `auto`.
*
* Not re-exported from the package; internal to Dialog. Directly unit-tested
* so the mapping is verified without StyleX class compilation.
*
* @see DialogPosition
*/
export function resolveDialogPositionOffsets(position: DialogPosition) {
const {top, bottom, start, end} = position;
return {
top: top !== undefined ? formatPosition(top) : 'auto',
bottom: bottom !== undefined ? formatPosition(bottom) : 'auto',
// Logical offsets mirror under RTL (preferred replacements).
insetInlineStart: start !== undefined ? formatPosition(start) : 'auto',
insetInlineEnd: end !== undefined ? formatPosition(end) : 'auto',
};
}
export interface DialogProps extends BaseProps<HTMLDialogElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLDialogElement>;
/**
* Whether the dialog is open.
*/
isOpen: boolean;
/**
* Renders dialog content inline without the <dialog> element, backdrop,
* modal behavior, or dialog-managed autofocus. Intended for documentation
* previews and showcases only — not for production UIs. The dialog will not
* trap focus or respond to Escape.
* @default false
*/
isInline?: boolean;
/**
* Callback fired when the dialog visibility changes.
* Called with `false` when the dialog requests to be hidden.
* Behavior depends on the `purpose` prop:
* - required: Never called automatically
* - form: Called on Escape key only
* - info: Called on Escape key and backdrop click
*/
onOpenChange: (isOpen: boolean) => unknown;
/**
* The width of the dialog.
* Numbers are treated as pixels, strings are used as-is.
* Ignored when variant is 'fullscreen'.
* @default 400
*/
width?: number | string;
/**
* The maximum height of the dialog.
* The actual height will be the height of its content.
* Numbers are treated as pixels, strings are used as-is.
* Ignored when variant is 'fullscreen'.
* @default '75dvh'
*/
maxHeight?: number | string;
/**
* Static position for the dialog on screen.
* By default, the dialog will be centered.
* Ignored when variant is 'fullscreen'.
*/
position?: Readonly<DialogPosition>;
/**
* The variant of the dialog.
* - standard: Normal dialog with configurable dimensions
* - fullscreen: Takes up the entire viewport
* @default 'standard'
*/
variant?: DialogVariant;
/**
* Configures how the dialog enables dismissals.
* - required: Disables all exit methods (for mandatory flows)
* - form: Prevents backdrop click, allows Escape key
* - info: Allows all exit methods (Escape and backdrop click)
* @default 'info'
*/
purpose?: DialogPurpose;
/**
* Internal padding of the dialog using the spacing scale.
* Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
* When omitted, uses the theme default for dialogs.
*/
padding?: SpacingStep;
/**
* The content of the dialog.
* Typically an Layout with header, content, and footer slots.
*/
children: ReactNode;
}
/**
* A dialog component using the native <dialog> element.
*
* Designed to be used with Layout as its child for structured content.
* Uses the browser's built-in modal behavior for optimal accessibility.
* When a DialogHeader is rendered inside, its title automatically names the
* dialog via aria-labelledby; pass `aria-label` or `aria-labelledby` to
* override.
*
* @example
* ```
* const [isOpen, setIsOpen] = useState(false);
* <Dialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
* <Layout
* header={<DialogHeader title="Title" onOpenChange={open => setIsOpen(open)} />}
* content={<LayoutContent>Content</LayoutContent>}
* footer={<LayoutFooter hasDivider>Actions</LayoutFooter>}
* />
* </Dialog>
* ```
*/
export function Dialog({
isOpen: isOpenProp,
isInline = false,
onOpenChange,
width = 400,
maxHeight = '75dvh',
position,
variant = 'standard',
purpose = 'info',
padding,
children,
xstyle,
className,
style,
ref,
...props
}: DialogProps) {
// A modal dialog open on the server renders closed until hydration, and
// opens in the render after it, the first one that can call showModal(): a
// <dialog> painted open with aria-modal before it is modal claims a state it
// does not have, over a live page (FR8). An inline dialog is not modal and
// renders as it is.
const isHydrating = useIsHydrating();
const isOpen = isOpenProp && (isInline || !isHydrating);
// A dialog open on the server was present on page load, so it opens settled,
// with no entry motion; its later opens animate as usual (spec:AST-013 FR13).
const [settledOpen] = useSettledOpen(isOpenProp && !isInline, isOpen, false);
const opensSettled = settledOpen && isOpen;
// When no explicit padding prop, use theme default (--astryx-dialog-padding)
const useThemeDefault = padding == null;
const effectivePadding = padding ?? 4;
const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
const isFullscreen = variant === 'fullscreen';
const standardSizing = isFullscreen
? null
: resolveDialogSizing(width, maxHeight);
// Default accessible name: publish a title id through DialogContext so a
// DialogHeader applies it to its heading (mirrors AlertDialog's explicit
// useId wiring). Whether to emit the default aria-labelledby is decided
// imperatively in the callback ref below by checking whether the title
// element actually rendered — so a dialog with no header never points at a
// missing id, and we avoid the extra render a registration-via-state effect
// would cost at the dialog level.
const titleId = useId();
// Consumer-provided labels always win over the DialogHeader default.
const hasConsumerName =
props['aria-label'] != null || props['aria-labelledby'] != null;
const dialogRef = useRef<HTMLDialogElement>(null);
// Native showModal() lets Tab leave for the browser's own UI, so the shared
// module wraps it. An inline preview is not modal and contains nothing.
useFocusRegionContainment(dialogRef, isOpen && !isInline);
// Callback ref on the <dialog>: sync the default aria-labelledby from the
// DialogHeader title (if one rendered) in the same commit, with no second
// render. Consumer aria-label/aria-labelledby win — when present we leave
// the attribute to the {...safeProps} spread and never touch it here.
const attachDialog = useCallback(
(node: HTMLDialogElement | null) => {
dialogRef.current = node;
if (!node || hasConsumerName) {
return;
}
const hasTitle = node.querySelector(`#${CSS.escape(titleId)}`) != null;
if (hasTitle) {
node.setAttribute('aria-labelledby', titleId);
} else {
node.removeAttribute('aria-labelledby');
}
},
[titleId, hasConsumerName],
);
// A composed header whose title renders after the dialog mounted asks the
// dialog to look for the title again.
const syncDefaultName = useCallback(() => {
if (dialogRef.current != null) {
attachDialog(dialogRef.current);
}
}, [attachDialog]);
const dialogContextValue = useMemo(
() => ({isInline, titleId, syncDefaultName}),
[isInline, titleId, syncDefaultName],
);
// Input in a second document (a same-origin iframe, a Document
// Picture-in-Picture window) never reaches the page's listeners, so the
// dialog's own document keeps its own last input for the focus return while
// this Dialog is mounted, from before it opens until it unmounts.
const {ref: modalityRef} = useInteractionModalityTracking();
const mergedDialogRef = useMergedRefs(ref, attachDialog, modalityRef);
// Capture the element that was focused when the dialog opened, for
// directional animation origin and focus restoration on close.
const triggerElementRef = useRef<HTMLElement | null>(null);
// This runs in a layout effect so the capture lands before any descendant's
// passive mount effect: all layout effects run before any passive effect,
// while a child's passive effect runs before this parent's passive effect.
// Content that mounts in the open commit — e.g. a DialogHeader focusing its
// own title on mount — would otherwise move document.activeElement inside
// the dialog before the capture ran, and closing would then restore focus
// to a detached node, stranding the user's focus on <body>.
//
// Only the closed-to-open edge captures. StrictMode replays this effect
// after the open commit's passive effects. By then Dialog has focused the
// title, so a replayed capture would take the title as the opener. The ref
// survives the replay. It starts false, so a dialog first mounted open still
// captures.
const wasOpenRef = useRef(false);
useLayoutEffect(() => {
const isOpenNow = !isInline && isOpen;
if (isOpenNow && !wasOpenRef.current) {
// The dialog's own document while it holds focus: an app can render a
// dialog into a second document (a same-origin iframe, a Document
// Picture-in-Picture window) through a portal, and a control there that
// opens it is focused in that document, which the page's document reports
// only as the iframe element, or not at all. A control in the page that
// opens such a dialog leaves focus in the page.
const dialogDocument = dialogRef.current?.ownerDocument ?? document;
const doc = dialogDocument.hasFocus() ? dialogDocument : document;
triggerElementRef.current = doc.activeElement as HTMLElement | null;
}
wasOpenRef.current = isOpenNow;
}, [isOpen, isInline]);
// Derive dismissal behavior from purpose
const allowEscape = purpose !== 'required';
const allowBackdropClick = purpose === 'info';
// Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
// An inline dialog is not in the top layer, so it skips this.
useEffect(() => {
if (isInline) {
return;
}
const dialog = dialogRef.current;
if (!dialog) {
return;
}
if (isOpen) {
// Set directional CSS custom properties before opening. The trigger was
// captured by the layout effect above, before any descendant effect
// could move focus.
const trigger = triggerElementRef.current;
if (trigger && trigger !== trigger.ownerDocument.body) {
const dir = getDialogDirection(trigger);
dialog.style.setProperty('--dialog-dir-x', `${dir.x}px`);
dialog.style.setProperty('--dialog-dir-y', `${dir.y}px`);
} else {
dialog.style.setProperty('--dialog-dir-x', '0px');
dialog.style.setProperty('--dialog-dir-y', '16px');
}
if (!dialog.open) {
dialog.showModal();
// React's autoFocus calls .focus() during commit, before showModal()
// makes the dialog visible, so the focus silently fails.
// Explicit descendant intent takes priority over a header's default
// title. Keep the marker private to the focus-owning components.
const autofocusTargets = [
...dialog.querySelectorAll<HTMLElement>(
'[data-autofocus]:not([data-autofocus="dialog-title"])',
),
...dialog.querySelectorAll<HTMLElement>(
'[data-autofocus="dialog-title"]',
),
];
for (const target of autofocusTargets) {
// Only hiding inside the dialog makes a request ineligible: the
// modal dialog is not part of an inert region around it.
const hiddenAncestor = target.closest(
'[hidden], [inert], [aria-hidden="true"]',
);
if (hiddenAncestor != null && dialog.contains(hiddenAncestor)) {
continue;
}
// Disabled and CSS-hidden targets cannot receive focus in the
// browser. If a request cannot land, try the next eligible request
// and finally the title; otherwise preserve native initial focus.
// The dialog's own document reports its focus, also when the dialog
// renders in an iframe or a Picture-in-Picture window.
focusForLastInput(target);
if (target.ownerDocument.activeElement === target) {
break;
}
}
}
// Under a coarse primary pointer, a tap or a drag during the entrance
// reaches nothing. Keys and assistive technology stay live. The hold
// ends with the entrance, or with this effect's cleanup on a close or
// unmount.
return holdEntranceInput(dialog) ?? undefined;
} else {
if (dialog.open) {
dialog.close();
}
// Return focus to the element that opened the dialog, with the ring
// the last input in that element's own document calls for.
const trigger = triggerElementRef.current;
if (trigger) {
returnFocusForLastInput(trigger);
}
triggerElementRef.current = null;
}
}, [isOpen, isInline]);
// A dialog that unmounts while open (rendered only while open, or removed
// with the rest of a view) never runs the close branch above. Focus the
// removal lost goes back to the opener.
useEffect(() => {
const dialog = dialogRef.current;
if (isInline || dialog == null) {
return;
}
const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
return () => returnFocusOnRemoval(triggerElementRef.current);
}, [isInline]);
// Host app-global surfaces (toasts) inside this modal while it is open, so
// they stay visible and operable above it.
const outletRef = useModalOutlet(dialogRef, isOpen && !isInline);
// Lock body scroll when dialog is open (iOS Safari workaround)
// Skip for inline rendering — no modal overlay to compensate for.
useScrollLock(isOpen && !isInline);
// Join the shared layer dismissal stack. The stack owns the Escape listener
// and routes each press to the top-most layer, so this dialog does not listen
// itself — that is what stops a modal opened from inside another modal (or a
// popover opened inside this one) from closing two layers on one press.
//
// A `required` dialog registers as `block`: it must not be dismissed, and the
// press must not fall through and dismiss a layer behind it either.
//
// Inline mode opts out — it renders dialog content in normal flow, with
// nothing layered over anything.
const {shouldDismissOnCloseRequest} = useLayerDismissal({
isActive: isOpen,
isEnabled: !isInline,
escapeBehavior: allowEscape ? 'close' : 'block',
onDismiss: () => {
onOpenChange(false);
},
// The dialog's document is this layer's: rendered into an iframe or a
// Picture-in-Picture window, it ranks with the layers opened inside it.
getContainer: () => dialogRef.current,
});
// Dev-time guardrail: an open modal should always have an accessible name.
// The header-title check reads the DOM, so this stays in an effect.
const [warn] = useState(createDevWarnings);
useEffect(() => {
const hasHeaderTitle =
dialogRef.current?.querySelector(`#${CSS.escape(titleId)}`) != null;
if (isOpen && !isInline && !hasConsumerName && !hasHeaderTitle) {
warn(
'Dialog',
'open dialog has no accessible name. Add a DialogHeader ' +
'with a `title`, or pass `aria-label`/`aria-labelledby`.',
);
}
}, [isOpen, isInline, hasConsumerName, titleId, warn]);
// A press on the ::backdrop targets the <dialog> itself, so native browser
// popups (date pickers, selects, color pickers) that render outside the
// dialog's rect never count. The press must start and end there.
const handleBackdropPress = useCallback(() => {
onOpenChange(false);
}, [onOpenChange]);
const backdropPress = useBackdropPress(
handleBackdropPress,
allowBackdropClick,
);
// The native `cancel` event is the browser's own close-watcher firing: an
// Android back gesture, or a close request the stack never saw a press for.
// Escape presses the stack owns never arrive here — it preventDefault()s
// those, which suppresses the close watcher.
//
// A `cancel` that bubbles up from inside is not a close request for this
// dialog: a file input fires one when its picker is dismissed. It is left
// alone. Otherwise always preventDefault so the browser cannot close a
// controlled <dialog> behind React's back, then answer the request with the
// stack's own rules: only the top-most layer dismisses, a `required` dialog
// swallows it, and nothing dismisses while an IME composition is in progress.
const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
if (event.target !== event.currentTarget) {
return;
}
event.preventDefault();
if (!shouldDismissOnCloseRequest()) {
return;
}
if (allowEscape) {
onOpenChange(false);
}
};
const innerContent = (
<div
ref={outletRef}
{...stylex.props(
styles.inner,
...container(
useThemeDefault
? {
useThemeDefault: 'dialog',
maxHeight: standardSizing?.maxHeight,
}
: {
paddingInnerX: paddingToken,
paddingInnerY: paddingToken,
paddingOuterX: paddingToken,
paddingOuterY: paddingToken,
maxHeight: standardSizing?.maxHeight,
},
),
!useThemeDefault &&
effectivePadding !== 4 &&
paddingStyles[effectivePadding],
!useThemeDefault &&
effectivePadding !== 4 &&
containerPaddingInlineVarStyles[effectivePadding],
!useThemeDefault &&
effectivePadding !== 4 &&
containerPaddingBlockStartVarStyles[effectivePadding],
!useThemeDefault &&
effectivePadding !== 4 &&
containerPaddingBlockEndVarStyles[effectivePadding],
isFullscreen && useThemeDefault && styles.fullscreenSafeArea,
styles.innerCorners,
containerCornerStyles.publish,
)}>
<DialogContext value={dialogContextValue}>{children}</DialogContext>
</div>
);
// Filter out native open to prevent InvalidStateError when accidentally passed.
// Keep the consumer click handler separate so the modal path can compose it
// with Dialog-owned behavior without changing the inline preview path.
const hasPosition = position != null && !isFullscreen;
const {onClick: onClickProp, ...propsWithoutClick} = props;
const {open: _open, ...safeProps} = propsWithoutClick as Record<
string,
unknown
>;
const inlineSafeProps: Record<string, unknown> = {
...safeProps,
onClick: onClickProp,
};
// --- Inline rendering path (for documentation previews) ---
if (isInline) {
if (!isOpen) {
return null;
}
return (
<div
{...inlineSafeProps}
{...mergeProps(
themeProps('dialog', {variant}),
stylex.props(
layerTextReset.reset,
layerStructureReset.reset,
styles.inlineWrapper,
overlayPaddingReset.reset,
standardSizing &&
dynamicStyles.sizing(
standardSizing.width,
standardSizing.maxWidth,
standardSizing.maxHeight,
),
isFullscreen && styles.fullscreen,
xstyle,
),
className,
style,
)}
data-testid={
(props as Record<string, unknown>)['data-testid'] as
string | undefined
}>
<LayerDepthProvider>
<LayerContentBoundary>{innerContent}</LayerContentBoundary>
</LayerDepthProvider>
</div>
);
}
// --- Standard modal rendering path ---
return (
<dialog
ref={mergedDialogRef}
{...safeProps}
{...mergeProps(
themeProps('dialog', {variant}),
focusOutlineProps.focusVisible(
layerTextReset.reset,
layerStructureReset.reset,
styles.dialog,
overlayPaddingReset.reset,
isOpen && styles.open,
styles.backdrop,
standardSizing &&
dynamicStyles.sizing(
standardSizing.width,
standardSizing.maxWidth,
standardSizing.maxHeight,
),
hasPosition &&
(() => {
const o = resolveDialogPositionOffsets(position);
return dynamicStyles.position(
o.top,
o.insetInlineStart,
o.insetInlineEnd,
o.bottom,
);
})(),
isFullscreen && styles.fullscreen,
isFullscreen && isOpen && styles.fullscreenOpen,
opensSettled && styles.openSettled,
xstyle,
),
className,
style,
)}
// Presses inside the dialog do not reach handlers around where it is
// written.
{...layerClickBoundary({
...safeProps,
onClick: chainEventHandlers(backdropPress.onClick, onClickProp),
})}
onPointerDownCapture={chainEventHandlers(
backdropPress.onPointerDownCapture,
safeProps.onPointerDownCapture as PointerHandler | undefined,
)}
onPointerUpCapture={chainEventHandlers(
backdropPress.onPointerUpCapture,
safeProps.onPointerUpCapture as PointerHandler | undefined,
)}
onPointerCancelCapture={chainEventHandlers(
backdropPress.onPointerCancelCapture,
safeProps.onPointerCancelCapture as PointerHandler | undefined,
)}
onCancel={handleCancel}
aria-modal={isHydrating ? undefined : 'true'}
// The default aria-labelledby (from a DialogHeader title) is set
// imperatively in `attachDialog`; a consumer-provided aria-labelledby
// flows through {...safeProps} above and wins.
{...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
<ModalAnnounceProvider dialogRef={dialogRef} isOpen={isOpen}>
<LayerDepthProvider>
<LayerContentBoundary>{innerContent}</LayerContentBoundary>
</LayerDepthProvider>
</ModalAnnounceProvider>
</dialog>
);
}
Dialog.displayName = 'Dialog';