Files Bubble - CometChat Docs

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. The message list always renders it for file messages in v7. The legacy CometChatFileBubble remains available as a deprecated standalone component you can use directly, but the list no longer uses it. 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

Live Preview — interact with the files bubble.Open in Storybook ↗

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	Standalone use only (deprecated)	Always, for file messages in the list
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

​Overview

​Usage

​File Card Layout

​Supported File-Type Icons

​Batch Position

​Props

​message

​alignment

​textFormatters

​batchPosition

​className

​CSS Selectors

​Relationship to Legacy File Bubble

​Next Steps

File Bubble (Legacy)

Images Bubble

Message List

Message Composer

Overview

Usage

File Card Layout

Supported File-Type Icons

Batch Position

Props

message

alignment

textFormatters

batchPosition

className

CSS Selectors

Relationship to Legacy File Bubble

Next Steps