> ## 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.

# Image Bubble

> A batch-aware bubble that renders one or more image attachments with adaptive grid layouts, a caption, and a fullscreen gallery viewer.

<Accordion title="AI Integration Quick Reference">
  | Field | Value |
  | - | - |
  | Component | `CometChatImagesBubble` |
  | Since | 7.1.0 |
  | Package | `@cometchat/chat-uikit-react` |
  | Import | `import { CometChatImagesBubble } from "@cometchat/chat-uikit-react";` |
  | CSS root class | `.cometchat-images-bubble` |
  | Primary output | `onImageClicked(attachment, index)` — opens the fullscreen gallery |
  | 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) |
</Accordion>

## Overview

`CometChatImagesBubble` renders the image attachment(s) of a media message with batch-aware styling. It is **self-extracting**: pass the SDK `message` and the bubble derives its attachments, caption, and alignment itself. The message list uses it automatically for image messages.

Key capabilities:

* **Adaptive grid layouts** — single image, 2-column, 2×2 grid, and overflow (+N) based on attachment count
* **Fullscreen gallery viewer** — click any image to open a paginated fullscreen gallery
* **Batch grouping** — rendered as one connected group when several media messages are sent together (handled by the [message list](/ui-kit/react/components/message-list#multi-attachment-batch-grouping))
* **Placeholder loading** — shows a configurable placeholder while images load

<Info>
  **Live Preview** — interact with the image bubble.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-bubbles-message-bubble-images--grid-3-images)
</Info>

<iframe src="https://storybook.cometchat.io/react/iframe.html?id=components-bubbles-message-bubble-images--grid-3-images&viewMode=story&shortcuts=false&singleStory=true" className="w-full rounded-xl" loading="lazy" style={{height: "700px", border: "1px solid #e0e0e0"}} title="CometChat Image Bubble — 3 Image Grid" allow="clipboard-write" />

***

## Usage

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

function ImageMessage({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatImagesBubble message={message} />;
}
```

***

## Grid Layouts

The bubble automatically selects a layout based on the number of image attachments:

| Attachment Count | Layout | Description |
| - | - | - |
| 1 | `single` | Full-width single image |
| 2 | `grid` (2-col) | Side-by-side images |
| 3 | `grid` (three) | 2-col grid with one spanning |
| 4 | `grid-2x2` | 2×2 even grid |
| 5+ | `overflow` | 2×2 grid with last tile showing "+N" overlay |

<iframe src="https://storybook.cometchat.io/react/iframe.html?id=components-bubbles-message-bubble-images--grid-overflow&viewMode=story&shortcuts=false&singleStory=true" className="w-full rounded-xl" loading="lazy" style={{height: "700px", border: "1px solid #e0e0e0"}} title="CometChat Image Bubble — Grid Overflow" allow="clipboard-write" />

***

## Props

### message

The image message. The bubble extracts its attachments and caption from it. **Required.**

| | |
| - | - |
| Type | `CometChat.MediaMessage` |
| Required | Yes |

***

### alignment

Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user.

| | |
| - | - |
| Type | `"left" \| "right"` |
| Default | derived |

***

### textFormatters

Text formatters applied to the caption (mentions, URLs).

| | |
| - | - |
| Type | `CometChatTextFormatter[]` |
| Default | `undefined` |

***

### placeholderImage

Custom placeholder image URL shown while the image is loading. Falls back to a default photo icon.

| | |
| - | - |
| Type | `string` |
| Default | built-in placeholder |

***

### onImageClicked

Callback fired when an image tile is clicked (in addition to opening the fullscreen viewer).

| | |
| - | - |
| Type | `(attachment: CometChatImagesBubbleAttachment, index: number) => void` |
| Default | `undefined` |

***

### className

Additional CSS class applied to the root element.

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

***

## CSS Selectors

| Target | Selector |
| - | - |
| Root | `.cometchat-images-bubble` |
| Incoming variant | `.cometchat-images-bubble--incoming` |
| Outgoing variant | `.cometchat-images-bubble--outgoing` |
| Single layout | `.cometchat-images-bubble--single` |
| Grid container | `.cometchat-images-bubble__grid` |
| 2-column grid | `.cometchat-images-bubble__grid--two-col` |
| 3-image grid | `.cometchat-images-bubble__grid--three` |
| 2×2 grid | `.cometchat-images-bubble__grid--2x2` |
| Overflow grid | `.cometchat-images-bubble__grid--overflow` |
| Image wrapper | `.cometchat-images-bubble__image-wrapper` |
| Image element | `.cometchat-images-bubble__image` |
| Placeholder | `.cometchat-images-bubble__placeholder` |
| Overflow tile | `.cometchat-images-bubble__overflow-tile` |
| Overflow overlay | `.cometchat-images-bubble__overflow-overlay` |
| Overflow text (+N) | `.cometchat-images-bubble__overflow-text` |
| Container | `.cometchat-images-bubble__container` |
| Caption | `.cometchat-images-bubble__caption` |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Video Bubble" icon="video" href="/ui-kit/react/components/video-bubble">
    Batch-aware video bubble with grid layouts
  </Card>

  <Card title="File Bubble" icon="file" href="/ui-kit/react/components/file-bubble">
    Batch-aware file bubble with stacked cards
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Multi-attachment batch grouping in the list
  </Card>

  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
    Multi-attachment staging tray
  </Card>
</CardGroup>


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