Avatar - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatAvatar",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatAvatar } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "A composable avatar component that displays a user or group image with initials fallback and optional online/offline status indicator.",
  "cssRootClass": ".cometchat-avatar",
  "subComponents": ["Root", "Image", "Initials", "StatusIndicator"],
  "props": {
    "Root": {
      "name": { "type": "string", "default": "''" },
      "image": { "type": "string", "default": "''" },
      "size": { "type": "'small' | 'medium' | 'large'", "default": "'medium'" },
      "className": { "type": "string", "default": "undefined" },
      "children": { "type": "ReactNode", "default": "undefined" }
    },
    "Image": {
      "className": { "type": "string", "default": "undefined" }
    },
    "Initials": {
      "className": { "type": "string", "default": "undefined" }
    },
    "StatusIndicator": {
      "status": { "type": "'online' | 'offline'", "default": "undefined", "note": "Required." },
      "className": { "type": "string", "default": "undefined" }
    }
  },
  "types": {
    "CometChatAvatarSize": "'small' | 'medium' | 'large'",
    "CometChatAvatarStatus": "'online' | 'offline'",
    "CometChatAvatarContextValue": {
      "name": "string",
      "image": "string",
      "size": "CometChatAvatarSize",
      "imageLoaded": "boolean",
      "imageError": "boolean"
    }
  }
}

Where It Fits

CometChatAvatar is a base component used throughout the UI Kit wherever a user or group needs visual representation. It appears inside CometChatConversations, CometChatUsers, CometChatGroups, CometChatMessageHeader, and CometChatMessageBubble. Compose the sub-components you need — render Image and Initials together for automatic fallback, add StatusIndicator to show presence.

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

function UserProfile({ user }) {
  return (
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <CometChatAvatar.Root name={user.name} image={user.avatar} size="large">
        <CometChatAvatar.Image />
        <CometChatAvatar.Initials />
        <CometChatAvatar.StatusIndicator status={user.status} />
      </CometChatAvatar.Root>
      <span>{user.name}</span>
    </div>
  );
}

Minimal Render

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

function Demo() {
  return (
    <CometChatAvatar.Root name="John Doe">
      <CometChatAvatar.Initials />
    </CometChatAvatar.Root>
  );
}

Root CSS class: .cometchat-avatar

Sub-Components

CometChatAvatar is a compound component with four sub-components:

Sub-component	Purpose
`Root`	Container that provides context (name, image, size, load state) to children. Renders the circular avatar wrapper.
`Image`	Displays the avatar image. Automatically hides when no image URL is provided or when the image fails to load.
`Initials`	Displays name initials as fallback text. Automatically hides when the image loads successfully.
`StatusIndicator`	Renders an online/offline presence dot positioned at the bottom-right corner.

Root

The outermost wrapper. Sets up the avatar context, applies size via data-size, and renders as a role="img" element with aria-label.

<CometChatAvatar.Root name="Jane Smith" image="https://example.com/avatar.png" size="large">
  {/* Image, Initials, StatusIndicator go here */}
</CometChatAvatar.Root>

Image

Renders an <img> tag sourced from the image prop on Root. Returns null when no image URL is set or when the image fails to load, allowing Initials to show instead.

<CometChatAvatar.Root name="Jane Smith" image="https://example.com/avatar.png">
  <CometChatAvatar.Image />
  <CometChatAvatar.Initials />
</CometChatAvatar.Root>

Initials

Extracts initials from the name prop on Root. For multi-word names, uses the first letter of the first two words. For single-word names, uses the first two characters. Hides automatically when the image loads successfully.

<CometChatAvatar.Root name="Jane Smith">
  <CometChatAvatar.Initials />
</CometChatAvatar.Root>

StatusIndicator

A small colored dot indicating online or offline presence. Positioned absolutely at the bottom-right of the avatar.

<CometChatAvatar.Root name="Jane Smith" size="large">
  <CometChatAvatar.Initials />
  <CometChatAvatar.StatusIndicator status="online" />
</CometChatAvatar.Root>

Common Patterns

Image with initials fallback

Render both Image and Initials together. The component automatically shows initials when the image is missing or fails to load.

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

function UserAvatar({ name, image, status }) {
  return (
    <CometChatAvatar.Root name={name} image={image} size="medium">
      <CometChatAvatar.Image />
      <CometChatAvatar.Initials />
      <CometChatAvatar.StatusIndicator status={status} />
    </CometChatAvatar.Root>
  );
}

Initials only (no image)

Omit the image prop and the Image sub-component for a pure initials avatar.

<CometChatAvatar.Root name="John Doe" size="small">
  <CometChatAvatar.Initials />
</CometChatAvatar.Root>

Avatar without status indicator

Simply don’t render StatusIndicator — no boolean prop needed.

<CometChatAvatar.Root name="John Doe" image={avatarUrl} size="medium">
  <CometChatAvatar.Image />
  <CometChatAvatar.Initials />
</CometChatAvatar.Root>

Size variants side by side

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

