Flag Message Dialog - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatFlagMessageDialog",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatFlagMessageDialog } from \"@cometchat/chat-uikit-react\";",
  "description": "Dialog for reporting/flagging an inappropriate message. Fetches flag reasons from the SDK, captures an optional remark, and submits the report.",
  "cssRootClass": ".cometchat-flag-message-dialog",
  "primaryOutput": {
    "prop": "onSubmit",
    "type": "(messageId: string, reasonId: string, remark?: string) => Promise<boolean>"
  },
  "props": {
    "data": {
      "message": { "type": "CometChat.BaseMessage", "note": "Required. The message being flagged." },
      "isOpen": { "type": "boolean", "note": "When provided, the dialog is controlled." }
    },
    "callbacks": {
      "onSubmit": { "type": "(messageId: string, reasonId: string, remark?: string) => Promise<boolean>", "note": "Return true to close, false to keep open and show an error." },
      "onClose": { "type": "() => void" },
      "onError": { "type": "((error: CometChat.CometChatException) => void) | null" }
    },
    "config": {
      "closeOnOutsideClick": { "type": "boolean", "default": true },
      "className": { "type": "string" }
    }
  },
  "types": {
    "CometChatFlagMessageDialogRootProps": "Root overlay props",
    "CometChatFlagMessageDialogHeaderProps": "Header sub-component props",
    "CometChatFlagMessageDialogReasonsProps": "Reasons list sub-component props",
    "CometChatFlagMessageDialogRemarkProps": "Remark input sub-component props",
    "CometChatFlagMessageDialogActionsProps": "Actions (cancel/submit) sub-component props",
    "CometChatFlagMessageDialogContextValue": "Full context value"
  }
}

Where It Fits

CometChatFlagMessageDialog is a modal dialog that lets a user report an inappropriate message. When it opens, it fetches the available report reasons from the SDK (CometChat.getFlagReasons), renders them as a single-select list, captures an optional free-text remark, and—on submit—invokes your onSubmit handler with the message ID, the selected reason ID, and the remark.

Live Preview — interact with the flag message dialog.Open in Storybook ↗

Use it when a user chooses “Report” on a message. The parent owns the open state and decides what happens with the report inside onSubmit (e.g., calling a moderation backend).

import { useState } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatFlagMessageDialog } from "@cometchat/chat-uikit-react";

function FlagMessageExample({ message }: { message: CometChat.BaseMessage }) {
  const [open, setOpen] = useState(false);

  const handleSubmit = async (
    messageId: string,
    reasonId: string,
    remark?: string
  ) => {
    // Report the message to your backend / moderation service.
    console.log("Reporting", { messageId, reasonId, remark });
    return true; // return false to keep the dialog open and show an error
  };

  return (
    <>
      <button onClick={() => setOpen(true)}>Report message</button>

      <CometChatFlagMessageDialog
        message={message}
        isOpen={open}
        onClose={() => setOpen(false)}
        onSubmit={handleSubmit}
      />
    </>
  );
}

Minimal Render

import { CometChatFlagMessageDialog } from "@cometchat/chat-uikit-react";

function Demo({ message }) {
  return <CometChatFlagMessageDialog message={message} isOpen />;
}

Root CSS class: .cometchat-flag-message-dialog

Sub-Components

CometChatFlagMessageDialog is a compound component with these sub-components:

Sub-Component	Purpose
`Root`	Overlay and context provider. Manages open/close state, focus trap, outside-click/Escape, reason fetching, and submission. Renders the default layout when no children are passed.
`Header`	Title and subtitle. Defaults to a localized “Report a Message” heading.
`Reasons`	Single-select list of report reasons fetched from the SDK.
`Remark`	Optional free-text input with a character counter (default max 500).
`Actions`	Cancel and submit (Report) buttons.

Custom Layout

Compose sub-components to customize the layout — for example, omit Remark to collect only a reason:

<CometChatFlagMessageDialog.Root
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
  onSubmit={handleSubmit}
>
  <CometChatFlagMessageDialog.Header />
  <CometChatFlagMessageDialog.Reasons />
  <CometChatFlagMessageDialog.Remark />
  <CometChatFlagMessageDialog.Actions />
</CometChatFlagMessageDialog.Root>

Custom Header

Pass title/subtitle for text changes, or children for fully custom header content:

<CometChatFlagMessageDialog.Root message={message} isOpen={open} onClose={onClose}>
  <CometChatFlagMessageDialog.Header>
    <div style={{ textAlign: "center" }}>
      <h3>Custom Report Header</h3>
      <p>This uses children instead of title/subtitle props.</p>
    </div>
  </CometChatFlagMessageDialog.Header>
  <CometChatFlagMessageDialog.Reasons />
  <CometChatFlagMessageDialog.Actions />
</CometChatFlagMessageDialog.Root>

Sub-component props:

Sub-component	Prop	Type	Default
`Header`	`title`	`string`	`"Report a Message"` (localized)
`Header`	`subtitle`	`string`	Localized description
`Remark`	`label`	`string`	`"Reason"` (localized)
`Remark`	`placeholder`	`string`	Localized placeholder
`Remark`	`maxLength`	`number`	`500`
`Actions`	`cancelText`	`string`	`"Cancel"` (localized)
`Actions`	`submitText`	`string`	`"Report"` (localized)

Every sub-component also accepts children (where applicable) and a className.

Actions and Events

Callback Props

onSubmit

Called when the user clicks Report with a reason selected. Receives the message ID, the selected reason ID, and the optional remark. Return true to close the dialog, or false to keep it open and show an inline error.

