Flag Message Dialog

A dialog for reporting inappropriate messages with reason selection, an optional remark, and submission handling.

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:

1. onSubmit is awaited.
2. Returning false (or throwing) keeps the dialog open and shows an inline error banner.
3. 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".