Call Buttons - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatCallButtons",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatCallButtons } from \"@cometchat/chat-uikit-react\";",
  "description": "Voice and video call initiation buttons for user or group conversations. Manages the full call lifecycle (outgoing + ongoing) internally.",
  "cssRootClass": ".cometchat-call-buttons",
  "primaryOutput": {
    "description": "Initiates calls via the SDK and renders the outgoing/ongoing call screens"
  },
  "props": {
    "data": {
      "user": {
        "type": "CometChat.User",
        "default": "undefined",
        "note": "Pass either user or group, not both"
      },
      "group": {
        "type": "CometChat.Group",
        "default": "undefined",
        "note": "Pass either user or group, not both"
      }
    },
    "callbacks": {
      "onVoiceCallClick": "(entity: CometChat.User | CometChat.Group) => void",
      "onVideoCallClick": "(entity: CometChat.User | CometChat.Group) => void",
      "onCallEnded": "() => void",
      "onError": "((error: CometChat.CometChatException) => void) | null"
    },
    "visibility": {
      "hideVoiceCallButton": { "type": "boolean", "default": false },
      "hideVideoCallButton": { "type": "boolean", "default": false }
    },
    "viewSlots": {
      "voiceCallButtonView": "ReactNode",
      "videoCallButtonView": "ReactNode"
    },
    "configuration": {
      "callSettingsBuilder": "(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => CallSettingsBuilder",
      "className": "string"
    }
  },
  "eventsEmitted": [
    {
      "name": "ui:call/outgoing",
      "payload": "{ call }",
      "description": "User initiates a 1-on-1 voice/video call"
    },
    {
      "name": "ui:message/sent",
      "payload": "{ message, status }",
      "description": "Group call meeting message sent"
    }
  ],
  "eventsReceived": [
    {
      "name": "ui:call/rejected",
      "payload": "{ call }",
      "description": "Re-enables call buttons after the call is rejected"
    },
    {
      "name": "ui:call/ended",
      "payload": "{}",
      "description": "Resets all call state when the call ends"
    }
  ],
  "sdkListeners": [
    "onIncomingCallReceived",
    "onIncomingCallCancelled",
    "onOutgoingCallAccepted",
    "onOutgoingCallRejected"
  ],
  "compositionExample": {
    "description": "Standalone call buttons or embedded in the MessageHeader auxiliary view",
    "components": ["CometChatCallButtons", "CometChatOutgoingCall", "CometChatOngoingCall"],
    "flow": "user/group prop -> click button -> SDK initiateCall -> CometChatOutgoingCall overlay -> onOutgoingCallAccepted -> CometChatOngoingCall"
  }
}

Where It Fits

CometChatCallButtons renders voice and video call buttons. Pass a user for 1-on-1 calls or a group for group calls. It is typically embedded in CometChatMessageHeader’s auxiliary view or used standalone. The component is self-contained: clicking a button initiates the call, renders CometChatOutgoingCall internally while waiting for an answer, transitions to CometChatOngoingCall on acceptance, and cleans up when the call ends.

Live Preview — interact with the call buttons component.Open in Storybook ↗

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsDemo() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return chatUser ? <CometChatCallButtons user={chatUser} /> : null;
}

export default CallButtonsDemo;

Minimal Render

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

function CallButtonsMinimal({ chatUser }: { chatUser: CometChat.User }) {
  return <CometChatCallButtons user={chatUser} />;
}

Root CSS class: .cometchat-call-buttons

Actions and Events

Callback Props

onVoiceCallClick

Overrides the default voice call initiation behavior. When set, clicking the voice button invokes this callback (with the active user or group entity) instead of initiating a call via the SDK.

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsVoiceOverride() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return (
    <CometChatCallButtons
      user={chatUser}
      onVoiceCallClick={(entity) => {
        console.log("Custom voice call logic for", entity.getName());
      }}
    />
  );
}

onVideoCallClick

Overrides the default video call initiation behavior.

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function CallButtonsVideoOverride() {
  const [chatUser, setChatUser] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("uid").then((user) => setChatUser(user));
  }, []);

  return (
    <CometChatCallButtons
      user={chatUser}
      onVideoCallClick={(entity) => {
        console.log("Custom video call logic for", entity.getName());
      }}
    />
  );
}

