Popover - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatPopover",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatPopover } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A floating popover primitive that positions content relative to a trigger element with viewport-aware auto-flipping.",
  "cssRootClass": ".cometchat-popover",
  "primaryOutput": {
    "prop": "onClose",
    "type": "() => void"
  },
  "props": {
    "callbacks": {
      "onClose": { "type": "() => void", "default": "undefined" },
      "onOpen": { "type": "() => void", "default": "undefined" }
    },
    "behavior": {
      "isOpen": { "type": "boolean", "default": "undefined (uncontrolled)" },
      "placement": { "type": "'top' | 'right' | 'bottom' | 'left'", "default": "'bottom'" },
      "closeOnOutsideClick": { "type": "boolean", "default": "true" },
      "showOnHover": { "type": "boolean", "default": "false" },
      "debounceOnHover": { "type": "number", "default": "500" },
      "showArrow": { "type": "boolean", "default": "false" },
      "trapFocus": { "type": "boolean", "default": "false" }
    },
    "accessibility": {
      "ariaLabel": { "type": "string", "default": "undefined" },
      "ariaLabelledBy": { "type": "string", "default": "undefined" },
      "ariaDescribedBy": { "type": "string", "default": "undefined" }
    },
    "viewSlots": {
      "children (Trigger)": { "type": "ReactNode", "default": "required" },
      "children (Content)": { "type": "ReactNode", "default": "required" }
    }
  },
  "events": [],
  "sdkListeners": [],
  "types": {
    "CometChatPopoverPlacement": "'top' | 'right' | 'bottom' | 'left'"
  }
}

Where It Fits

CometChatPopover is a base positioning primitive used by other components that need floating content anchored to a trigger element. It handles viewport-aware placement, keyboard accessibility, and focus management so consuming components don’t have to.

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

function App() {
  return (
    <CometChatPopover.Root placement="bottom" closeOnOutsideClick>
      <CometChatPopover.Trigger>
        <button>Options</button>
      </CometChatPopover.Trigger>
      <CometChatPopover.Content>
        <div style={{ padding: 16 }}>
          <p>Popover content here</p>
        </div>
      </CometChatPopover.Content>
    </CometChatPopover.Root>
  );
}

Minimal Render

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

function Demo() {
  return (
    <CometChatPopover.Root>
      <CometChatPopover.Trigger>
        <button>Click me</button>
      </CometChatPopover.Trigger>
      <CometChatPopover.Content>
        <div>Content</div>
      </CometChatPopover.Content>
    </CometChatPopover.Root>
  );
}

Root CSS class: .cometchat-popover

Actions and Events

Callback Props

onOpen

Called when the popover opens (click, hover, or keyboard trigger).

<CometChatPopover.Root onOpen={() => console.log("opened")}>
  {/* ... */}
</CometChatPopover.Root>

onClose

Called when the popover requests to close (outside click, Escape key).

<CometChatPopover.Root onClose={() => console.log("closed")}>
  {/* ... */}
</CometChatPopover.Root>

Controlled Mode

Pass isOpen to control the popover externally. The component calls onOpen/onClose to request state changes, but the consumer owns the state.

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

function ControlledExample() {
  const [open, setOpen] = useState(false);

  return (
    <CometChatPopover.Root
      isOpen={open}
      onOpen={() => setOpen(true)}
      onClose={() => setOpen(false)}
      placement="top"
    >
      <CometChatPopover.Trigger>
        <button>Toggle</button>
      </CometChatPopover.Trigger>
      <CometChatPopover.Content>
        <div style={{ padding: 16 }}>
          <p>Controlled popover</p>
          <button onClick={() => setOpen(false)}>Close</button>
        </div>
      </CometChatPopover.Content>
    </CometChatPopover.Root>
  );
}

Hover Trigger with Arrow

Use showOnHover for tooltip-like behavior and showArrow to render a directional arrow.

<CometChatPopover.Root showOnHover showArrow placement="top" debounceOnHover={300}>
  <CometChatPopover.Trigger>
    <span>Hover me</span>
  </CometChatPopover.Trigger>
  <CometChatPopover.Content>
    <div style={{ padding: 8 }}>Tooltip text</div>
  </CometChatPopover.Content>
</CometChatPopover.Root>

Focus Trap

Enable trapFocus for dialog-like popovers where Tab/Shift+Tab should cycle within the content.

<CometChatPopover.Root placement="bottom" trapFocus ariaLabel="Settings menu">
  <CometChatPopover.Trigger>
    <button>Settings</button>
  </CometChatPopover.Trigger>
  <CometChatPopover.Content>
    <div style={{ padding: 16, display: "flex", flexDirection: "column", gap: 8 }}>
      <button>Option 1</button>
      <button>Option 2</button>
      <button>Option 3</button>
    </div>
  </CometChatPopover.Content>
