cometchat · PrajwalDhuleCC · Jul 9, 2026
diff --git a/docs.json b/docs.json
@@ -531,9 +531,14 @@
                                   "ui-kit/react/components/message-bubble",
                                   "ui-kit/react/components/text-bubble",
                                   "ui-kit/react/components/image-bubble",
+                                  "ui-kit/react/components/images-bubble",
                                   "ui-kit/react/components/video-bubble",
+                                  "ui-kit/react/components/videos-bubble",
                                   "ui-kit/react/components/audio-bubble",
+                                  "ui-kit/react/components/audios-bubble",
+                                  "ui-kit/react/components/voice-note-bubble",
                                   "ui-kit/react/components/file-bubble",
+                                  "ui-kit/react/components/files-bubble",
                                   "ui-kit/react/components/poll-bubble",
                                   "ui-kit/react/components/sticker-bubble",
                                   "ui-kit/react/components/collaborative-document-bubble",

@@ -0,0 +1,206 @@
+---
+title: "Audios Bubble"
+sidebarTitle: "Audios Bubble"
+description: "A batch-aware bubble that renders one or more audio file attachments with inline playback cards, seek controls, and download."
+---
+
+<Accordion title="AI Integration Quick Reference">
+```json
+{
+  "component": "CometChatAudiosBubble",
+  "package": "@cometchat/chat-uikit-react",
+  "import": "import { CometChatAudiosBubble } from \"@cometchat/chat-uikit-react\";",
+  "description": "Batch-aware audio bubble for attached audio files. Renders stacked audio cards with play/pause, seekable slider, duration, and download. NOT used for voice notes — see CometChatVoiceNoteBubble.",
+  "cssRootClass": ".cometchat-audios-bubble",
+  "selfExtracting": true,
+  "multiAttachment": true,
+  "props": {
+    "data": {
+      "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of audio 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" }
+    }
+  }
+}
+```
+</Accordion>
+
+## Overview
+
+`CometChatAudiosBubble` renders audio file attachment(s) as stacked playback cards. It is **self-extracting**: pass the SDK `message` and the bubble derives the audio attachments and caption itself.
+
+This is the **multi-attachment replacement** for `CometChatAudioBubble` when dealing with attached audio files. It renders when `enableMultipleAttachments` is `true` (the default in v7) and the audio message does **not** have `audioType: "voice_note"` in its metadata. When the prop is `false`, the legacy `CometChatAudioBubble` is used for all audio.
+
+<Note>
+**Audio files vs Voice notes.** The audio plugin routes messages by the `audioType` metadata key:
+- **No `audioType`** (attached audio files) → `CometChatAudiosBubble` (this component)
+- **`audioType: "voice_note"`** (recorded via voice recorder) → [CometChatVoiceNoteBubble](/ui-kit/react/components/voice-note-bubble)
+
+This distinction is automatic — you don't need to configure it.
+</Note>
+
+Key capabilities:
+
+- **Stacked audio cards** — one card per audio attachment with filename, play/pause, seekable slider, elapsed/total time
+- **Inline playback** — plays audio directly in the bubble without a fullscreen viewer
+- **Download button** — download individual audio files
+- **Batch position awareness** — adjusts corner radius based on position within a multi-message batch group
+- **Caption support** — optional caption rendered below the cards
+
+{/* TODO: Add screenshot showing audios bubble with multiple audio cards */}
+
+---
+
+## Usage
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+import { CometChatAudiosBubble } from "@cometchat/chat-uikit-react";
+
+function AudioFilesMessage({ message }: { message: CometChat.MediaMessage }) {
+  return <CometChatAudiosBubble message={message} />;
+}
+```
+
+---
+
+## Audio Card Layout
+
+Each attachment renders as a card with:
+
+| Element | Description |
+| --- | --- |
+| Play/Pause button | Toggles playback for that audio file |
+| Filename | Display name of the audio file |
+| Seek slider | Seekable progress bar showing current position |
+| Time display | `currentTime / totalDuration` in `m:ss` format |
+| Download button | Downloads the audio file |
+
+When a message has multiple audio attachments, cards stack vertically.
+
+{/* TODO: Add Storybook embed showing single and multi-audio card layouts */}
+
+---
+
+## 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 audio 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-audios-bubble` |
+| Incoming variant | `.cometchat-audios-bubble--incoming` |
+| Outgoing variant | `.cometchat-audios-bubble--outgoing` |
+| Container | `.cometchat-audios-bubble__container` |
+| Multi-card container | `.cometchat-audios-bubble__container--multi` |
+| Audio card | `.cometchat-audios-bubble__card` |
+| Play button | `.cometchat-audios-bubble__play-btn` |
+| Play button icon | `.cometchat-audios-bubble__play-btn-icon` |
+| Card body (name + slider + time) | `.cometchat-audios-bubble__body` |
+| Filename | `.cometchat-audios-bubble__name` |
+| Seek slider | `.cometchat-audios-bubble__slider` |
+| Time display | `.cometchat-audios-bubble__time` |
+| Expand/collapse toggle | `.cometchat-audios-bubble__toggle` |
+| Caption | `.cometchat-audios-bubble__caption` |
+
+---
+
+## Relationship to Legacy Audio Bubble
+
+| | `CometChatAudioBubble` (legacy) | `CometChatAudiosBubble` (v7 multi-attachment) |
+| --- | --- | --- |
+| Used when | `enableMultipleAttachments: false` | `enableMultipleAttachments: true` + no `audioType: "voice_note"` |
+| Multiple attachments | No | Yes (stacked cards) |
+| Batch grouping | No | Yes (`batchPosition` prop) |
+| Audio routing | All audio messages | Only attached audio files (not voice notes) |
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Voice Note Bubble" icon="microphone" href="/ui-kit/react/components/voice-note-bubble">
+    Waveform bubble for recorded voice notes
+  </Card>
+  <Card title="Audio Bubble (Legacy)" icon="headphones" href="/ui-kit/react/components/audio-bubble">
+    Single-attachment audio bubble
+  </Card>
+  <Card title="Files Bubble" icon="file" href="/ui-kit/react/components/files-bubble">
+    Multi-attachment file bubble
+  </Card>
+  <Card title="Message Composer" icon="pen-to-square" href="/ui-kit/react/components/message-composer">
+    Enable multi-attachment staging tray
+  </Card>
+</CardGroup>