Context Menu - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatContextMenu",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatContextMenu } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A context menu that displays top-row icon actions and an overflow dropdown for additional options.",
  "cssRootClass": ".cometchat-context-menu",
  "subComponents": ["Root", "Item", "Trigger", "Dropdown"],
  "props": {
    "Root": {
      "items": { "type": "CometChatContextMenuItemData[]", "default": "[]" },
      "topMenuSize": { "type": "number", "default": "2" },
      "onOptionClicked": { "type": "(item: CometChatContextMenuItemData) => void", "default": "undefined" },
      "placement": { "type": "CometChatContextMenuPlacement", "default": "'left'" },
      "moreButtonTooltip": { "type": "string", "default": "undefined" },
      "closeOnOutsideClick": { "type": "boolean", "default": "true" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Item": {
      "item": { "type": "CometChatContextMenuItemData", "default": "undefined", "note": "Required." },
      "variant": { "type": "'icon' | 'full'", "default": "'full'" },
      "className": { "type": "string", "default": "undefined" }
    },
    "Trigger": {
      "tooltip": { "type": "string", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Dropdown": {
      "placement": { "type": "CometChatContextMenuPlacement", "default": "inherited from Root" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    }
  },
  "types": {
    "CometChatContextMenuItemData": {
      "id": "string",
      "title": "string",
      "icon": "ReactNode (optional)",
      "iconURL": "string (optional)",
      "onClick": "() => void",
      "disabled": "boolean (optional)",
      "className": "string (optional)"
    },
    "CometChatContextMenuPlacement": "'top' | 'right' | 'bottom' | 'left'",
    "CometChatContextMenuContextValue": {
      "isOpen": "boolean",
      "open": "() => void",
      "close": "() => void",
      "toggle": "() => void",
      "placement": "CometChatContextMenuPlacement",
      "onOptionClicked": "(item: CometChatContextMenuItemData) => void | undefined",
      "triggerRef": "RefObject<HTMLButtonElement | null>"
    }
  }
}

Where It Fits

CometChatContextMenu is a base component used as the overflow action menu across the UI Kit. It appears on message bubbles, conversation list items, group member rows, user list items, and message headers. It splits actions into a visible top row of icon buttons and a dropdown for the rest.

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

const options = [
  { id: "edit", title: "Edit", icon: <EditIcon />, onClick: () => handleEdit() },
  { id: "copy", title: "Copy", icon: <CopyIcon />, onClick: () => handleCopy() },
  { id: "info", title: "Info", icon: <InfoIcon />, onClick: () => handleInfo() },
  { id: "delete", title: "Delete", icon: <DeleteIcon />, onClick: () => handleDelete() },
];

function MessageBubbleActions() {
  return (
    <CometChatContextMenu.Root
      items={options}
      topMenuSize={2}
      placement="left"
      onOptionClicked={(item) => console.log("Selected:", item.id)}
    />
  );
}

Minimal Render

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

function Demo() {
  return (
    <CometChatContextMenu.Root
      items={[
        { id: "1", title: "Edit", onClick: () => {} },
        { id: "2", title: "Delete", onClick: () => {} },
      ]}
      topMenuSize={1}
    />
  );
}

Root CSS class: .cometchat-context-menu

Sub-Components

CometChatContextMenu is a compound component with four sub-components:

Sub-component	Purpose
`Root`	Container that provides context, orchestrates top-row items and dropdown.
`Item`	A single action rendered as a button. Supports `icon` (top-row) and `full` (dropdown) variants.
`Trigger`	The “more” button that toggles the dropdown.
`Dropdown`	The overflow popover with keyboard navigation and focus trap.

Root

The outermost wrapper. In data-driven mode, pass items and topMenuSize and it renders everything automatically. For full control, pass children instead.

Data-driven
Fully composed

<CometChatContextMenu.Root
  items={options}
  topMenuSize={2}
  placement="left"
  closeOnOutsideClick
/>

<CometChatContextMenu.Root placement="bottom">
  <CometChatContextMenu.Item item={editAction} variant="icon" />
  <CometChatContextMenu.Trigger tooltip="More options" />
  <CometChatContextMenu.Dropdown>
    <CometChatContextMenu.Item item={copyAction} variant="full" />
    <CometChatContextMenu.Item item={deleteAction} variant="full" />
  </CometChatContextMenu.Dropdown>
</CometChatContextMenu.Root>

Item

Renders a single action. In icon variant, it shows only the icon with an aria-label. In full variant, it shows icon + title and uses role="menuitem".

<CometChatContextMenu.Item
  item={{
    id: "edit",
    title: "Edit Message",
    icon: <EditIcon />,
    onClick: () => handleEdit(),
  }}
  variant="full"
/>

Trigger

The “more” button. Renders a vertical ellipsis icon by default. Pass children for a custom trigger.

<CometChatContextMenu.Trigger tooltip="Show more">
  <span>⋯</span>
</CometChatContextMenu.Trigger>

The overflow popover. Positioned relative to the root container using the placement prop. Includes full keyboard navigation and a focus trap.

<CometChatContextMenu.Dropdown placement="bottom">
  <CometChatContextMenu.Item item={action1} variant="full" />
  <CometChatContextMenu.Item item={action2} variant="full" />
</CometChatContextMenu.Dropdown>

Actions and Events

Callback Props

onOptionClicked

Called when any menu item is selected (top-row or dropdown). Receives the full CometChatContextMenuItemData object. When provided, overrides individual item.onClick callbacks.

<CometChatContextMenu.Root
  items={options}
  topMenuSize={2}
  onOptionClicked={(item) => {
    console.log("Selected action:", item.id, item.title);
  }}
/>

Custom View Slots

Slot	Signature	Replaces
`children` on `Root`	`ReactNode`	Entire auto-generated layout (top-row + trigger + dropdown)
`children` on `Trigger`	`ReactNode`	Default “more” icon
`children` on `Dropdown`	`ReactNode`	Auto-generated dropdown items

Custom trigger content

<CometChatContextMenu.Root placement="bottom">
  <CometChatContextMenu.Item item={editAction} variant="icon" />
  <CometChatContextMenu.Trigger>
    <span style={{ fontSize: 14, padding: "0 4px" }}>⋯</span>
  </CometChatContextMenu.Trigger>
  <CometChatContextMenu.Dropdown>
    <CometChatContextMenu.Item item={copyAction} variant="full" />
    <CometChatContextMenu.Item item={deleteAction} variant="full" />
  </CometChatContextMenu.Dropdown>
</CometChatContextMenu.Root>

Common Patterns

Message bubble options

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

function MessageOptions({ options }) {
  return (
    <CometChatContextMenu.Root
      items={options}
      topMenuSize={2}
      placement="left"
      closeOnOutsideClick
    />
  );
}

<CometChatContextMenu.Root items={options} topMenuSize={0} placement="bottom" />

<CometChatContextMenu.Root items={options.slice(0, 3)} topMenuSize={10} />

The context menu is fully keyboard-accessible:

Key	Behavior
`Tab`	Moves focus between top-row items and the trigger button
`Enter` / `Space`	On top-row item: activates it. On trigger: toggles dropdown
`ArrowDown`	On trigger: opens dropdown. In dropdown: moves to next item (wraps)
`ArrowUp`	In dropdown: moves to previous item (wraps)
`Home`	In dropdown: moves focus to first item
`End`	In dropdown: moves focus to last item
`Escape`	Closes dropdown and returns focus to trigger
`Tab` (in dropdown)	Cycles within dropdown items (focus trap)

When the dropdown opens, focus moves to the first enabled item. When it closes, focus returns to the trigger button.

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-context-menu) consumes these tokens via var().
Overrides target .cometchat-context-menu descendant selectors.

Key Selectors

Target	Selector
Root container	`.cometchat-context-menu`
Top menu row	`.cometchat-context-menu__top-menu`
Top menu item	`.cometchat-context-menu__top-menu-item`
Top menu item icon	`.cometchat-context-menu__top-menu-item-icon`
Trigger button	`.cometchat-context-menu__trigger`
Trigger icon	`.cometchat-context-menu__trigger-icon`
Dropdown	`.cometchat-context-menu__dropdown`
Dropdown item	`.cometchat-context-menu__dropdown-item`
Dropdown item icon	`.cometchat-context-menu__dropdown-item-icon`
Dropdown item title	`.cometchat-context-menu__dropdown-item-title`

App.css

.cometchat-context-menu__dropdown {
  border-radius: 12px;
  border-color: var(--brand-border);
}

.cometchat-context-menu__dropdown-item:hover:not(:disabled) {
  background: var(--brand-hover);
}

.cometchat-context-menu__top-menu-item:hover:not(:disabled) {
  background: var(--brand-hover);
}

Customization Matrix

What to change	Where	Property/API	Example
Menu items	Component props	`items` on `Root`	`<Root items={myItems}>`
Top row count	Component props	`topMenuSize` on `Root`	`<Root topMenuSize={3}>`
Dropdown position	Component props	`placement` on `Root` or `Dropdown`	`<Root placement="bottom">`
Handle selection	Component props	`onOptionClicked` on `Root`	`<Root onOptionClicked={handler}>`
Disable an item	Item data	`disabled` on `CometChatContextMenuItemData`	`{ disabled: true }`
Custom trigger	Sub-component	`children` on `Trigger`	`<Trigger><MyIcon /></Trigger>`
Change visual styling	Global CSS	`.cometchat-context-menu` selectors	See example above

Props

All props are optional unless noted otherwise.

CometChatContextMenu.Root

items

Array of menu item data objects. When provided without children, the component auto-renders top-row items and dropdown.


Type	`CometChatContextMenuItemData[]`
Default	`[]`

interface CometChatContextMenuItemData {
  id: string;
  title: string;
  icon?: ReactNode;
  iconURL?: string;
  onClick: () => void;
  disabled?: boolean;
  className?: string;
}

topMenuSize

Number of items visible in the top row. Remaining items go to the dropdown. When 0, all items are in the dropdown. When >= items.length, no dropdown is rendered.


Type	`number`
Default	`2`

onOptionClicked

Called when any menu item is selected. Receives the full item data object. When provided, overrides individual item.onClick callbacks.


Type	`(item: CometChatContextMenuItemData) => void`
Default	`undefined`

placement

Position of the dropdown relative to the trigger.


Type	`'top' \| 'right' \| 'bottom' \| 'left'`
Default	`'left'`

moreButtonTooltip

Tooltip text for the “more” trigger button.


Type	`string`
Default	`undefined`

closeOnOutsideClick

Whether clicking outside the component closes the dropdown.


Type	`boolean`
Default	`true`

className

Custom CSS class appended to the root container.


Type	`string`
Default	`undefined`

children

Custom content. When provided, overrides the data-driven rendering entirely.


Type	`ReactNode`
Default	`undefined`

CometChatContextMenu.Item

item

The menu item data object.


Type	`CometChatContextMenuItemData`
Default	`undefined`

Required.

variant

Display mode. icon renders icon-only (for top row). full renders icon + title (for dropdown).


Type	`'icon' \| 'full'`
Default	`'full'`

className

Custom CSS class appended to the item button.


Type	`string`
Default	`undefined`

CometChatContextMenu.Trigger

Tooltip and aria-label text for the trigger button.


Type	`string`
Default	`undefined`

className

Custom CSS class appended to the trigger button.


Type	`string`
Default	`undefined`

children

Custom trigger content. Replaces the default vertical ellipsis icon.


Type	`ReactNode`
Default	`undefined`

placement

Position of the dropdown. Overrides the value from Root context.


Type	`'top' \| 'right' \| 'bottom' \| 'left'`
Default	inherited from `Root`

className

Custom CSS class appended to the dropdown container.


Type	`string`
Default	`undefined`

children

Dropdown content. Typically CometChatContextMenu.Item elements with variant="full".


Type	`ReactNode`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-context-menu`
Top menu row	`.cometchat-context-menu__top-menu`
Top menu item	`.cometchat-context-menu__top-menu-item`
Top menu item icon	`.cometchat-context-menu__top-menu-item-icon`
Trigger button	`.cometchat-context-menu__trigger`
Trigger icon	`.cometchat-context-menu__trigger-icon`
Dropdown	`.cometchat-context-menu__dropdown`
Dropdown (top)	`.cometchat-context-menu__dropdown--top`
Dropdown (right)	`.cometchat-context-menu__dropdown--right`
Dropdown (bottom)	`.cometchat-context-menu__dropdown--bottom`
Dropdown (left)	`.cometchat-context-menu__dropdown--left`
Dropdown item	`.cometchat-context-menu__dropdown-item`
Dropdown item (disabled)	`.cometchat-context-menu__dropdown-item--disabled`
Dropdown item icon	`.cometchat-context-menu__dropdown-item-icon`
Dropdown item title	`.cometchat-context-menu__dropdown-item-title`

Documentation Index

​Where It Fits

​Minimal Render

​Sub-Components

​Root

​Item

​Trigger

​Dropdown

​Actions and Events

​Callback Props

​onOptionClicked

​Custom View Slots

​Custom trigger content

​Common Patterns

​Message bubble options

​All items in dropdown (no top row)

​All items in top row (no dropdown)

​Keyboard Navigation

​CSS Architecture

​Key Selectors

​Example: Brand-themed context menu

​Customization Matrix

​Props

​CometChatContextMenu.Root

​items

​topMenuSize

​onOptionClicked

​placement

​moreButtonTooltip

​closeOnOutsideClick

​className

​children

​CometChatContextMenu.Item

​item

​variant

​className

​CometChatContextMenu.Trigger

​tooltip

​className

​children

​CometChatContextMenu.Dropdown

​placement

​className

​children

​CSS Selectors

Where It Fits

Minimal Render

Sub-Components

Root

Item

Trigger

Dropdown

Actions and Events

Callback Props

onOptionClicked

Custom View Slots

Custom trigger content

Common Patterns

Message bubble options

All items in dropdown (no top row)

All items in top row (no dropdown)

Keyboard Navigation

CSS Architecture

Key Selectors

Example: Brand-themed context menu

Customization Matrix

Props

CometChatContextMenu.Root

items

topMenuSize

onOptionClicked

placement

moreButtonTooltip

closeOnOutsideClick

className

children

CometChatContextMenu.Item

item

variant

className

CometChatContextMenu.Trigger

tooltip

className

children

CometChatContextMenu.Dropdown

placement

className

children

CSS Selectors