Flag Message Dialog - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatFlagMessageDialog",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatFlagMessageDialog } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A modal dialog for reporting/flagging messages by selecting a reason and optionally providing a remark.",
  "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" },
      "title": { "type": "string", "default": "localized 'flag_message_title'" },
      "subtitle": { "type": "string", "default": "localized 'flag_message_subtitle'" },
      "cancelText": { "type": "string", "default": "localized 'flag_message_confirm_no'" },
      "submitText": { "type": "string", "default": "localized 'flag_message_confirm_yes'" },
      "label": { "type": "string", "default": "localized 'flag_message_remark_label'" },
      "placeholder": { "type": "string", "default": "localized 'flag_message_remark_placeholder'" },
      "maxLength": { "type": "number", "default": "500" }
    },
    "callbacks": {
      "onClose": { "type": "() => void", "default": "undefined" },
      "onSubmit": { "type": "(messageId, reasonId, remark?) => Promise<boolean>", "default": "undefined" },
      "onError": { "type": "(error: CometChatException) => void", "default": "undefined" }
    },
    "behavior": {
      "isOpen": { "type": "boolean", "default": "undefined (uncontrolled)" },
      "closeOnOutsideClick": { "type": "boolean", "default": "true" }
    }
  },
  "events": [],
  "sdkListeners": [],
  "types": {}
}

Where It Fits

CometChatFlagMessageDialog is a base modal component used when a user wants to report an inappropriate message. It fetches flag reasons from the CometChat SDK, presents them as selectable options, and optionally collects a remark. Wire it into CometChatMessageList as a message option to enable message reporting.

import { useState } from "react";
import { CometChatFlagMessageDialog } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function MessageActions({ message }) {
  const [showFlag, setShowFlag] = useState(false);

  const handleSubmit = async (messageId, reasonId, remark) => {
    await reportMessage(messageId, reasonId, remark);
    return true;
  };

  return (
    <div>
      <button onClick={() => setShowFlag(true)}>Report</button>
      <CometChatFlagMessageDialog.Root
        message={message}
        isOpen={showFlag}
        onClose={() => setShowFlag(false)}
        onSubmit={handleSubmit}
      >
        <CometChatFlagMessageDialog.Header />
        <CometChatFlagMessageDialog.Reasons />
        <CometChatFlagMessageDialog.Remark />
        <CometChatFlagMessageDialog.Actions />
      </CometChatFlagMessageDialog.Root>
    </div>
  );
}

Minimal Render

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

function Demo({ message }) {
  return (
    <CometChatFlagMessageDialog.Root message={message} isOpen={true} onClose={() => {}}>
      <CometChatFlagMessageDialog.Header />
      <CometChatFlagMessageDialog.Reasons />
      <CometChatFlagMessageDialog.Remark />
      <CometChatFlagMessageDialog.Actions />
    </CometChatFlagMessageDialog.Root>
  );
}

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

Common Patterns

Without Remark Field

Omit the Remark sub-component to hide the remark textarea. This replaces the v6 hideFlagRemarkField boolean prop.

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

Controlled Mode

Manage the open/close state externally for full control.

function FlagDialog({ message }) {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Report Message</button>
      <CometChatFlagMessageDialog.Root
        message={message}
        isOpen={open}
        onClose={() => setOpen(false)}
        onSubmit={async (msgId, reasonId, remark) => {
          await api.flagMessage(msgId, reasonId, remark);
          return true;
        }}
      >
        <CometChatFlagMessageDialog.Header />
        <CometChatFlagMessageDialog.Reasons />
        <CometChatFlagMessageDialog.Remark />
        <CometChatFlagMessageDialog.Actions />
      </CometChatFlagMessageDialog.Root>
    </>
  );
}

Custom Header

Replace the default header with fully custom content using children.

<CometChatFlagMessageDialog.Header>
  <div style={{ textAlign: "center" }}>
    <h3>Report This Message</h3>
    <p>Help us keep the community safe.</p>
  </div>
