Modal and overlay components for contextual information, user interactions, notifications, and help content with focus management and accessibility.
Modal dialog components for important user interactions and confirmations.
/**
* Modal dialog for important user interactions
* @param props - Dialog content and behavior properties
* @returns JSX element as modal dialog
*/
function Dialog(props: SpectrumDialogProps): JSX.Element;
/**
* Trigger component that opens dialogs on user interaction
* @param props - Dialog trigger configuration and content
* @returns JSX element as dialog trigger button
*/
function DialogTrigger(props: SpectrumDialogTriggerProps): JSX.Element;
interface SpectrumDialogProps extends DOMProps, StyleProps {
/** Dialog content */
children: React.ReactNode;
/** Dialog size */
size?: "S" | "M" | "L" | "fullscreen" | "fullscreenTakeover";
/** Whether dialog can be dismissed by clicking outside */
isDismissable?: boolean;
/** Whether to show close button */
isKeyboardDismissDisabled?: boolean;
/** Dismiss handler */
onDismiss?: () => void;
/** Dialog type for styling */
type?: "modal" | "fullscreen" | "fullscreenTakeover";
}
interface SpectrumDialogTriggerProps extends DOMProps {
/** Trigger element and dialog */
children: [React.ReactElement, React.ReactElement];
/** Dialog trigger type */
type?: "modal" | "popover" | "tray";
/** Whether dialog is open (controlled) */
isOpen?: boolean;
/** Default open state (uncontrolled) */
defaultOpen?: boolean;
/** Open state change handler */
onOpenChange?: (isOpen: boolean) => void;
/** Target element for popover positioning */
targetRef?: React.RefObject<Element>;
/** Dialog placement for popovers */
placement?: Placement;
/** Container padding for mobile */
containerPadding?: number;
/** Offset from target */
offset?: number;
/** Cross offset from target */
crossOffset?: number;
/** Whether popover should flip when space is limited */
shouldFlip?: boolean;
/** Whether dialog should update position */
shouldUpdatePosition?: boolean;
}Specialized dialog for alerts, confirmations, and destructive actions.
/**
* Alert dialog for confirmations and important messages
* @param props - AlertDialog content and action properties
* @returns JSX element as alert dialog
*/
function AlertDialog(props: SpectrumAlertDialogProps): JSX.Element;
interface SpectrumAlertDialogProps extends Omit<SpectrumDialogProps, 'type'> {
/** Alert dialog variant */
variant?: "confirmation" | "information" | "warning" | "error" | "destructive";
/** Dialog title */
title: React.ReactNode;
/** Primary action button */
primaryActionLabel: React.ReactNode;
/** Secondary action button (optional) */
secondaryActionLabel?: React.ReactNode;
/** Cancel button label (optional) */
cancelLabel?: React.ReactNode;
/** Auto-focus target */
autoFocusButton?: "primary" | "secondary" | "cancel";
/** Primary action handler */
onPrimaryAction?: () => void;
/** Secondary action handler */
onSecondaryAction?: () => void;
/** Cancel action handler */
onCancel?: () => void;
}Container for managing dialog rendering and positioning.
/**
* Container for managing dialog rendering and positioning
* @param props - DialogContainer configuration properties
* @returns JSX element as dialog container
*/
function DialogContainer(props: SpectrumDialogContainerProps): JSX.Element;
/**
* Hook for accessing dialog container context
* @returns Dialog container context value
*/
function useDialogContainer(): DialogContainerValue;
interface SpectrumDialogContainerProps extends DOMProps {
/** Dialog container content */
children: React.ReactNode;
/** Dialog type for container styling */
type?: "modal" | "fullscreen" | "fullscreenTakeover";
/** Whether container is open */
isOpen?: boolean;
/** Open state change handler */
onOpenChange?: (isOpen: boolean) => void;
/** Whether to use dialog container */
isDismissable?: boolean;
}
interface DialogContainerValue {
/** Current dialog type */
type: "modal" | "fullscreen" | "fullscreenTakeover";
/** Dismiss dialog function */
dismiss(): void;
}Contextual help tooltips that appear on hover or focus.
/**
* Contextual tooltip that appears on hover or focus
* @param props - Tooltip content and positioning properties
* @returns JSX element as tooltip overlay
*/
function Tooltip(props: SpectrumTooltipProps): JSX.Element;
/**
* Trigger wrapper that shows tooltips on hover/focus
* @param props - Tooltip trigger configuration and content
* @returns JSX element wrapping trigger and tooltip
*/
function TooltipTrigger(props: SpectrumTooltipTriggerProps): JSX.Element;
interface SpectrumTooltipProps extends DOMProps, StyleProps {
/** Tooltip content */
children: React.ReactNode;
/** Tooltip variant */
variant?: "neutral" | "positive" | "negative" | "info";
/** Tooltip placement */
placement?: Placement;
/** Whether tooltip is open */
isOpen?: boolean;
/** Whether tooltip should be disabled */
isDisabled?: boolean;
/** Show arrow pointing to trigger */
showIcon?: boolean;
}
interface SpectrumTooltipTriggerProps extends DOMProps {
/** Trigger element and tooltip */
children: [React.ReactElement, React.ReactElement];
/** Tooltip placement */
placement?: Placement;
/** Delay before showing tooltip (ms) */
delay?: number;
/** Delay before hiding tooltip (ms) */
closeDelay?: number;
/** Whether tooltip is disabled */
isDisabled?: boolean;
/** Trigger behavior */
trigger?: "focus" | "focus and hover";
/** Offset from trigger */
offset?: number;
/** Cross offset from trigger */
crossOffset?: number;
}Help content component that provides contextual assistance and documentation.
/**
* Contextual help content with info and help variants
* @param props - ContextualHelp content and variant properties
* @returns JSX element as contextual help trigger
*/
function ContextualHelp(props: SpectrumContextualHelpProps): JSX.Element;
interface SpectrumContextualHelpProps extends DOMProps, StyleProps {
/** Help content */
children: React.ReactNode;
/** Help variant */
variant?: "help" | "info";
/** Help placement */
placement?: Placement;
/** Whether help is disabled */
isDisabled?: boolean;
}Global notification system for user feedback and status updates.
/**
* Toast container for displaying notifications
* @param props - ToastContainer configuration properties
* @returns JSX element as toast notification container
*/
function ToastContainer(props: SpectrumToastContainerProps): JSX.Element;
/**
* Global toast queue for managing notifications
*/
const ToastQueue: {
/** Show positive toast notification */
positive(message: React.ReactNode, options?: SpectrumToastOptions): void;
/** Show negative toast notification */
negative(message: React.ReactNode, options?: SpectrumToastOptions): void;
/** Show neutral toast notification */
neutral(message: React.ReactNode, options?: SpectrumToastOptions): void;
/** Show info toast notification */
info(message: React.ReactNode, options?: SpectrumToastOptions): void;
};
interface SpectrumToastContainerProps extends DOMProps, StyleProps {
/** Maximum number of visible toasts */
maxVisibleToasts?: number;
/** Toast placement position */
placement?: "top" | "bottom";
}
interface SpectrumToastOptions {
/** Toast timeout in milliseconds */
timeout?: number;
/** Action button configuration */
actionLabel?: string;
/** Action button handler */
onAction?: () => void;
/** Close button handler */
onClose?: () => void;
/** Whether toast should not auto-dismiss */
shouldCloseOnAction?: boolean;
/** Toast priority for queue management */
priority?: number;
}import {
DialogTrigger,
AlertDialog,
Button
} from "@adobe/react-spectrum";
function DeleteConfirmation({ onDelete, itemName }) {
return (
<DialogTrigger>
<Button variant="negative">Delete</Button>
<AlertDialog
title="Confirm Deletion"
variant="destructive"
primaryActionLabel="Delete"
cancelLabel="Cancel"
onPrimaryAction={onDelete}
>
Are you sure you want to delete "{itemName}"? This action cannot be undone.
</AlertDialog>
</DialogTrigger>
);
}function SettingsDialog({ isOpen, onClose }) {
const [settings, setSettings] = useState({
notifications: true,
theme: 'auto',
language: 'en'
});
return (
<DialogTrigger isOpen={isOpen} onOpenChange={onClose}>
<div></div> {/* Empty trigger since controlled */}
<Dialog size="M" isDismissable onDismiss={onClose}>
<Header>
<Heading slot="title">Settings</Heading>
</Header>
<Content>
<Form>
<Switch
isSelected={settings.notifications}
onChange={(notifications) =>
setSettings({ ...settings, notifications })
}
>
Enable Notifications
</Switch>
<RadioGroup
label="Theme"
value={settings.theme}
onChange={(theme) => setSettings({ ...settings, theme })}
>
<Radio value="light">Light</Radio>
<Radio value="dark">Dark</Radio>
<Radio value="auto">Auto</Radio>
</RadioGroup>
<Picker
label="Language"
selectedKey={settings.language}
onSelectionChange={(language) =>
setSettings({ ...settings, language })
}
>
<Item key="en">English</Item>
<Item key="es">Spanish</Item>
<Item key="fr">French</Item>
</Picker>
</Form>
</Content>
<Footer>
<ButtonGroup>
<Button variant="secondary" onPress={onClose}>
Cancel
</Button>
<Button variant="accent" onPress={handleSave}>
Save Changes
</Button>
</ButtonGroup>
</Footer>
</Dialog>
</DialogTrigger>
);
}function IconWithTooltip({ icon, tooltip, ...props }) {
return (
<TooltipTrigger delay={500}>
<ActionButton isQuiet {...props}>
<Icon src={icon} />
</ActionButton>
<Tooltip>{tooltip}</Tooltip>
</TooltipTrigger>
);
}
// Usage in toolbar
<ActionGroup>
<IconWithTooltip
icon={SaveIcon}
tooltip="Save document (Cmd+S)"
onPress={handleSave}
/>
<IconWithTooltip
icon={PrintIcon}
tooltip="Print document (Cmd+P)"
onPress={handlePrint}
/>
</ActionGroup>function UserActions() {
const handleSave = async () => {
try {
await saveDocument();
ToastQueue.positive("Document saved successfully", {
timeout: 3000
});
} catch (error) {
ToastQueue.negative("Failed to save document", {
timeout: 5000,
actionLabel: "Retry",
onAction: handleSave
});
}
};
const handleDelete = async () => {
const result = await deleteItem();
if (result.success) {
ToastQueue.neutral("Item deleted", {
timeout: 4000,
actionLabel: "Undo",
onAction: () => restoreItem(result.id)
});
}
};
return (
<div>
<Button onPress={handleSave}>Save</Button>
<Button variant="negative" onPress={handleDelete}>Delete</Button>
{/* Toast container at app level */}
<ToastContainer placement="bottom" maxVisibleToasts={3} />
</div>
);
}function FormFieldWithHelp() {
return (
<Flex alignItems="end" gap="size-100">
<TextField
label="API Key"
type="password"
isRequired
description="Your API key for authentication"
/>
<ContextualHelp variant="info">
<Header>
<Heading>API Keys</Heading>
</Header>
<Content>
<Text>
API keys are used to authenticate requests to our service.
Keep your API key secure and never share it publicly.
</Text>
<Link>
<a href="/docs/api-keys" target="_blank">
Learn more about API keys
</a>
</Link>
</Content>
</ContextualHelp>
</Flex>
);
}/** Placement options for overlays and popovers */
type Placement =
| "bottom" | "bottom left" | "bottom right" | "bottom start" | "bottom end"
| "top" | "top left" | "top right" | "top start" | "top end"
| "left" | "left top" | "left bottom" | "start" | "start top" | "start bottom"
| "right" | "right top" | "right bottom" | "end" | "end top" | "end bottom";
/** Overlay positioning configuration */
interface PositionProps {
/** Placement relative to target */
placement?: Placement;
/** Offset from target element */
offset?: number;
/** Cross-axis offset from target */
crossOffset?: number;
/** Whether overlay should flip when constrained */
shouldFlip?: boolean;
/** Whether overlay should update position */
shouldUpdatePosition?: boolean;
/** Container padding for mobile */
containerPadding?: number;
}/** Dialog size options */
type DialogSize = "S" | "M" | "L" | "fullscreen" | "fullscreenTakeover";
/** Dialog type variants */
type DialogType = "modal" | "popover" | "tray";
/** Alert dialog variants */
type AlertDialogVariant = "confirmation" | "information" | "warning" | "error" | "destructive";
/** Auto-focus button options */
type AutoFocusButton = "primary" | "secondary" | "cancel";/** Toast variant types */
type ToastVariant = "positive" | "negative" | "neutral" | "info";
/** Toast placement options */
type ToastPlacement = "top" | "bottom";