function AvatarSizes() {
  return (
    <div style={{ display: "flex", gap: 16, alignItems: "center" }}>
      <CometChatAvatar.Root name="SM" size="small">
        <CometChatAvatar.Initials />
      </CometChatAvatar.Root>
      <CometChatAvatar.Root name="MD" size="medium">
        <CometChatAvatar.Initials />
      </CometChatAvatar.Root>
      <CometChatAvatar.Root name="LG" size="large">
        <CometChatAvatar.Initials />
      </CometChatAvatar.Root>
    </div>
  );
}

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

Key Selectors

Target	Selector
Root container	`.cometchat-avatar`
Image	`.cometchat-avatar__image`
Initials text	`.cometchat-avatar__initials`
Status indicator	`.cometchat-avatar__status-indicator`
Online modifier	`.cometchat-avatar__status-indicator[data-status="online"]`
Offline modifier	`.cometchat-avatar__status-indicator[data-status="offline"]`

Size Modifiers

Size is controlled via the data-size attribute on the root element:

Size	Selector	Dimensions
Small	`.cometchat-avatar[data-size="small"]`	28×28px
Medium	`.cometchat-avatar[data-size="medium"]`	40×40px
Large	`.cometchat-avatar[data-size="large"]`	48×48px

Example: Brand-themed avatar

App.css

.cometchat-avatar {
  background: var(--brand-primary, #6851ff);
}

.cometchat-avatar__initials {
  color: var(--brand-on-primary, #ffffff);
  font-weight: 600;
}

.cometchat-avatar__status-indicator[data-status="online"] {
  background: var(--brand-success, #00c853);
}

Customization Matrix

What to change	Where	Property/API	Example
Avatar size	Component props	`size` on `Root`	`<Root size="large">`
Name / image	Component props	`name`, `image` on `Root`	`<Root name="Jane" image={url}>`
Show/hide status	Composition	Render or omit `StatusIndicator`	Don’t render `<StatusIndicator />`
Show/hide image	Composition	Render or omit `Image`	Don’t render `<Image />`
Background color	Global CSS	`.cometchat-avatar`	`background: #6851ff;`
Initials font	Global CSS	`.cometchat-avatar__initials`	`font-weight: 600;`
Status dot color	Global CSS	`.cometchat-avatar__status-indicator[data-status]`	`background: #00c853;`
Border radius	Global CSS	`--cometchat-radius-max`	`--cometchat-radius-max: 8px;`

Props

All props are optional unless noted otherwise.

CometChatAvatar.Root

name

Name used for generating initials and as the aria-label on the root element.


Type	`string`
Default	`''`

image

URL of the avatar image. When provided, Image sub-component renders an <img> tag. When the URL fails to load, Initials automatically takes over.


Type	`string`
Default	`''`

size

Controls the avatar dimensions. small is 28px, medium is 40px, large is 48px.


Type	`'small' \| 'medium' \| 'large'`
Default	`'medium'`

className

Custom CSS class appended to the root container.


Type	`string`
Default	`undefined`

children

Sub-components to render inside the avatar. Typically Image, Initials, and optionally StatusIndicator.


Type	`ReactNode`
Default	`undefined`

CometChatAvatar.Image

className

Custom CSS class appended to the <img> element.


Type	`string`
Default	`undefined`

CometChatAvatar.Initials

className

Custom CSS class appended to the initials <span> element.


Type	`string`
Default	`undefined`

CometChatAvatar.StatusIndicator

status

The presence status to display. Renders a green dot for online and a gray dot for offline.


Type	`'online' \| 'offline'`
Default	`undefined`

Required.

className

Custom CSS class appended to the status indicator <span> element.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-avatar`
Root (small)	`.cometchat-avatar[data-size="small"]`
Root (medium)	`.cometchat-avatar[data-size="medium"]`
Root (large)	`.cometchat-avatar[data-size="large"]`
Image	`.cometchat-avatar__image`
Initials	`.cometchat-avatar__initials`
Status indicator	`.cometchat-avatar__status-indicator`
Status (online)	`.cometchat-avatar__status-indicator[data-status="online"]`
Status (offline)	`.cometchat-avatar__status-indicator[data-status="offline"]`

Documentation Index

​Where It Fits

​Minimal Render

​Sub-Components

​Root

​Image

​Initials

​StatusIndicator

​Common Patterns

​Image with initials fallback

​Initials only (no image)

​Avatar without status indicator

​Size variants side by side

​CSS Architecture

​Key Selectors

​Size Modifiers

​Example: Brand-themed avatar

​Customization Matrix

​Props

​CometChatAvatar.Root

​name

​image

​size

​className

​children

​CometChatAvatar.Image

​className

​CometChatAvatar.Initials

​className

​CometChatAvatar.StatusIndicator

​status

​className

​CSS Selectors

Where It Fits

Minimal Render

Sub-Components

Root

Image

Initials

StatusIndicator

Common Patterns

Image with initials fallback

Initials only (no image)

Avatar without status indicator

Size variants side by side

CSS Architecture

Key Selectors

Size Modifiers

Example: Brand-themed avatar

Customization Matrix

Props

CometChatAvatar.Root

name

image

size

className

children

CometChatAvatar.Image

className

CometChatAvatar.Initials

className

CometChatAvatar.StatusIndicator

status

className

CSS Selectors