Videos Bubble

A batch-aware bubble that renders one or more video attachments with adaptive grid layouts, poster thumbnails, and a fullscreen viewer.

AI Integration Quick Reference

{
  "component": "CometChatVideosBubble",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatVideosBubble } from \"@cometchat/chat-uikit-react\";",
  "description": "Batch-aware video bubble. Extracts video attachments and caption from a MediaMessage; renders adaptive grid layouts with poster thumbnails and opens a fullscreen viewer.",
  "cssRootClass": ".cometchat-videos-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." },
      "onVideoClicked": { "type": "(attachment, index) => void" },
      "className": { "type": "string" }
    }
  }
}

Overview

CometChatVideosBubble renders the video 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 CometChatVideoBubble. It renders when enableMultipleAttachments is true (the default in v7). When the prop is false, the legacy CometChatVideoBubble is used instead.

Key capabilities:

• Adaptive grid layouts — single video, 2-column, 2×2 grid, and overflow (+N) based on attachment count
• Poster thumbnails — auto-generated from the thumbnail-generation extension or first frame
• Duration overlay — displays video duration on each tile
• Play icon overlay — visual indicator on each video tile
• Fullscreen viewer — click any video to open in fullscreen player
• Batch position awareness — adjusts corner radius based on position within a multi-message batch group

---

Usage

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

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

---

Grid Layouts

The bubble automatically selects a layout based on the number of video attachments:

Attachment Count	Layout	Description
1	single	Full-width single video with poster
2	grid (2-col)	Side-by-side video tiles
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

Each tile shows a poster thumbnail, play icon, and duration badge.

---

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

---

onVideoClicked

Callback fired when a video tile is clicked.

Type	(attachment: CometChatVideosBubbleAttachment, index: number) => void
Default	undefined

---

className

Additional CSS class applied to the root element.

Type	string
Default	undefined

---

CSS Selectors

Target	Selector
Root	.cometchat-videos-bubble
Incoming variant	.cometchat-videos-bubble--incoming
Outgoing variant	.cometchat-videos-bubble--outgoing
Single layout	.cometchat-videos-bubble--single
Grid container	.cometchat-videos-bubble__grid
2-column grid	.cometchat-videos-bubble__grid--two-col
3-video grid	.cometchat-videos-bubble__grid--three
2×2 grid	.cometchat-videos-bubble__grid--2x2
Overflow grid	.cometchat-videos-bubble__grid--overflow
Video tile	.cometchat-videos-bubble__tile
Poster thumbnail	.cometchat-videos-bubble__thumbnail
Play icon	.cometchat-videos-bubble__play-icon
Duration badge	.cometchat-videos-bubble__duration
Placeholder	.cometchat-videos-bubble__placeholder
Overflow tile	.cometchat-videos-bubble__overflow-tile
Overflow overlay	.cometchat-videos-bubble__overflow-overlay
Overflow text (+N)	.cometchat-videos-bubble__overflow-text
Container	.cometchat-videos-bubble__container
Caption	.cometchat-videos-bubble__caption

---

Relationship to Legacy Video Bubble

	CometChatVideoBubble (legacy)	CometChatVideosBubble (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)
Poster thumbnails	Single	Per-tile with duration overlay
Fullscreen viewer	Single video	Gallery with pagination

---

Next Steps

Images Bubble

Multi-attachment image bubble with grid layouts

Audios Bubble

Multi-attachment audio bubble with player cards

Message List

Configure multi-attachment rendering

Message Composer

Enable multi-attachment staging tray