onCallEnded

Fires after an ongoing call session ends and the component has reset its internal state.

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

function CallButtonsWithEndHandler({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      onCallEnded={() => {
        console.log("Call ended");
      }}
    />
  );
}

onError

Fires on internal errors during call initiation.

import { CometChatCallButtons } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function CallButtonsWithError({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      onError={(error: CometChat.CometChatException) => {
        console.error("CallButtons error:", error);
      }}
    />
  );
}

Events Emitted

UI events this component publishes during the call lifecycle:

Event	Payload	Fires when
`ui:call/outgoing`	`{ call }`	A 1-on-1 voice/video call is initiated
`ui:message/sent`	`{ message, status }`	A group call meeting message is sent

Events Received

UI events this component subscribes to (published by other components):

Event	Payload	Behavior
`ui:call/rejected`	`{ call }`	Clears the active call and re-enables the buttons
`ui:call/ended`	`{}`	Clears the active call and resets all call state

SDK Listeners (Real-Time, Automatic)

The component attaches SDK call listeners internally:

SDK Listener	Internal behavior
`onIncomingCallReceived`	Disables call buttons to prevent concurrent calls
`onIncomingCallCancelled`	Re-enables call buttons
`onOutgoingCallAccepted`	Transitions to the ongoing call screen
`onOutgoingCallRejected`	Clears the active call and resets state

Call Settings

Customize the calling experience via callSettingsBuilder. The builder is forwarded to the internal CometChatOngoingCall session.

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons, CometChatUIKitCalls } from "@cometchat/chat-uikit-react";

function CallButtonsCustomSettings({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      callSettingsBuilder={(isAudioOnlyCall, user, group) =>
        new CometChatUIKitCalls.CallSettingsBuilder()
          .enableDefaultLayout(true)
          .setIsAudioOnlyCall(isAudioOnlyCall)
      }
    />
  );
}

Customization

Custom Button Views

Use voiceCallButtonView and videoCallButtonView to replace the default buttons while keeping the component’s call lifecycle behavior intact.

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

function CallButtonsCustomViews({ chatUser }: { chatUser: CometChat.User }) {
  return (
    <CometChatCallButtons
      user={chatUser}
      voiceCallButtonView={<button className="my-voice-btn">Voice</button>}
      videoCallButtonView={<button className="my-video-btn">Video</button>}
    />
  );
}

Slot	Type	Replaces
`voiceCallButtonView`	`ReactNode`	Default voice call button
`videoCallButtonView`	`ReactNode`	Default video call button

Common Patterns

Voice-only call button

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

function VoiceOnlyCallButtons({ chatUser }: { chatUser: CometChat.User }) {
  return <CometChatCallButtons user={chatUser} hideVideoCallButton={true} />;
}

Group call buttons

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCallButtons } from "@cometchat/chat-uikit-react";

function GroupCallButtons() {
  const [group, setGroup] = useState<CometChat.Group>();

  useEffect(() => {
    CometChat.getGroup("guid").then((g) => setGroup(g));
  }, []);

  return group ? <CometChatCallButtons group={group} /> : null;
}

CSS Architecture

The component uses CSS custom properties (design tokens) provided by the UI Kit. The cascade:

Global tokens set on the .cometchat root wrapper.
Component CSS (.cometchat-call-buttons) consumes these tokens via var().
Overrides target .cometchat-call-buttons descendant selectors.

Key Selectors

Target	Selector
Root	`.cometchat-call-buttons`
Button element	`.cometchat-call-buttons__button`
Button icon	`.cometchat-call-buttons__button-icon`
Voice button icon	`.cometchat-call-buttons__button-icon--voice`
Video button icon	`.cometchat-call-buttons__button-icon--video`

Example: Themed call buttons

.cometchat-call-buttons {
  display: flex;
  padding: 8px 16px;
  justify-content: center;
  align-items: center;
  gap: 4px;
  background: #fff;
}

.cometchat-call-buttons__button {
  border-radius: 8px;
  border: 1px solid #e8e8e8;
  background: #edeafa;
}

.cometchat-call-buttons__button-icon--voice,
.cometchat-call-buttons__button-icon--video {
  background-color: #6852d6;
}

