> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Incoming Call

> Displays an incoming call notification with caller info, accept/decline buttons, and transitions to the ongoing call screen.

<Accordion title="AI Integration Quick Reference">
  | Field | Value |
  | - | - |
  | Component | `CometChatIncomingCall` |
  | Package | `@cometchat/chat-uikit-react` |
  | Import | `import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";` |
  | CSS root class | `.cometchat-incoming-call` |
  | Primary output | `onAccept: (call: CometChat.Call) => void` — fires when the call is accepted |
  | Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user |
  | Stitching | Mount at the app root to catch incoming calls; wire `onAccept` / `onDecline` |
  | Events emitted | `ui:call/rejected`, `ui:call/ended` — see [Event System](/ui-kit/react/event-system) |
  | SDK listeners (automatic) | Incoming and outgoing call lifecycle — handled internally |
  | Full props | See [Props](#props) |
</Accordion>

## Overview

`CometChatIncomingCall` is a full-screen notification component that automatically listens for incoming calls via the CometChat SDK `CallListener`. When an incoming call is detected, it displays the caller's avatar, name, and call type (Voice/Video) with accept and decline buttons.

<Info>
  **Live Preview** — interact with the default incoming call screen.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-calls-cometchat-incoming-call--default)
</Info>

<iframe src="https://storybook.cometchat.io/react/iframe.html?id=components-calls-cometchat-incoming-call--default&viewMode=story&shortcuts=false&singleStory=true" className="w-full rounded-xl" loading="lazy" style={{height: "200px", border: "1px solid #e0e0e0"}} title="CometChat Incoming Call — Default" allow="clipboard-write" />

The component handles:

* Automatic detection of incoming calls via SDK `CallListener`
* Caller avatar, name, and call type display (Voice/Video)
* Accept button — transitions to `CometChatOngoingCall` internally
* Decline button — rejects the call via SDK
* Incoming call sound playback (looping while notification is visible)
* Self-managed visibility (renders nothing when no incoming call is active)

> **Placement:** Render `CometChatIncomingCall` at your app's root level. It manages its own visibility internally and only appears when an incoming call is detected.

> **Note:** Call **initiation** buttons are provided by the standalone [`CometChatCallButtons`](/ui-kit/react/components/call-buttons) component (also rendered automatically inside `CometChatMessageHeader`). `CometChatIncomingCall` is separate — it handles the incoming call notification flow.

***

## Usage

### Flat API

```tsx theme={null}
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function App() {
  return (
    <div>
      {/* Your app content */}
      <CometChatIncomingCall
        onAccept={(call) => {
          console.log("Call accepted:", call.getSessionId());
        }}
        onDecline={(call) => {
          console.log("Call declined:", call.getSessionId());
        }}
        onCallEnded={() => {
          console.log("Call ended");
        }}
      />
    </div>
  );
}
```

### Full Layout Example

```tsx theme={null}
import {
  CometChatConversations,
  CometChatMessageHeader,
  CometChatMessageList,
  CometChatMessageComposer,
  CometChatIncomingCall,
} from "@cometchat/chat-uikit-react";

function ChatApp() {
  return (
    <div style={{ display: "flex", height: "100vh" }}>
      <div style={{ width: 360 }}>
        <CometChatConversations onItemClick={handleConversationClick} />
      </div>
      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <CometChatMessageHeader user={user} group={group} />
        <CometChatMessageList user={user} group={group} />
        <CometChatMessageComposer user={user} group={group} />
      </div>

      {/* Render at root level — manages its own visibility */}
      <CometChatIncomingCall />
    </div>
  );
}
```

***

## Actions and Events

### Callback Props

| Prop | Signature | Fires when |
| - | - | - |
| `onAccept` | `(call: CometChat.Call) => void` | User clicks the accept button |
| `onDecline` | `(call: CometChat.Call) => void` | User clicks the decline button |
| `onCallEnded` | `() => void` | Ongoing call session ends |
| `onError` | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs |

