Files Bubble

A batch-aware bubble that renders one or more generic file attachments with file-type icons, metadata, download, and a collapsible list.

AI Integration Quick Reference

{
  "component": "CometChatFilesBubble",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatFilesBubble } from \"@cometchat/chat-uikit-react\";",
  "description": "Batch-aware file bubble. Extracts file attachments and caption from a MediaMessage; renders stacked file cards with type icons, name, size, extension, and download. Collapses to 3 cards with '+N more' expander.",
  "cssRootClass": ".cometchat-files-bubble",
  "selfExtracting": true,
  "multiAttachment": true,
  "props": {
    "data": {
      "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of file 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." },
      "className": { "type": "string" }
    }
  }
}

Overview

CometChatFilesBubble renders generic file attachment(s) as stacked file cards. It is self-extracting: pass the SDK message and the bubble derives the file attachments and caption itself.

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

Key capabilities:

• Stacked file cards — one card per file with type icon, filename, extension label, and file size
• File-type icons — recognizes PDF, Word, Excel, PowerPoint, text, zip, audio, video, and image extensions
• Collapsible list — shows up to 3 files initially, with a “+N more” toggle to expand
• Download button — download individual files
• Batch position awareness — adjusts corner radius based on position within a multi-message batch group
• Caption support — optional caption rendered below the cards

---

Usage

import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatFilesBubble } from "@cometchat/chat-uikit-react";

function FileMessage({ message }: { message: CometChat.MediaMessage }) {
  return <CometChatFilesBubble message={message} />;
}

---

File Card Layout

Each attachment renders as a card with:

Element	Description
File-type icon	Color-coded icon based on file extension
Filename	Display name of the file
Meta label	Extension (uppercase) and human-readable file size
Download button	Downloads the file

When a message has more than 3 file attachments, the list is initially collapsed with a toggle showing “+N more”. Clicking the toggle expands to show all files.

Supported File-Type Icons

Icon	Extensions
PDF	pdf
Word	doc, docx
Excel	xls, xlsx, csv
PowerPoint	ppt, pptx
Text	txt, rtf
Archive	zip, rar, 7z, gz
Audio	mp3, wav, m4a, aac, ogg
Video	mov, mp4, avi, mkv
Image	jpg, jpeg, png, gif, webp, bmp, svg, heic, heif
Unsupported	All other extensions

---

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

---

className

Additional CSS class applied to the root element.

Type	string
Default	undefined

---

CSS Selectors

Target	Selector
Root	.cometchat-files-bubble
Incoming variant	.cometchat-files-bubble--incoming
Outgoing variant	.cometchat-files-bubble--outgoing
Container	.cometchat-files-bubble__container
Multi-card container	.cometchat-files-bubble__container--multi
File card	.cometchat-files-bubble__card
File-type icon wrapper	.cometchat-files-bubble__card-icon
File-type icon image	.cometchat-files-bubble__card-icon-img
Card text area	.cometchat-files-bubble__card-text
Filename	.cometchat-files-bubble__card-name
Meta (extension + size)	.cometchat-files-bubble__card-meta
Expand/collapse toggle	.cometchat-files-bubble__toggle
Caption	.cometchat-files-bubble__caption

---

Relationship to Legacy File Bubble

	CometChatFileBubble (legacy)	CometChatFilesBubble (v7 multi-attachment)
Used when	enableMultipleAttachments: false	enableMultipleAttachments: true (default)
Multiple attachments	No	Yes (stacked cards with collapse)
Batch grouping	No	Yes (batchPosition prop)
File-type icons	Basic	Color-coded per extension type
Collapse/expand	No	Yes (3 visible, “+N more” toggle)

---

Next Steps

File Bubble (Legacy)

Single-attachment file bubble

Images Bubble

Multi-attachment image bubble with grid layouts

Message List

Configure multi-attachment rendering

Message Composer

Enable multi-attachment staging tray