Image 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[]" },
      "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. 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)
• Placeholder loading — shows a configurable placeholder while images load

Live Preview — interact with the image bubble.

Open in Storybook ↗

---

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

---

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

Video Bubble

Batch-aware video bubble with grid layouts

File Bubble

Batch-aware file bubble with stacked cards

Message List

Multi-attachment batch grouping in the list

Message Composer

Multi-attachment staging tray