Customization Matrix

What to change	Where	Property/API	Example
Override call initiation	Component props	`onVoiceCallClick` / `onVideoCallClick`	`onVoiceCallClick={(entity) => customCall(entity)}`
Hide a call button	Component props	`hideVoiceCallButton` / `hideVideoCallButton`	`hideVideoCallButton={true}`
Replace a button view	Component props	`voiceCallButtonView` / `videoCallButtonView`	`voiceCallButtonView={<CustomButton />}`
Customize call settings	Component props	`callSettingsBuilder`	`callSettingsBuilder={(audio) => builder}`
Change colors, fonts, spacing	Global CSS	Target `.cometchat-call-buttons` class	`.cometchat-call-buttons__button-icon { background: red; }`

Props

All props are optional. Sorted alphabetically.

callSettingsBuilder

Builder function for customizing the ongoing call settings.


Type	`(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => CallSettingsBuilder`
Default	`undefined`

className

Additional CSS class name applied to the root container.


Type	`string`
Default	`undefined`

group

The group for group call buttons. Pass either user or group, not both.


Type	`CometChat.Group`
Default	`undefined`

hideVideoCallButton

Hides the video call button.


Type	`boolean`
Default	`false`

hideVoiceCallButton

Hides the voice call button.


Type	`boolean`
Default	`false`

onCallEnded

Callback fired after an ongoing call ends and the component resets its state.


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

onError

Callback fired when the component encounters an error.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`undefined`

onVideoCallClick

Overrides the default video call initiation. Receives the active user or group entity.


Type	`(entity: CometChat.User \| CometChat.Group) => void`
Default	`undefined`

onVoiceCallClick

Overrides the default voice call initiation. Receives the active user or group entity.


Type	`(entity: CometChat.User \| CometChat.Group) => void`
Default	`undefined`

user

The user for 1-on-1 call buttons. Pass either user or group, not both.


Type	`CometChat.User`
Default	`undefined`

videoCallButtonView

Custom view that replaces the default video call button.


Type	`ReactNode`
Default	`undefined`

voiceCallButtonView

Custom view that replaces the default voice call button.


Type	`ReactNode`
Default	`undefined`

CSS Selectors

Target	Selector
Root	`.cometchat-call-buttons`
Button element	`.cometchat-call-buttons__button`
Button icon	`.cometchat-call-buttons__button-icon`
Voice button icon	`.cometchat-call-buttons__button-icon--voice`
Video button icon	`.cometchat-call-buttons__button-icon--video`

Next Steps

Outgoing Call

Customize the outgoing call screen shown while waiting for an answer

Incoming Call

Handle incoming call notifications with accept/decline actions

Call Logs

Browse call history and re-initiate calls

Theming

Customize colors, fonts, and spacing

​Where It Fits

​Minimal Render

​Actions and Events

​Callback Props

​onVoiceCallClick

​onVideoCallClick

​onCallEnded

​onError

​Events Emitted

​Events Received

​SDK Listeners (Real-Time, Automatic)

​Call Settings

​Customization

​Custom Button Views

​Common Patterns

​Voice-only call button

​Group call buttons

​CSS Architecture

​Key Selectors

​Example: Themed call buttons

​Customization Matrix

​Props

​callSettingsBuilder

​className

​group

​hideVideoCallButton

​hideVoiceCallButton

​onCallEnded

​onError

​onVideoCallClick

​onVoiceCallClick

​user

​videoCallButtonView

​voiceCallButtonView

​CSS Selectors

​Next Steps

Outgoing Call

Incoming Call

Call Logs

Theming

Where It Fits

Minimal Render

Actions and Events

Callback Props

onVoiceCallClick

onVideoCallClick

onCallEnded

onError

Events Emitted

Events Received

SDK Listeners (Real-Time, Automatic)

Call Settings

Customization

Custom Button Views

Common Patterns

Voice-only call button

Group call buttons

CSS Architecture

Key Selectors

Example: Themed call buttons

Customization Matrix

Props

callSettingsBuilder

className

group

hideVideoCallButton

hideVoiceCallButton

onCallEnded

onError

onVideoCallClick

onVoiceCallClick

user

videoCallButtonView

voiceCallButtonView

CSS Selectors

Next Steps