### Events Emitted

UI events this component publishes:

| Event | Payload | Fires when |
| - | - | - |
| `ui:call/rejected` | `{ call }` | Call declined by user |
| `ui:call/ended` | `{}` | Ongoing call ended |

### Events Received

This component does not subscribe to any UI events from other components.

### SDK Listeners (Automatic)

These SDK `CallListener` callbacks are attached internally. The component updates its state automatically:

* `onIncomingCallReceived` — shows the incoming call notification
* `onIncomingCallCancelled` — hides the notification (caller cancelled)
* `onOutgoingCallAccepted` — transitions to ongoing call screen
* `onOutgoingCallRejected` — hides the notification (call rejected elsewhere)

***

## Customization

### View Props

Use view props to replace sections of the default UI while keeping the component's behavior intact:

```tsx theme={null}
<CometChatIncomingCall
  leadingView={(call) => <MyCustomAvatar call={call} />}
  titleView={(call) => <span>{call.getSender().getName()}</span>}
  subtitleView={(call) => <span>Incoming {call.getType()} call</span>}
/>
```

| Slot | Signature | Replaces |
| - | - | - |
| `itemView` | `(call: CometChat.Call) => ReactNode` | Entire call notification card |
| `leadingView` | `(call: CometChat.Call) => ReactNode` | Avatar section |
| `titleView` | `(call: CometChat.Call) => ReactNode` | Caller name |
| `subtitleView` | `(call: CometChat.Call) => ReactNode` | Call type label |
| `trailingView` | `(call: CometChat.Call) => ReactNode` | Trailing section |

#### leadingView

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/egNZF-iXldTS9vDi/images/c3e4060d-incoming_call_leading_view_custom_web_screens-75333fe402b7588c590288cd6f825a99.png?fit=max&auto=format&n=egNZF-iXldTS9vDi&q=85&s=0abfeb927c3d7522f823791db7d91872" width="1282" height="802" data-path="images/c3e4060d-incoming_call_leading_view_custom_web_screens-75333fe402b7588c590288cd6f825a99.png" />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAvatar, CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function CustomLeadingIncoming() {
  return (
    <CometChatIncomingCall
      leadingView={(call: CometChat.Call) => (
        <CometChatAvatar.Root
          name={call.getCallInitiator()?.getName()}
          image={call.getCallInitiator()?.getAvatar()}
        >
          <CometChatAvatar.Image />
          <CometChatAvatar.Initials />
        </CometChatAvatar.Root>
      )}
    />
  );
}
```

#### titleView

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/-nSFFcS2LLIkMyn9/images/8d3bfa9b-incoming_call_title_view_custom_web_screens-67b55f5b6fc1ede3f9f55d840ebaa290.png?fit=max&auto=format&n=-nSFFcS2LLIkMyn9&q=85&s=e6cc379b5ccfb80a08cbbdf23fa80116" width="1282" height="802" data-path="images/8d3bfa9b-incoming_call_title_view_custom_web_screens-67b55f5b6fc1ede3f9f55d840ebaa290.png" />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function CustomTitleIncoming() {
  return (
    <CometChatIncomingCall
      titleView={(call: CometChat.Call) => (
        <div>{call.getCallInitiator()?.getName()}</div>
      )}
    />
  );
}
```

#### itemView

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-llms-scoped-indexes/cTCXebw8IhR7IiJw/images/40f39b71-incoming_call_item_view_custom_web_screens-f8cd3984730f17f99313f1d988439d41.png?fit=max&auto=format&n=cTCXebw8IhR7IiJw&q=85&s=e9ac077e31f2b80fae667a389de78cc4" width="1282" height="802" data-path="images/40f39b71-incoming_call_item_view_custom_web_screens-f8cd3984730f17f99313f1d988439d41.png" />
</Frame>