</CometChatPopover.Root>

CSS Architecture

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

Key Selectors

Target	Selector
Root wrapper	`.cometchat-popover`
Trigger wrapper	`.cometchat-popover__trigger`
Content panel	`.cometchat-popover__content`
Content positioned	`.cometchat-popover__content--positioned`
Content top	`.cometchat-popover__content--top`
Content bottom	`.cometchat-popover__content--bottom`
Content left	`.cometchat-popover__content--left`
Content right	`.cometchat-popover__content--right`
Arrow	`.cometchat-popover__arrow`
Arrow top	`.cometchat-popover__arrow--top`
Arrow bottom	`.cometchat-popover__arrow--bottom`
Arrow left	`.cometchat-popover__arrow--left`
Arrow right	`.cometchat-popover__arrow--right`

.cometchat-popover__content {
  border-radius: 16px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.15);
  max-width: 400px;
}

Customization Matrix

What to change	Where	Property/API	Example
Placement	Component props	`placement`	`placement="top"`
Control open state	Component props	`isOpen`, `onClose`, `onOpen`	`isOpen={open}`
Disable outside click	Component props	`closeOnOutsideClick`	`closeOnOutsideClick={false}`
Hover trigger	Component props	`showOnHover`, `debounceOnHover`	`showOnHover debounceOnHover={300}`
Show arrow	Component props	`showArrow`	`showArrow`
Focus trap	Component props	`trapFocus`	`trapFocus`
ARIA label	Component props	`ariaLabel`	`ariaLabel="Menu"`
Visual styling	Global CSS	`.cometchat-popover__content`	See CSS Selectors table

Props

All props are optional unless noted otherwise.

ariaDescribedBy

ID of element that describes the popover content.


Type	`string`
Default	`undefined`

ariaLabel

Custom ARIA label for the popover content.


Type	`string`
Default	`undefined`

ariaLabelledBy

ID of element that labels the popover content.


Type	`string`
Default	`undefined`

className

Optional custom CSS class name applied to the root container.


Type	`string`
Default	`undefined`

closeOnOutsideClick

Whether clicking outside the popover closes it.


Type	`boolean`
Default	`true`

debounceOnHover

Debounce delay in milliseconds for hover open/close.


Type	`number`
Default	`500`

isOpen

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


Type	`boolean`
Default	`undefined` (uncontrolled)

onClose

Callback when the popover requests to close (outside click, Escape key).


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

onOpen

Callback when the popover opens.


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

placement

Preferred placement of the popover relative to the trigger. Auto-flips if insufficient viewport space.


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

type CometChatPopoverPlacement = 'top' | 'right' | 'bottom' | 'left';

showArrow

Whether to show a directional arrow pointing to the trigger.


Type	`boolean`
Default	`false`

showOnHover

Show the popover on hover instead of click.


Type	`boolean`
Default	`false`

trapFocus

Enable focus trap within the popover content. Tab/Shift+Tab cycles within the popover when enabled.


Type	`boolean`
Default	`false`

CSS Selectors

Target	Selector
Root wrapper	`.cometchat-popover`
Trigger wrapper	`.cometchat-popover__trigger`
Content panel	`.cometchat-popover__content`
Content positioned	`.cometchat-popover__content--positioned`
Placement top	`.cometchat-popover__content--top`
Placement bottom	`.cometchat-popover__content--bottom`
Placement left	`.cometchat-popover__content--left`
Placement right	`.cometchat-popover__content--right`
Arrow	`.cometchat-popover__arrow`
Arrow top	`.cometchat-popover__arrow--top`
Arrow bottom	`.cometchat-popover__arrow--bottom`
Arrow left	`.cometchat-popover__arrow--left`
Arrow right	`.cometchat-popover__arrow--right`

Documentation Index

​Where It Fits

​Minimal Render

​Actions and Events

​Callback Props

​onOpen

​onClose

​Controlled Mode

​Hover Trigger with Arrow

​Focus Trap

​CSS Architecture

​Key Selectors

​Example: Custom popover styling

​Customization Matrix

​Props

​ariaDescribedBy

​ariaLabel

​ariaLabelledBy

​className

​closeOnOutsideClick

​debounceOnHover

​isOpen

​onClose

​onOpen

​placement

​showArrow

​showOnHover

​trapFocus

​CSS Selectors

Where It Fits

Minimal Render

Actions and Events

Callback Props

onOpen

onClose

Controlled Mode

Hover Trigger with Arrow

Focus Trap

CSS Architecture

Key Selectors

Example: Custom popover styling

Customization Matrix

Props

ariaDescribedBy

ariaLabel

ariaLabelledBy

className

closeOnOutsideClick

debounceOnHover

isOpen

onClose

onOpen

placement

showArrow

showOnHover

trapFocus

CSS Selectors