Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Dialog): useXDSImperativeDialog — show/hide without state management (#1239)

Cindy Zhanga87f5fb2edf6
diff --git a/packages/core/src/Dialog/index.ts b/packages/core/src/Dialog/index.ts
index aa9d59c9a3..ec37fd240f 100644
--- a/packages/core/src/Dialog/index.ts
+++ b/packages/core/src/Dialog/index.ts
@@ -20,3 +20,6 @@ export type {
export {XDSDialogHeader} from './XDSDialogHeader';
export type {XDSDialogHeaderProps} from './XDSDialogHeader';
+
+export {useXDSImperativeDialog} from './useXDSImperativeDialog';
+export type {XDSImperativeDialogReturn} from './useXDSImperativeDialog';
diff --git a/packages/core/src/Dialog/useXDSImperativeDialog.test.tsx b/packages/core/src/Dialog/useXDSImperativeDialog.test.tsx
new file mode 100644
index 0000000000..ba841a1144
--- /dev/null
+++ b/packages/core/src/Dialog/useXDSImperativeDialog.test.tsx
@@ -0,0 +1,70 @@
+import {describe, it, expect, vi, beforeAll} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {useXDSImperativeDialog} from './useXDSImperativeDialog';
+
+// jsdom doesn't support dialog.showModal/close
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal = vi.fn();
+ HTMLDialogElement.prototype.close = vi.fn();
+});
+
+function TestHarness() {
+ const dialog = useXDSImperativeDialog({width: 400});
+
+ return (
+ <div>
+ <button onClick={() => dialog.show(<div>Dialog content</div>)}>
+ Open
+ </button>
+ <button onClick={() => dialog.hide()}>Close</button>
+ <span data-testid="status">{dialog.isOpen ? 'open' : 'closed'}</span>
+ {dialog.element}
+ </div>
+ );
+}
+
+describe('useXDSImperativeDialog', () => {
+ it('starts closed', () => {
+ render(<TestHarness />);
+ expect(screen.getByTestId('status').textContent).toBe('closed');
+ });
+
+ it('opens on show()', () => {
+ render(<TestHarness />);
+ fireEvent.click(screen.getByText('Open'));
+ expect(screen.getByTestId('status').textContent).toBe('open');
+ });
+
+ it('renders content when open', () => {
+ render(<TestHarness />);
+ fireEvent.click(screen.getByText('Open'));
+ expect(screen.getByText('Dialog content')).toBeInTheDocument();
+ });
+
+ it('closes on hide()', () => {
+ render(<TestHarness />);
+ fireEvent.click(screen.getByText('Open'));
+ expect(screen.getByTestId('status').textContent).toBe('open');
+ fireEvent.click(screen.getByText('Close'));
+ expect(screen.getByTestId('status').textContent).toBe('closed');
+ });
+
+ it('can show with options', () => {
+ function OptionsHarness() {
+ const dialog = useXDSImperativeDialog();
+ return (
+ <div>
+ <button onClick={() => dialog.show(<div>Wide content</div>, {width: 720})}>
+ Open Wide
+ </button>
+ <span data-testid="status">{dialog.isOpen ? 'open' : 'closed'}</span>
+ {dialog.element}
+ </div>
+ );
+ }
+ render(<OptionsHarness />);
+ fireEvent.click(screen.getByText('Open Wide'));
+ expect(screen.getByTestId('status').textContent).toBe('open');
+ expect(screen.getByText('Wide content')).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/Dialog/useXDSImperativeDialog.tsx b/packages/core/src/Dialog/useXDSImperativeDialog.tsx
new file mode 100644
index 0000000000..73523f7ed8
--- /dev/null
+++ b/packages/core/src/Dialog/useXDSImperativeDialog.tsx
@@ -0,0 +1,98 @@
+'use client';
+
+/**
+ * @file useXDSImperativeDialog.tsx
+ * @input Uses React, XDSDialog
+ * @output Exports useXDSImperativeDialog hook
+ * @position Utility hook; wraps XDSDialog with imperative show/hide API
+ *
+ * Eliminates boilerplate for dialogs that don't need controlled state.
+ * Instead of managing isOpen + content state, call show() with content
+ * and the dialog handles the rest.
+ *
+ * @example
+ * ```
+ * const dialog = useXDSImperativeDialog();
+ *
+ * <button onClick={() => dialog.show(<MyContent />)}>Open</button>
+ * {dialog.element}
+ * ```
+ */
+
+import {useState, useCallback, useMemo, type ReactNode} from 'react';
+import {XDSDialog, type XDSDialogProps} from './XDSDialog';
+
+type DialogOptions = Omit<
+ XDSDialogProps,
+ 'isOpen' | 'onOpenChange' | 'children'
+>;
+
+export interface XDSImperativeDialogReturn {
+ /** Show the dialog with the given content. */
+ show: (content: ReactNode, options?: DialogOptions) => void;
+ /** Hide the dialog. */
+ hide: () => void;
+ /** Whether the dialog is currently open. */
+ isOpen: boolean;
+ /** Render this in your JSX tree. */
+ element: ReactNode;
+}
+
+/**
+ * Imperative dialog — show/hide without managing state.
+ *
+ * @example
+ * ```
+ * const dialog = useXDSImperativeDialog();
+ *
+ * // Fire and forget — no isOpen state needed
+ * onClick={() => dialog.show(
+ * <XDSCodeBlock code={output} language="bash" />
+ * )}
+ *
+ * // With options
+ * onClick={() => dialog.show(content, { width: 720, variant: 'fullscreen' })}
+ *
+ * // Render the portal
+ * return <>{dialog.element}</>;
+ * ```
+ */
+export function useXDSImperativeDialog(
+ defaultOptions?: DialogOptions,
+): XDSImperativeDialogReturn {
+ const [isOpen, setIsOpen] = useState(false);
+ const [content, setContent] = useState<ReactNode>(null);
+ const [options, setOptions] = useState<DialogOptions | undefined>(
+ defaultOptions,
+ );
+
+ const show = useCallback(
+ (newContent: ReactNode, newOptions?: DialogOptions) => {
+ setContent(newContent);
+ if (newOptions) setOptions(prev => ({...prev, ...newOptions}));
+ setIsOpen(true);
+ },
+ [],
+ );
+
+ const hide = useCallback(() => {
+ setIsOpen(false);
+ }, []);
+
+ const element = useMemo(
+ () => (
+ <XDSDialog
+ isOpen={isOpen}
+ onOpenChange={open => {
+ if (!open) setIsOpen(false);
+ }}
+ {...(defaultOptions ?? {})}
+ {...(options ?? {})}>
+ {content}
+ </XDSDialog>
+ ),
+ [isOpen, content, options, defaultOptions],
+ );
+
+ return {show, hide, isOpen, element};
+}