List Item - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatListItem",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatListItem } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A composable list row component that displays a leading view, title, subtitle, trailing view, and hover-revealed menu view.",
  "cssRootClass": ".cometchat-list-item",
  "subComponents": ["Root", "LeadingView", "Title", "Subtitle", "TrailingView", "MenuView"],
  "props": {
    "Root": {
      "id": { "type": "string", "default": "undefined" },
      "isActive": { "type": "boolean", "default": "false" },
      "disabled": { "type": "boolean", "default": "false" },
      "onItemClick": { "type": "(event: MouseEvent | KeyboardEvent) => void", "default": "undefined" },
      "className": { "type": "string", "default": "undefined" },
      "aria-label": { "type": "string", "default": "undefined" },
      "menuShortcutKey": { "type": "string | null", "default": "'M'" },
      "disableTabIndex": { "type": "boolean", "default": "false" },
      "isFocused": { "type": "boolean", "default": "false" },
      "children": { "type": "ReactNode", "default": "undefined", "note": "Required." }
    },
    "LeadingView": {
      "children": { "type": "ReactNode", "default": "undefined", "note": "Required." },
      "className": { "type": "string", "default": "undefined" }
    },
    "Title": {
      "children": { "type": "ReactNode", "default": "undefined", "note": "Required." },
      "className": { "type": "string", "default": "undefined" }
    },
    "Subtitle": {
      "children": { "type": "ReactNode", "default": "undefined", "note": "Required." },
      "className": { "type": "string", "default": "undefined" }
    },
    "TrailingView": {
      "children": { "type": "ReactNode", "default": "undefined", "note": "Required." },
      "className": { "type": "string", "default": "undefined" }
    },
    "MenuView": {
      "children": { "type": "ReactNode", "default": "undefined", "note": "Required." },
      "className": { "type": "string", "default": "undefined" }
    }
  },
  "types": {
    "CometChatListItemContextValue": {
      "isHovered": "boolean",
      "isActive": "boolean",
      "disabled": "boolean",
      "id": "string | undefined",
      "isMenuVisible": "boolean"
    }
  }
}

Where It Fits

CometChatListItem is the universal row component used throughout the UI Kit. It appears inside CometChatConversations, CometChatUsers, CometChatGroups, CometChatGroupMembers, CometChatCallLogs, and CometChatMessageInformation. Each row displays a leading view (typically an avatar), a title, an optional subtitle, a trailing view (badge, timestamp), and a hover/focus-revealed menu view. Compose only the sub-components you need — to hide the subtitle, just don’t render it.

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

function ConversationRow({ conversation, isSelected, onClick }) {
  return (
    <CometChatListItem.Root
      id={conversation.id}
      isActive={isSelected}
      onItemClick={onClick}
      aria-label={`Conversation with ${conversation.name}`}
    >
      <CometChatListItem.LeadingView>
        <CometChatAvatar.Root name={conversation.name} image={conversation.avatarUrl} size="medium">
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      </CometChatListItem.LeadingView>
      <CometChatListItem.Title>{conversation.name}</CometChatListItem.Title>
      <CometChatListItem.Subtitle>
        <span>{conversation.lastMessage}</span>
      </CometChatListItem.Subtitle>
      <CometChatListItem.TrailingView>
        <span>3:42 PM</span>
      </CometChatListItem.TrailingView>
      <CometChatListItem.MenuView>
        <button aria-label="More options">⋮</button>
      </CometChatListItem.MenuView>
    </CometChatListItem.Root>
  );
}

Minimal Render

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

function Demo() {
  return (
    <CometChatListItem.Root>
      <CometChatListItem.Title>John Doe</CometChatListItem.Title>
    </CometChatListItem.Root>
  );
}

Root CSS class: .cometchat-list-item

Sub-Components

CometChatListItem is a compound component with six sub-components:

Sub-component	Purpose
`Root`	Container that provides context, handles hover/focus/keyboard state, renders the row layout with ARIA attributes.
`LeadingView`	Left-side slot for an avatar or custom icon.
`Title`	Primary text displayed in the row. Truncates with ellipsis on overflow.
`Subtitle`	Secondary text or custom content below the title.
`TrailingView`	Right-side slot for timestamps, badges, or status. Hidden when MenuView is visible on hover/focus.
`MenuView`	Contextual actions revealed on hover or keyboard focus. Replaces TrailingView when visible.

Root

The outermost wrapper. Sets up the list item context, manages hover/focus state, handles click and keyboard activation (Enter/Space), and applies ARIA attributes (role="option", aria-selected, aria-disabled).

<CometChatListItem.Root
  id="user-1"
  isActive={true}
  onItemClick={(e) => console.log("clicked")}
  aria-label="Conversation with John Doe"
>
  {/* LeadingView, Title, Subtitle, TrailingView, MenuView */}
</CometChatListItem.Root>

LeadingView

Renders content in the left-side area. Typically wraps a CometChatAvatar, but accepts any ReactNode for custom icons or images.