</CometChatFlagMessageDialog.Header>

Actions and Events

Callback Props

onSubmit

Called when the user clicks the submit/report button. Receives the message ID, selected reason ID, and optional remark. Return true to close the dialog, or throw to show an error.

<CometChatFlagMessageDialog.Root
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
  onSubmit={async (messageId, reasonId, remark) => {
    const result = await flagMessageAPI(messageId, reasonId, remark);
    return result.success;
  }}
>
  {/* ... */}
</CometChatFlagMessageDialog.Root>

onClose

Called when the dialog requests to close (Escape key, outside click, or cancel button).

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

onError

Called when an SDK error occurs (e.g., fetching flag reasons fails).

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

Custom View Slots

Slot	Signature	Replaces
`children` (Header)	`ReactNode`	Title + subtitle text
`children` (Reasons)	`ReactNode`	Default reason radio buttons
`children` (Actions)	`ReactNode`	Cancel + submit buttons

Custom Header

TypeScript
CSS

<CometChatFlagMessageDialog.Header>
  <div>
    <h3>Custom Report Title</h3>
    <p>Custom description text.</p>
  </div>
</CometChatFlagMessageDialog.Header>

.cometchat-flag-message-dialog__header {
  padding: 16px;
  border-bottom: 1px solid #eee;
}

Custom Actions

TypeScript
CSS

<CometChatFlagMessageDialog.Actions>
  <button onClick={handleCancel}>Go Back</button>
  <button onClick={handleSubmit} style={{ background: "red", color: "white" }}>
    Submit Report
  </button>
</CometChatFlagMessageDialog.Actions>

.cometchat-flag-message-dialog__actions {
  justify-content: flex-end;
}

CSS Architecture

The component uses CSS custom properties (design tokens) defined in @cometchat/chat-uikit-react/css-variables.css. The cascade:

Global tokens set on the .cometchat root wrapper.
Component CSS (.cometchat-flag-message-dialog) consumes these tokens via var().
Overrides target .cometchat-flag-message-dialog descendant selectors.

Key Selectors

Target	Selector
Backdrop	`.cometchat-flag-message-dialog__backdrop`
Dialog container	`.cometchat-flag-message-dialog`
Header	`.cometchat-flag-message-dialog__header`
Title	`.cometchat-flag-message-dialog__header-title`
Subtitle	`.cometchat-flag-message-dialog__header-subtitle`
Reasons container	`.cometchat-flag-message-dialog__reasons`
Reason button	`.cometchat-flag-message-dialog__reason`
Selected reason	`.cometchat-flag-message-dialog__reason--selected`
Remark area	`.cometchat-flag-message-dialog__remark`
Remark textarea	`.cometchat-flag-message-dialog__remark-input`
Error banner	`.cometchat-flag-message-dialog__error`
Actions row	`.cometchat-flag-message-dialog__actions`
Cancel button	`.cometchat-flag-message-dialog__actions-cancel`
Submit button	`.cometchat-flag-message-dialog__actions-submit`

Example: Brand-themed dialog

.cometchat-flag-message-dialog {
  border-radius: 24px;
  max-width: 500px;
}

.cometchat-flag-message-dialog__reason--selected {
  border-color: #6851ff;
  background: #f0edff;
  color: #6851ff;
}

.cometchat-flag-message-dialog__actions-submit button {
  background: #6851ff;
}

Customization Matrix

What to change	Where	Property/API	Example
Override submit behavior	Component props	`onSubmit`	`onSubmit={handleFlag}`
Control open state	Component props	`isOpen`, `onClose`	`isOpen={showDialog}`
Disable outside click	Component props	`closeOnOutsideClick`	`closeOnOutsideClick={false}`
Hide remark field	Composition	Omit `Remark` sub-component	Don’t render `<Remark />`
Replace header	Sub-component children	`children` on `Header`	`<Header><Custom /></Header>`
Replace buttons	Sub-component children	`children` on `Actions`	`<Actions><Custom /></Actions>`
Change visual styling	Global CSS	`.cometchat-flag-message-dialog` selectors	See CSS Selectors table

