Image Bubble - CometChat Docs

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

​Overview

​Usage

​Grid Layouts

​Props

​message

​alignment

​textFormatters

​placeholderImage

​onImageClicked

​className

​CSS Selectors

​Next Steps

Video Bubble

File Bubble

Message List

Message Composer

Overview

Usage

Grid Layouts

Props

message

alignment

textFormatters

placeholderImage

onImageClicked

className

CSS Selectors

Next Steps