```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAvatar, CometChatIncomingCall } from "@cometchat/chat-uikit-react";

function CustomItemViewIncoming() {
  return (
    <CometChatIncomingCall
      itemView={(call: CometChat.Call) => (
        <div className="incoming-call__item">
          <CometChatAvatar.Root
            name={call.getCallInitiator()?.getName()}
            image={call.getCallInitiator()?.getAvatar()}
          >
            <CometChatAvatar.Image />
            <CometChatAvatar.Initials />
          </CometChatAvatar.Root>
          <div>{call.getCallInitiator()?.getName()}</div>
        </div>
      )}
    />
  );
}
```

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-incoming-call {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-incoming-call__button-accept {
  background: var(--cometchat-success-color);
}

.cometchat-incoming-call__button-decline {
  background: var(--cometchat-error-color);
}
```

***

## Props

All props are optional.

***

### onAccept

Custom accept handler. When provided, overrides the default `CometChat.acceptCall` behavior.

| | |
| - | - |
| Type | `(call: CometChat.Call) => void` |
| Default | `undefined` |

***

### onDecline

Custom decline handler. When provided, overrides the default `CometChat.rejectCall` behavior.

| | |
| - | - |
| Type | `(call: CometChat.Call) => void` |
| Default | `undefined` |

***

### onCallEnded

Callback when the ongoing call session ends and the call screen should close.

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

***

### disableSoundForCalls

Disable the incoming call ringtone sound.

| | |
| - | - |
| Type | `boolean` |
| Default | `false` |

***

### customSoundForCalls

Custom sound URL to play for incoming calls (replaces the built-in ringtone).

| | |
| - | - |
| Type | `string` |
| Default | Built-in ringtone |

***

### callSettingsBuilder

Custom call settings builder for the ongoing call session after accepting. If not provided, the component uses default settings.

| | |
| - | - |
| Type | `(call: CometChat.Call) => any` |
| Default | `undefined` |

```tsx theme={null}
<CometChatIncomingCall
  callSettingsBuilder={(call) => {
    return new CometChat.CallSettingsBuilder()
      .enableDefaultLayout(true)
      .setIsAudioOnlyCall(call.getType() === "audio")
      .build();
  }}
/>
```

***

### onError

Callback when an SDK error occurs.

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

***

### itemView

Custom renderer for the entire incoming call notification card.

| | |
| - | - |
| Type | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined` |

***

### leadingView

Custom renderer for the avatar section.

| | |
| - | - |
| Type | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined` |

***

### titleView

Custom renderer for the caller name.

| | |
| - | - |
| Type | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined` |

***

### subtitleView

Custom renderer for the call type label (Voice/Video).

| | |
| - | - |
| Type | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined` |

***

### trailingView

Custom renderer for the trailing section.

| | |
| - | - |
| Type | `(call: CometChat.Call) => ReactNode` |
| Default | `undefined` |

***

### className

Additional CSS class name applied to the root element.

| | |
| - | - |
| Type | `string` |
| Default | `undefined` |

***

## CSS Selectors

| Target | Selector |
| - | - |
| Root container | `.cometchat-incoming-call` |
| Info section | `.cometchat-incoming-call__info` |
| Avatar | `.cometchat-incoming-call__avatar` |
| Details container | `.cometchat-incoming-call__details` |
| Title | `.cometchat-incoming-call__title` |
| Subtitle | `.cometchat-incoming-call__subtitle` |
| Trailing section | `.cometchat-incoming-call__trailing` |
| Button group | `.cometchat-incoming-call__button-group` |
| Accept button | `.cometchat-incoming-call__button-accept` |
| Decline button | `.cometchat-incoming-call__button-decline` |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Outgoing Call" icon="phone-arrow-up-right" href="/ui-kit/react/components/outgoing-call">
    Display the outgoing call screen while waiting for the receiver to answer
  </Card>

  <Card title="Call Logs" icon="clock-rotate-left" href="/ui-kit/react/components/call-logs">
    Browse call history and re-initiate calls
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and spacing
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.