Props

All props are optional unless noted otherwise.

cancelText

Text for the cancel button.


Type	`string`
Default	Localized `"Cancel"`

children (Root)

Sub-components to render inside the dialog.


Type	`ReactNode`
Default	`Header + Reasons + Remark + Actions`

className

Optional custom CSS class name applied to the component root.


Type	`string`
Default	`undefined`

closeOnOutsideClick

Whether clicking outside the dialog closes it.


Type	`boolean`
Default	`true`

isOpen

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


Type	`boolean`
Default	`undefined` (uncontrolled)

label

Label text for the remark textarea.


Type	`string`
Default	Localized `"Reason"`

maxLength

Maximum character count for the remark textarea.


Type	`number`
Default	`500`

message

The message being flagged. Required on Root.


Type	`CometChat.BaseMessage`
Default	—

onClose

Callback when the dialog requests to close.


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

onError

Callback when an SDK error occurs.


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

onSubmit

Custom submit handler. Receives message ID, reason ID, and optional remark.


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

placeholder

Placeholder text for the remark textarea.


Type	`string`
Default	Localized placeholder

submitText

Text for the submit/report button.


Type	`string`
Default	Localized `"Report"`

subtitle

Subtitle text in the Header sub-component.


Type	`string`
Default	Localized description

title

Title text in the Header sub-component.


Type	`string`
Default	Localized `"Report a Message"`

CSS Selectors

Target	Selector
Backdrop overlay	`.cometchat-flag-message-dialog__backdrop`
Dialog container	`.cometchat-flag-message-dialog`
Header area	`.cometchat-flag-message-dialog__header`
Title text	`.cometchat-flag-message-dialog__header-title`
Subtitle text	`.cometchat-flag-message-dialog__header-subtitle`
Reasons container	`.cometchat-flag-message-dialog__reasons`
Reason button	`.cometchat-flag-message-dialog__reason`
Selected reason	`.cometchat-flag-message-dialog__reason--selected`
Remark area	`.cometchat-flag-message-dialog__remark`
Remark label	`.cometchat-flag-message-dialog__remark-label`
Remark textarea	`.cometchat-flag-message-dialog__remark-input`
Error banner	`.cometchat-flag-message-dialog__error`
Actions row	`.cometchat-flag-message-dialog__actions`
Cancel button wrapper	`.cometchat-flag-message-dialog__actions-cancel`
Submit button wrapper	`.cometchat-flag-message-dialog__actions-submit`

Documentation Index

​Where It Fits

​Minimal Render

​Common Patterns

​Without Remark Field

​Controlled Mode

​Custom Header

​Actions and Events

​Callback Props

​onSubmit

​onClose

​onError

​Custom View Slots

​Custom Header

​Custom Actions

​CSS Architecture

​Key Selectors

​Example: Brand-themed dialog

​Customization Matrix

​Props

​cancelText

​children (Root)

​className

​closeOnOutsideClick

​isOpen

​label

​maxLength

​message

​onClose

​onError

​onSubmit

​placeholder

​submitText

​subtitle

​title

​CSS Selectors

Where It Fits

Minimal Render

Common Patterns

Without Remark Field

Controlled Mode

Custom Header

Actions and Events

Callback Props

onSubmit

onClose

onError

Custom View Slots

Custom Header

Custom Actions

CSS Architecture

Key Selectors

Example: Brand-themed dialog

Customization Matrix

Props

cancelText

children (Root)

className

closeOnOutsideClick

isOpen

label

maxLength

message

onClose

onError

onSubmit

placeholder

submitText

subtitle

title

CSS Selectors