<CometChatListItem.LeadingView>
  <CometChatAvatar.Root name="Jane Smith" image={avatarUrl}>
    <CometChatAvatar.Image />
    <CometChatAvatar.Initials />
  </CometChatAvatar.Root>
</CometChatListItem.LeadingView>

Title

Primary text for the row. Long text is truncated with an ellipsis. Accepts a string or custom ReactNode.

<CometChatListItem.Title>Jane Smith</CometChatListItem.Title>

Subtitle

Secondary content below the title. Accepts text or custom ReactNode for typing indicators, last message previews, etc.

<CometChatListItem.Subtitle>
  <span>Last seen 5 minutes ago</span>
</CometChatListItem.Subtitle>

TrailingView

Right-side content area for timestamps, badges, or status indicators. Automatically hidden when the user hovers or focuses the row and a MenuView is present.

<CometChatListItem.TrailingView>
  <span>3:42 PM</span>
</CometChatListItem.TrailingView>

MenuView

Contextual actions that appear on hover or keyboard focus, replacing the TrailingView. Click events on the menu area stop propagation to prevent triggering the row’s onItemClick.

<CometChatListItem.MenuView>
  <button aria-label="More options">⋮</button>
</CometChatListItem.MenuView>

Actions and Events

Callback Props

onItemClick

Fires when the list item is clicked or activated via Enter/Space. The event object is passed through.

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

function Demo() {
  return (
    <CometChatListItem.Root
      id="user-1"
      onItemClick={(event) => {
        console.log("Item clicked", event);
      }}
    >
      <CometChatListItem.Title>John Doe</CometChatListItem.Title>
    </CometChatListItem.Root>
  );
}

Common Patterns

Conversation row

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

function ConversationRow({ name, avatar, lastMessage, time, unread, isSelected, onClick }) {
  return (
    <CometChatListItem.Root id={name} isActive={isSelected} onItemClick={onClick}>
      <CometChatListItem.LeadingView>
        <CometChatAvatar.Root name={name} image={avatar} size="medium">
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      </CometChatListItem.LeadingView>
      <CometChatListItem.Title>{name}</CometChatListItem.Title>
      <CometChatListItem.Subtitle>
        <span>{lastMessage}</span>
      </CometChatListItem.Subtitle>
      <CometChatListItem.TrailingView>
        <span>{time}</span>
      </CometChatListItem.TrailingView>
      <CometChatListItem.MenuView>
        <button aria-label="More options">⋮</button>
      </CometChatListItem.MenuView>
    </CometChatListItem.Root>
  );
}

User row (no trailing view)

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

function UserRow({ name, avatar, status, onClick }) {
  return (
    <CometChatListItem.Root id={name} onItemClick={onClick}>
      <CometChatListItem.LeadingView>
        <CometChatAvatar.Root name={name} image={avatar} size="medium">
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
          <CometChatAvatar.StatusIndicator status={status} />
        </CometChatAvatar.Root>
      </CometChatListItem.LeadingView>
      <CometChatListItem.Title>{name}</CometChatListItem.Title>
    </CometChatListItem.Root>
  );
}

Title-only row

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

function SimpleRow({ label, onClick }) {
  return (
    <CometChatListItem.Root onItemClick={onClick}>
      <CometChatListItem.Title>{label}</CometChatListItem.Title>
    </CometChatListItem.Root>
  );
}

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

Key Selectors

Target	Selector
Root	`.cometchat-list-item`
Leading view	`.cometchat-list-item__leading-view`
Body wrapper	`.cometchat-list-item__body`
Title container	`.cometchat-list-item__title-container`
Title	`.cometchat-list-item__title`
Subtitle	`.cometchat-list-item__subtitle`
Trailing view	`.cometchat-list-item__trailing-view`
Menu view	`.cometchat-list-item__menu-view`
Active modifier	`.cometchat-list-item--active`
Disabled modifier	`.cometchat-list-item--disabled`

Example: Brand-themed list item

App.css

