> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Flag Message Dialog

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

<Accordion title="AI Integration Quick Reference">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

## 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.

<Info>
  **Live Preview** — interact with the flag message dialog.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-misc-flag-message-dialog--default)
</Info>

<iframe src="https://storybook.cometchat.io/react/iframe.html?id=components-misc-flag-message-dialog--default&viewMode=story&shortcuts=false&singleStory=true" className="w-full rounded-xl" loading="lazy" style={{height: "500px", border: "1px solid #e0e0e0"}} title="CometChat Flag Message Dialog — Default" allow="clipboard-write" />

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).

```tsx lines theme={null}
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

```tsx lines theme={null}
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:

```tsx lines theme={null}
<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:

```tsx lines theme={null}
<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.

```tsx lines theme={null}
<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.

```tsx lines theme={null}
<CometChatFlagMessageDialog
  message={message}
  isOpen={open}
  onClose={() => setOpen(false)}
/>
```

#### onError

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

```tsx lines theme={null}
<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

```css lines title="App.css" theme={null}
.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"`.