Images Bubble

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

AI Integration Quick Reference

{
  "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" }
    }
  }
}

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

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

Videos Bubble

Multi-attachment video bubble with grid layouts

Image Bubble (Legacy)

Single-attachment image bubble

Message List

Configure multi-attachment rendering

Message Composer

Enable multi-attachment staging tray