> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.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">
  ```json theme={null}
  {
    "component": "CometChatIncomingCall",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatIncomingCall } from \"@cometchat/chat-uikit-react\";",
    "description": "Displays an incoming call notification with caller info, accept/decline buttons, and transitions to the ongoing call screen.",
    "cssRootClass": ".cometchat-incoming-call",
    "primaryOutput": {
      "prop": "onAccept",
      "type": "(call: CometChat.Call) => void"
    },
    "props": {
      "callbacks": {
        "onAccept": "(call: CometChat.Call) => void",
        "onDecline": "(call: CometChat.Call) => void",
        "onCallEnded": "() => void",
        "onError": "((error: CometChat.CometChatException) => void) | null"
      },
      "sound": {
        "disableSoundForCalls": { "type": "boolean", "default": false },
        "customSoundForCalls": { "type": "string", "default": "built-in" }
      },
      "configuration": {
        "callSettingsBuilder": {
          "type": "(call: CometChat.Call) => any",
          "default": "undefined",
          "note": "Custom call settings for the ongoing call session after accepting"
        }
      },
      "viewSlots": {
        "itemView": "(call: CometChat.Call) => ReactNode",
        "leadingView": "(call: CometChat.Call) => ReactNode",
        "titleView": "(call: CometChat.Call) => ReactNode",
        "subtitleView": "(call: CometChat.Call) => ReactNode",
        "trailingView": "(call: CometChat.Call) => ReactNode"
      }
    },
    "events": [
      {
        "name": "ui:call/rejected",
        "payload": "{ call }",
        "description": "Call declined by user"
      },
      {
        "name": "ui:call/ended",
        "payload": "{}",
        "description": "Ongoing call ended"
      }
    ],
    "sdkListeners": [
      "onIncomingCallReceived",
      "onIncomingCallCancelled",
      "onOutgoingCallAccepted",
      "onOutgoingCallRejected"
    ],
    "types": {
      "CometChatDateFormatConfig": {
        "today": "string | undefined",
        "yesterday": "string | undefined",
        "lastWeek": "string | undefined",
        "otherDays": "string | undefined"
      }
    }
  }
  ```
</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-rn-guide-message-privately/FGBCGWXGo5d9bVxR/images/c3e4060d-incoming_call_leading_view_custom_web_screens-75333fe402b7588c590288cd6f825a99.png?fit=max&auto=format&n=FGBCGWXGo5d9bVxR&q=85&s=a5bc478718666a8ea75fce678f8c2381" 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-rn-guide-message-privately/ubfBSdV1t6rmjxeA/images/8d3bfa9b-incoming_call_title_view_custom_web_screens-67b55f5b6fc1ede3f9f55d840ebaa290.png?fit=max&auto=format&n=ubfBSdV1t6rmjxeA&q=85&s=1508c612f2ecefc88b4086d582b25f76" 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-rn-guide-message-privately/k0f_g7UwNe_JINeP/images/40f39b71-incoming_call_item_view_custom_web_screens-f8cd3984730f17f99313f1d988439d41.png?fit=max&auto=format&n=k0f_g7UwNe_JINeP&q=85&s=4254802dc085f727d90aadc4546da9bb" 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>