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

# Images 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">
  ```json theme={null}
  {
    "component": "CometChatImagesBubble",
    "package": "@cometchat/chat-uikit-react",
    "import": "import { CometChatImagesBubble } from \"@cometchat/chat-uikit-react\";",
    "description": "Batch-aware image bubble. Extracts image attachments and caption from a MediaMessage; renders adaptive grid layouts (single, 2-col, 2x2, overflow) and opens a fullscreen gallery viewer.",
    "cssRootClass": ".cometchat-images-bubble",
    "selfExtracting": true,
    "multiAttachment": true,
    "props": {
      "data": {
        "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of attachments and caption." },
        "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." },
        "textFormatters": { "type": "CometChatTextFormatter[]" },
        "batchPosition": { "type": "\"first\" | \"middle\" | \"last\" | \"single\"", "note": "Controls corner-radius styling within a batch group." },
        "placeholderImage": { "type": "string" },
        "onImageClicked": { "type": "(attachment, index) => void" },
        "className": { "type": "string" }
      }
    }
  }
  ```
</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.

This is the **multi-attachment replacement** for `CometChatImageBubble`. It renders when `enableMultipleAttachments` is `true` (the default in v7). When the prop is `false`, the legacy `CometChatImageBubble` is used instead.

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 position awareness** — adjusts corner radius based on position within a multi-message batch group
* **Placeholder loading** — shows a configurable placeholder while images load

***

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

***

## Batch Position

When multiple media messages are sent together (sharing the same `batchId`), each message receives a `batchPosition` that controls its visual grouping:

| Position | Behavior                                 |
| -------- | ---------------------------------------- |
| `first`  | Rounded top corners, flat bottom         |
| `middle` | Flat top and bottom (tight grouping)     |
| `last`   | Flat top, rounded bottom corners         |
| `single` | All corners rounded (standalone message) |

The `batchPosition` is computed automatically by the message list. You only need to pass it when using the bubble standalone outside of `CometChatMessageList`.

***

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

***

### batchPosition

Position within a multi-attachment batch group. Controls corner-radius styling.

|         |                                             |
| ------- | ------------------------------------------- |
| Type    | `"first" \| "middle" \| "last" \| "single"` |
| 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`          |

***

## Relationship to Legacy Image Bubble

|                   | `CometChatImageBubble` (legacy)    | `CometChatImagesBubble` (v7 multi-attachment) |
| ----------------- | ---------------------------------- | --------------------------------------------- |
| Used when         | `enableMultipleAttachments: false` | `enableMultipleAttachments: true` (default)   |
| Grid layouts      | No                                 | Yes (single, 2-col, 2×2, overflow)            |
| Batch grouping    | No                                 | Yes (`batchPosition` prop)                    |
| Fullscreen viewer | Single image                       | Gallery with pagination                       |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Videos Bubble" icon="video" href="/ui-kit/react/components/videos-bubble">
    Multi-attachment video bubble with grid layouts
  </Card>

  <Card title="Image Bubble (Legacy)" icon="image" href="/ui-kit/react/components/image-bubble">
    Single-attachment image bubble
  </Card>

  <Card title="Message List" icon="messages" href="/ui-kit/react/components/message-list">
    Configure multi-attachment rendering
  </Card>

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