Dialog

API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. ? means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

Dialog API

The Dialog root level component serves as an interface for interaction with all possible behaviors exposed. It provides context down the hierarchy to children compound components to allow functionality. This component expects to receive as children either a DialogSurface or a DialogTrigger and a DialogSurface (or some component that will eventually render one of those compound components) in this specific order

interface DialogProps {
  /**
   * Can contain two children including `DialogTrigger` and `DialogSurface`.
   * Alternatively can only contain `DialogSurface` if using trigger outside dialog, or controlling state.
   */
  children: JSXElement | [JSXElement, JSXElement];

  /**
   * Default value for the uncontrolled open state of the dialog.
   * @default false
   */
  defaultOpen?: boolean;

  /**
   * Enables standard behavior according to the [HTML dialog spec](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal)
   * where the focus trap involves setting outside elements inert.
   * @default false
   */
  inertTrapFocus?: boolean;

  /**
   * Dialog variations.
   *
   * `modal`: When this type of dialog is open, the rest of the page is dimmed out and cannot be interacted with.
   * The tab sequence is kept within the dialog and moving the focus outside
   * the dialog will imply closing it. This is the default type of the component.
   *
   * `non-modal`: When a non-modal dialog is open, the rest of the page is not dimmed out
   * and users can interact with the rest of the page.
   * This also implies that the tab focus can move outside the dialog when it reaches the last focusable element.
   *
   * `alert`: is a special type of modal dialogs that interrupts the user's workflow
   * to communicate an important message or ask for a decision.
   * Unlike a typical modal dialog, the user must take an action through the options given to dismiss the dialog,
   * and it cannot be dismissed through the dimmed background.
   * @default modal
   */
  modalType?: "alert" | "modal" | "non-modal";

  /**
   * Callback fired when the component changes value from open state.
   */
  onOpenChange?: DialogOpenChangeEventHandler;

  /**
   * Controls the open state of the dialog
   * @default false
   */
  open?: boolean;

  /**
   * For more information refer to the [Motion docs page](https://react.fluentui.dev/?path=/docs/motion-motion-slot--docs).
   */
  surfaceMotion?: PresenceMotionSlotProps<ScaleParams> | null;

  /**
   * Decides whether the dialog should be removed from the DOM tree when it is closed.
   * This can be useful when dealing with components that may contain state that should not
   * be reset when the dialog is closed.
   * @default true
   */
  unmountOnClose?: boolean;
}

DialogActions API

DialogActions is a container for the actions of the dialog. Apart from styling, this component does not have other behavior.

interface DialogActionsProps {
  as?: "div";

  children?: any;

  className?: string;

  /**
   * Makes the actions expand the entire width of the DialogBody
   * @default false
   */
  fluid?: boolean;

  /**
   * defines the position on the dialog grid of the actions
   * @default 'end'
   */
  position?: "start" | "end";

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;
}

DialogSurface API

DialogSurface component represents the visual part of a Dialog as a whole, it contains everything that should be visible.

interface DialogSurfaceProps {
  as?: "div";

  /**
   * Dimmed background of dialog.
   * The default backdrop is rendered as a `<div>` with styling.
   * This slot expects a `<div>` element which will replace the default backdrop.
   * The backdrop should have `aria-hidden="true"`.
   *
   * Accepts an `appearance` prop to control backdrop visibility:
   * - `'dimmed'`: Always shows a dimmed backdrop, regardless of nesting.
   * - `'transparent'`: Always shows a transparent backdrop.
   */
  backdrop?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; } & { appearance?: "transparent" | "dimmed" | undefined; }> | null | undefined;

  /**
   * For more information refer to the [Motion docs page](https://react.fluentui.dev/?path=/docs/motion-motion-slot--docs).
   */
  backdropMotion?: PresenceMotionSlotProps<FadeParams> | null;

  children?: any;

  className?: string;

  /**
   * Where the portal children are mounted on DOM
   * @default a new element on document.body without any styling
   */
  mountNode?: HTMLElement | { element?: HTMLElement | null; className?: string; } | null | undefined;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;
}

DialogTitle API

The DialogTitle component expects to have a title/header and when Dialog is non-modal a close (X icon) button is provided through action slot by default.

interface DialogTitleProps {
  /**
   * By default a Dialog with modalType='non-modal' will have a close button action
   */
  action?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  as?: "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";

  children?: any;

  className?: string;

  ref?: Ref<HTMLDivElement>;

  style?: CSSProperties;
}

DialogTrigger API

A non-visual component that wraps its child and configures them to be the trigger that will open or close a Dialog. This component should only accept one child.

This component sole purpose is to avoid opting out of the internal controlled open state of a Dialog Besides being a trigger that opens/close a dialog through context this component doesn't do much, making it basically unnecessary in cases where the trigger is outside of the Dialog component.

interface DialogTriggerProps {
  /**
   * Explicitly declare if the trigger is responsible for opening or
   * closing a Dialog visibility state.
   *
   * If `DialogTrigger` is outside `DialogSurface` then it'll be `open` by default
   *
   * If `DialogTrigger` is inside `DialogSurface` then it'll be `close` by default
   */
  action?: "open" | "close";

  children?: ReactElement<any, string | JSXElementConstructor<any>> | ((props: DialogTriggerChildProps<ARIAButtonType, {}>) => ReactElement<any, string | JSXElementConstructor<any>> | null) | null;

  /**
   * Disables internal trigger mechanism that ensures a child provided will be a compliant ARIA button.
   * @default false
   */
  disableButtonEnhancement?: boolean;
}