<CometChatFlagMessageDialog
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
  onSubmit={async (messageId, reasonId, remark) => {
    const ok = await reportToBackend({ messageId, reasonId, remark });
    return ok;
  }}
/>

onClose

Called when the dialog requests to close — via the cancel button, the Escape key, or an outside click. In controlled mode you own the open state, so update it here.

<CometChatFlagMessageDialog
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
/>

onError

Called when an SDK error occurs (e.g., while fetching reasons or during submission).

<CometChatFlagMessageDialog
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
  onError={(error) => console.error("Flag message error:", error)}
/>

Behavior Details

Controlled vs Uncontrolled

Controlled — pass isOpen and onClose. You own the open state (recommended for most apps).
Uncontrolled — omit isOpen. The dialog manages its own internal open state and closes itself on cancel, Escape, outside click, or a successful submit.

Reason Fetching

On open, the dialog calls CometChat.getFlagReasons() and renders the result as a single-select list. While loading, a loading state is shown. If the call fails, onError is invoked.

Remark

The remark is optional. It is trimmed before submission, and an empty remark is passed as undefined to onSubmit. A character counter enforces maxLength (default 500).

Submission

The submit button is disabled until a reason is selected. On submit:

onSubmit is awaited.
Returning false (or throwing) keeps the dialog open and shows an inline error banner.
Returning true closes the dialog.

Focus & Keyboard

The Root traps focus within the dialog while open, moves focus to the first focusable element on open, restores focus to the previously focused element on close, cycles focus with Tab / Shift+Tab, and closes on Escape.

CSS Architecture

The component uses CSS custom properties provided by the UI Kit.

Key Selectors

Target	Selector
Backdrop	`.cometchat-flag-message-dialog__backdrop`
Dialog container	`.cometchat-flag-message-dialog`
Error banner	`.cometchat-flag-message-dialog__error`
Header	`.cometchat-flag-message-dialog__header`
Header title	`.cometchat-flag-message-dialog__header-title`
Header subtitle	`.cometchat-flag-message-dialog__header-subtitle`
Reasons list	`.cometchat-flag-message-dialog__reasons`
Reason item	`.cometchat-flag-message-dialog__reason`
Reason item (selected)	`.cometchat-flag-message-dialog__reason--selected`
Reasons loading	`.cometchat-flag-message-dialog__reasons-loading`
Remark wrapper	`.cometchat-flag-message-dialog__remark`
Remark label	`.cometchat-flag-message-dialog__remark-label`
Remark input	`.cometchat-flag-message-dialog__remark-input`
Remark counter	`.cometchat-flag-message-dialog__remark-counter`
Remark counter (at limit)	`.cometchat-flag-message-dialog__remark-counter--limit`
Actions container	`.cometchat-flag-message-dialog__actions`
Cancel button	`.cometchat-flag-message-dialog__actions-cancel`
Submit button	`.cometchat-flag-message-dialog__actions-submit`

Example: Custom styling

App.css

.cometchat-flag-message-dialog {
  --cometchat-background-color-01: #ffffff;
  --cometchat-text-color-primary: #141414;
}

.cometchat-flag-message-dialog__reason--selected {
  border-color: var(--my-brand-color);
}

.cometchat-flag-message-dialog__actions-submit {
  background: var(--my-brand-color);
}

Props

The message prop is required. All other props are optional. The props below belong to Root (and to the flat CometChatFlagMessageDialog, which forwards them).

message

The message being flagged. Required.


Type	`CometChat.BaseMessage`
Default	—

isOpen

Whether the dialog is open. When provided, the component is controlled.


Type	`boolean`
Default	`undefined` (uncontrolled)

onClose

Callback invoked when the dialog requests to close (outside click, Escape, or cancel).


Type	`() => void`
Default	`undefined`

closeOnOutsideClick

Whether clicking outside the dialog closes it.


Type	`boolean`
Default	`true`

onSubmit

Custom submit handler. Receives the message ID, the selected reason ID, and the optional remark. Return true on success (the dialog closes) or false to keep it open and show an error.


Type	`(messageId: string, reasonId: string, remark?: string) => Promise<boolean>`
Default	`undefined`

onError

Callback when an SDK error occurs.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`undefined`

className

Additional CSS class applied to the dialog backdrop.


Type	`string`
Default	`undefined`

Accessibility

Root has role="dialog" with aria-modal="true".
The dialog is labelled by its title (aria-labelledby) and described by its subtitle (aria-describedby).
Focus moves into the dialog on open and is restored to the previously focused element on close.
Focus is trapped within the dialog; Tab / Shift+Tab cycle through focusable elements.
Escape closes the dialog.
The error banner uses role="alert" with aria-live="assertive".

​Where It Fits

​Minimal Render

​Sub-Components

​Custom Layout

​Custom Header

​Actions and Events

​Callback Props

​onSubmit

​onClose

​onError

​Behavior Details

​Controlled vs Uncontrolled

​Reason Fetching

​Remark

​Submission

​Focus & Keyboard

​CSS Architecture

​Key Selectors

​Example: Custom styling

​Props

​message

​isOpen

​onClose

​closeOnOutsideClick

​onSubmit

​onError

​className

​Accessibility

Where It Fits

Minimal Render

Sub-Components

Custom Layout

Custom Header

Actions and Events

Callback Props

onSubmit

onClose

onError

Behavior Details

Controlled vs Uncontrolled

Reason Fetching

Remark

Submission

Focus & Keyboard

CSS Architecture

Key Selectors

Example: Custom styling

Props

message

isOpen

onClose

closeOnOutsideClick

onSubmit

onError

className

Accessibility