Modal

GlobalModal is the public modal component in the React SDK. It renders through the chat-level modal dialog manager provided by Chat.

Best Practices

  • Use GlobalModal for app-owned modals rendered inside the chat tree.
  • Use WithComponents to override SDK-owned modal surfaces such as delete dialogs, poll dialogs, or selector dialogs.
  • Keep modal content lightweight and controlled by a single open state.
  • Use onCloseAttempt when overlay or escape dismissal should be blocked.

Basic Usage

import { useCallback, useState } from "react";
import { GlobalModal } from "stream-chat-react";

const Example = () => {
  const [open, setOpen] = useState(false);
  const closeModal = useCallback(() => setOpen(false), []);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open modal</button>
      <GlobalModal onClose={closeModal} open={open}>
        <div className="custom-modal-body">Custom content</div>
      </GlobalModal>
    </>
  );
};

SDK Modal Overrides

SDK surfaces that open modal content use the shared Modal override from ComponentContext. To change that behavior across a subtree, register a compatible modal component with WithComponents.

import {
  Channel,
  GlobalModal,
  MessageComposer,
  WithComponents,
} from "stream-chat-react";
import type { ModalProps } from "stream-chat-react";

const CustomModal = (props: ModalProps) => (
  <GlobalModal {...props} className="custom-modal-shell" />
);

const App = () => (
  <WithComponents overrides={{ Modal: CustomModal }}>
    <Channel>
      <MessageComposer />
    </Channel>
  </WithComponents>
);

Props

PropDescriptionType
childrenModal contents.ReactNode
classNameAdditional class name for the modal overlay root.string
CloseButtonOnOverlayOptional close-button component rendered on the overlay layer.React.ComponentType<ComponentProps<"button">>
onCloseCalled when the modal should close. Your handler should update open. ModalCloseEvent is KeyboardEvent | React.KeyboardEvent | React.MouseEvent<HTMLButtonElement | HTMLDivElement>.(event: ModalCloseEvent) => void
onCloseAttemptIntercepts close attempts. Return false to keep the modal open. ModalCloseSource is "overlay" | "button" | "escape".(source: ModalCloseSource, event: ModalCloseEvent) => boolean
openControls whether the modal is rendered. Defaults to false.boolean

Examples

Intercept close attempts

import { GlobalModal } from "stream-chat-react";
import type { ModalCloseSource, ModalProps } from "stream-chat-react";

const onCloseAttempt = (source: ModalCloseSource) => source !== "overlay";

const ConfirmingModal = (props: ModalProps) => (
  <GlobalModal {...props} onCloseAttempt={onCloseAttempt} />
);
Previous
WithDragAndDropUpload
Next
Overview