.cometchat-list-item {
  border-bottom: 1px solid var(--cometchat-border-color-light, #e8e8e8);
}

.cometchat-list-item--active {
  background: var(--brand-selected-bg, #e8f0fe);
}

.cometchat-list-item__title {
  font-weight: 600;
}

Customization Matrix

What to change	Where	Property/API	Example
Active/selected state	Component props	`isActive` on `Root`	`<Root isActive={true}>`
Disabled state	Component props	`disabled` on `Root`	`<Root disabled>`
Click handler	Component props	`onItemClick` on `Root`	`<Root onItemClick={fn}>`
Show/hide subtitle	Composition	Render or omit `Subtitle`	Don’t render `<Subtitle />`
Show/hide trailing	Composition	Render or omit `TrailingView`	Don’t render `<TrailingView />`
Show/hide menu	Composition	Render or omit `MenuView`	Don’t render `<MenuView />`
Show/hide avatar	Composition	Render or omit `LeadingView`	Don’t render `<LeadingView />`
Row background	Global CSS	`.cometchat-list-item`	`background: #f5f5f5;`
Title font	Global CSS	`.cometchat-list-item__title`	`font-weight: 600;`
Row padding	CSS token	`--cometchat-list-item-padding`	`--cometchat-list-item-padding: 12px 20px;`

Props

All props are optional unless noted otherwise.

CometChatListItem.Root

children

Sub-components to render inside the list item row. Typically LeadingView, Title, Subtitle, TrailingView, and MenuView.


Type	`ReactNode`
Default	`undefined`

Required.

id

Unique identifier for the list item. Passed to the DOM id attribute and available in context.


Type	`string`
Default	`undefined`

isActive

Whether the item is currently selected/active. Applies the --active modifier class and sets aria-selected="true".


Type	`boolean`
Default	`false`

disabled

Whether the item is disabled. Applies the --disabled modifier class, sets aria-disabled="true", and prevents click/keyboard activation.


Type	`boolean`
Default	`false`

onItemClick

Callback fired when the item is clicked or activated via Enter/Space. Receives the original mouse or keyboard event.


Type	`(event: MouseEvent \| KeyboardEvent) => void`
Default	`undefined`

aria-label

Custom accessible label for the list item. Passed through to the root element’s aria-label attribute.


Type	`string`
Default	`undefined`

className

Custom CSS class appended to the root container.


Type	`string`
Default	`undefined`

menuShortcutKey

Keyboard shortcut key for toggling menu visibility. Set to null or empty string to disable. Per WCAG 2.1.4, single-character shortcuts must be configurable.


Type	`string \| null`
Default	`'M'`

disableTabIndex

When true, removes the tabIndex from the root element. Use when the parent list manages focus via roving tabindex.


Type	`boolean`
Default	`false`

isFocused

Whether the list item is currently focused (managed by parent component). When true, the menu view becomes visible.


Type	`boolean`
Default	`false`

CometChatListItem.LeadingView

children

Content to render in the leading area. Typically a CometChatAvatar or custom icon.


Type	`ReactNode`
Default	`undefined`

Required.

className

Custom CSS class appended to the leading view container.


Type	`string`
Default	`undefined`

CometChatListItem.Title

children

Title text or custom ReactNode. Long text is truncated with an ellipsis.


Type	`ReactNode`
Default	`undefined`

Required.

className

Custom CSS class appended to the title element.


Type	`string`
Default	`undefined`

CometChatListItem.Subtitle

children

Subtitle content — text, typing indicator, last message preview, or any ReactNode.


Type	`ReactNode`
Default	`undefined`

Required.

className

Custom CSS class appended to the subtitle element.


Type	`string`
Default	`undefined`

CometChatListItem.TrailingView

children

Content for the right-side area — timestamps, badges, status indicators. Hidden when MenuView is visible on hover/focus.


Type	`ReactNode`
Default	`undefined`

Required.

className

Custom CSS class appended to the trailing view container.


Type	`string`
Default	`undefined`

CometChatListItem.MenuView

children

Menu content revealed on hover or keyboard focus. Click events stop propagation to prevent triggering the row’s onItemClick.


Type	`ReactNode`
Default	`undefined`

Required.

className

Custom CSS class appended to the menu view container.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-list-item`
Root (active)	`.cometchat-list-item--active`
Root (disabled)	`.cometchat-list-item--disabled`
Leading view	`.cometchat-list-item__leading-view`
Body wrapper	`.cometchat-list-item__body`
Title container	`.cometchat-list-item__title-container`
Title	`.cometchat-list-item__title`
Subtitle	`.cometchat-list-item__subtitle`
Trailing view	`.cometchat-list-item__trailing-view`
Menu view	`.cometchat-list-item__menu-view`

Documentation Index

​Where It Fits

​Minimal Render

​Sub-Components

​Root

​LeadingView

​Title

​Subtitle

​TrailingView

​MenuView

​Actions and Events

​Callback Props

​onItemClick

​Common Patterns

​Conversation row

​User row (no trailing view)

​Title-only row

​CSS Architecture

​Key Selectors

​Example: Brand-themed list item

​Customization Matrix

​Props

​CometChatListItem.Root

​children

​id

​isActive

​disabled

​onItemClick

​aria-label

​className

​menuShortcutKey

​disableTabIndex

​isFocused

​CometChatListItem.LeadingView

​children

​className

​CometChatListItem.Title

​children

​className

​CometChatListItem.Subtitle

​children

​className

​CometChatListItem.TrailingView

​children

​className

​CometChatListItem.MenuView

​children

​className

​CSS Selectors

Where It Fits

Minimal Render

Sub-Components

Root

LeadingView

Title

Subtitle

TrailingView

MenuView

Actions and Events

Callback Props

onItemClick

Common Patterns

Conversation row

User row (no trailing view)

Title-only row

CSS Architecture

Key Selectors

Example: Brand-themed list item

Customization Matrix

Props

CometChatListItem.Root

children

id

isActive

disabled

onItemClick

aria-label

className

menuShortcutKey

disableTabIndex

isFocused

CometChatListItem.LeadingView

children

className

CometChatListItem.Title

children

className

CometChatListItem.Subtitle

children

className

CometChatListItem.TrailingView

children

className

CometChatListItem.MenuView

children

className

CSS Selectors