> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-react-v7-feature-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Card Bubble
> A render-only bubble that draws developer-defined card messages (category "card") with the prebuilt CometChatCardView renderer and forwards card actions to your app.
| Field | Value |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Component | `CometChatCardBubble` |
| Package | `@cometchat/chat-uikit-react` |
| Import | `import { CometChatCardBubble } from "@cometchat/chat-uikit-react";` |
| CSS root class | `.cometchat-card-bubble` |
| Primary output | `onCardAction: (message: CometChat.BaseMessage, action: CometChatCardAction) => void` — forwards the user's card action |
| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user |
| Stitching | None — self-extracting from the SDK message |
| Full props | See [Props](#props) |
## Overview
`CometChatCardBubble` renders a **card message** — a message with `category: "card"`. A card message carries a block of Card Schema JSON that is created and sent server-side (via the Platform (REST) API or the Dashboard Bubble Builder) and delivered to clients like any other message. Card messages are **receive-only**: the UI Kit renders them, it does not send them.
The bubble is **render-only**, mirroring `CometChatTextBubble`: the kit performs zero transformation. It stringifies the raw payload from `message.getCard()` and hands it to the prebuilt [`CometChatCardView`](https://www.npmjs.com/package/@cometchat/cards-react) renderer (`@cometchat/cards-react`), then forwards user actions back to your app. It never parses or mutates the card body, and never performs an action itself — your app owns all action behavior (opening URLs, navigating to chats, API calls, etc.).
In the message list, card messages are routed to this bubble automatically by the built-in **Card plugin** — no configuration is required. See [Plugins → Built-in Plugins](/ui-kit/react/plugins/overview#built-in-plugins).
### Where cards fit in the message hierarchy
`card` is a top-level message category, alongside `message`, `custom`, `action`, and `call`.
***
## Usage
Card messages render automatically inside `CometChatMessageList`. To render one directly — for example in a custom layout — pass the SDK `CardMessage` to the bubble:
```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatCardBubble } from "@cometchat/chat-uikit-react";
function CardMessageItem({ message }: { message: CometChat.CardMessage }) {
return ;
}
```
To receive card actions without going through the [event bus](/ui-kit/react/event-system), pass an `onCardAction` callback:
```tsx theme={null}
import { CometChat } from "@cometchat/chat-sdk-javascript";
import {
CometChatCardBubble,
type CometChatCardAction,
} from "@cometchat/chat-uikit-react";
function CardMessageItem({ message }: { message: CometChat.CardMessage }) {
const handleAction = (
msg: CometChat.BaseMessage,
action: CometChatCardAction
) => {
// Your app owns the behavior — open a URL, start a call, call an API, etc.
console.log("Card action", action, "on message", msg.getId());
};
return ;
}
```
***
## Props
### message
The developer card message (`category: "card"`). The bubble reads the raw card payload from `message.getCard()`. **Required.**
| | |
| -------- | ----------------------- |
| Type | `CometChat.CardMessage` |
| Required | Yes |
***
### themeMode
Theme mode forwarded to the `CometChatCardView` renderer.
| | |
| ------- | ------------------------ |
| Type | `CometChatCardThemeMode` |
| Default | `"auto"` |
***
### themeOverride
Optional theme overrides forwarded to the renderer.
| | |
| ------- | ---------------------------- |
| Type | `CometChatCardThemeOverride` |
| Default | `undefined` |
***
### onCardAction
Direct callback for card actions. Fired **in addition to** the `ui:card/action` UI event, so an app embedding the bubble directly can receive actions without subscribing to the event bus. Receives the message and the clicked action.
| | |
| ------- | ----------------------------------------------------------------------- |
| Type | `(message: CometChat.BaseMessage, action: CometChatCardAction) => void` |
| Default | `undefined` |
***
## Card Actions
When a user clicks an action inside a card (a button, link, etc.), the bubble forwards the raw action to your app through **two** channels — it never handles the action itself:
1. The optional [`onCardAction`](#oncardaction) prop, when provided.
2. The [`ui:card/action`](/ui-kit/react/event-system#card-actions) UI event, published on the event bus with the `message` and the clicked `action`. This is the only channel that can reach a card rendered by the kit (e.g. a nested agent card) where no prop is reachable.
Subscribe to the event anywhere in your app:
```tsx theme={null}
import { useCometChatEvents } from "@cometchat/chat-uikit-react";
function CardActionListener() {
useCometChatEvents((event) => {
if (event.type === "ui:card/action") {
// event.message, event.action
console.log("Card action clicked:", event.action);
}
});
return null;
}
```
***
## Fallback
When `message.getCard()` is absent or empty, the renderer is **not** invoked. Instead the bubble renders a plain-text fallback, resolving the first available of:
1. `message.getFallbackText()`
2. `message.getText()`
3. The localized `"Card Message"` string
***
## CSS Selectors
| Target | Selector |
| ------------- | ---------------------------------- |
| Root | `.cometchat-card-bubble` |
| Text fallback | `.cometchat-card-bubble__fallback` |
The card body itself is styled by the `CometChatCardView` renderer; use `themeMode` / `themeOverride` to theme it.
***
## Next Steps
How the Card plugin routes card messages to this bubble
Subscribe to the ui:card/action event
The wrapper that hosts bubble content
Customize colors, fonts, and spacing