Full Screen Viewer - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatFullScreenViewer",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatFullScreenViewer } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Full-screen modal overlay for viewing images, videos, audio, and file previews with gallery navigation.",
  "cssRootClass": ".cometchat-fullscreen-viewer",
  "primaryOutput": {
    "prop": "onClose",
    "type": "() => void"
  },
  "props": {
    "data": {
      "isOpen": { "type": "boolean", "default": "false" },
      "url": { "type": "string", "default": "undefined" },
      "mediaType": { "type": "CometChatFullScreenViewerMediaType", "default": "'image'" },
      "fileName": { "type": "string", "default": "undefined" },
      "fileSize": { "type": "number", "default": "undefined" },
      "attachments": { "type": "CometChatMediaAttachment[]", "default": "[]" },
      "startIndex": { "type": "number", "default": "0" },
      "senderName": { "type": "string", "default": "undefined" },
      "senderAvatar": { "type": "string", "default": "undefined" },
      "senderStatus": { "type": "string", "default": "undefined" },
      "sentAt": { "type": "string", "default": "undefined" }
    },
    "callbacks": {
      "onClose": "() => void",
      "onIndexChange": "(index: number) => void",
      "onDownload": "(attachment: CometChatMediaAttachment | string) => void"
    },
    "behavior": {
      "enablePictureInPicture": { "type": "boolean", "default": "true" }
    }
  },
  "events": [],
  "sdkListeners": [],
  "types": {
    "CometChatFullScreenViewerMediaType": "'image' | 'video' | 'audio' | 'file'",
    "CometChatMediaAttachment": {
      "url": "string",
      "type": "CometChatFullScreenViewerMediaType",
      "name": "string | undefined",
      "size": "number | undefined"
    }
  }
}

Where It Fits

CometChatFullScreenViewer is a modal overlay component used by CometChatMessageList when a user taps an image, video, audio, or file bubble. It supports single-media mode and gallery mode with prev/next navigation.

import { useState } from "react";
import { CometChatFullScreenViewer } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function ChatWithViewer() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsOpen(true)}>View Image</button>
      <CometChatFullScreenViewer.Root
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        url="https://example.com/photo.jpg"
        mediaType="image"
        senderName="John Doe"
        senderAvatar="https://example.com/avatar.jpg"
        sentAt="Today at 2:30 PM"
      />
    </div>
  );
}

Minimal Render

import { CometChatFullScreenViewer } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function ViewerDemo() {
  return (
    <CometChatFullScreenViewer.Root
      isOpen={true}
      onClose={() => {}}
      url="https://example.com/photo.jpg"
    />
  );
}

Root CSS class: .cometchat-fullscreen-viewer

Media Types

The viewer supports four media types:

Type	Renders	Controls
`image`	`<img>` with box-shadow	None (view only)
`video`	`<video>` with native controls	Play/pause, seek, fullscreen
`audio`	Audio icon + `<audio>` with native controls	Play/pause, seek
`file`	File icon + extension badge + download button	Download link

// Video
<CometChatFullScreenViewer.Root
  isOpen={true}
  onClose={handleClose}
  url="https://example.com/video.mp4"
  mediaType="video"
  fileName="meeting.mp4"
  fileSize={15728640}
/>

// File preview
<CometChatFullScreenViewer.Root
  isOpen={true}
  onClose={handleClose}
  url="https://example.com/report.pdf"
  mediaType="file"
  fileName="quarterly-report.pdf"
  fileSize={2097152}
/>

Gallery Mode

Pass an attachments array to enable gallery navigation with prev/next buttons and keyboard arrow keys.

import { CometChatFullScreenViewer } from "@cometchat/chat-uikit-react";
import type { CometChatMediaAttachment } from "@cometchat/chat-uikit-react";

const attachments: CometChatMediaAttachment[] = [
  { url: "https://example.com/1.jpg", type: "image", name: "photo-1.jpg" },
  { url: "https://example.com/2.jpg", type: "image", name: "photo-2.jpg" },
  { url: "https://example.com/clip.mp4", type: "video", name: "clip.mp4" },
];

<CometChatFullScreenViewer.Root
  isOpen={true}
  onClose={handleClose}
  attachments={attachments}
  startIndex={0}
  senderName="Team Chat"
  onIndexChange={(index) => console.log("Viewing:", index)}
  onDownload={(attachment) => console.log("Download:", attachment)}
/>

Navigation stops at boundaries — prev is disabled at index 0, next is disabled at the last index.

Actions and Events

Callback Props

onClose

Fires when the viewer requests to close (close button, Escape key).

<CometChatFullScreenViewer.Root
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  url="https://example.com/photo.jpg"
/>

onIndexChange

Fires when the gallery index changes via navigation.

<CometChatFullScreenViewer.Root
  isOpen={true}
  onClose={handleClose}
  attachments={attachments}
  onIndexChange={(index) => console.log("Now viewing index:", index)}
/>

onDownload

Fires when the download button is clicked. Receives the current attachment or URL.

<CometChatFullScreenViewer.Root
  isOpen={true}
  onClose={handleClose}
  url="https://example.com/photo.jpg"
  onDownload={(url) => window.open(url as string)}
/>

Common Patterns

Image viewer with sender info

<CometChatFullScreenViewer.Root
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  url={imageUrl}
  mediaType="image"
  senderName="Alice"
  senderAvatar={avatarUrl}
  senderStatus="Online"
  sentAt="Today at 3:15 PM"
/>

Minimal viewer (no sender info)

<CometChatFullScreenViewer.Root
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  url={imageUrl}
/>

File download

<CometChatFullScreenViewer.Root
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  url={fileUrl}
  mediaType="file"
  fileName="document.pdf"
  fileSize={1048576}
  onDownload={(url) => triggerDownload(url as string)}
/>

CSS Architecture

The component uses CSS custom properties (design tokens) defined in @cometchat/chat-uikit-react/css-variables.css. The cascade:

Global tokens set on the .cometchat root wrapper.
Component CSS (.cometchat-fullscreen-viewer) consumes these tokens via var().
Overrides target .cometchat-fullscreen-viewer descendant selectors.

Key Selectors

Target	Selector
Root overlay	`.cometchat-fullscreen-viewer`
Header bar	`.cometchat-fullscreen-viewer__header`
Header left	`.cometchat-fullscreen-viewer__header-left`
Header center	`.cometchat-fullscreen-viewer__header-center`
Header right	`.cometchat-fullscreen-viewer__header-right`
Sender info	`.cometchat-fullscreen-viewer__sender-info`
Sender name	`.cometchat-fullscreen-viewer__sender-name`
Avatar	`.cometchat-fullscreen-viewer__avatar`
File info	`.cometchat-fullscreen-viewer__file-info-header`
Gallery index	`.cometchat-fullscreen-viewer__index-display`
Close button	`.cometchat-fullscreen-viewer__close-btn`
Body	`.cometchat-fullscreen-viewer__body`
Image	`.cometchat-fullscreen-viewer__body-image`
Video	`.cometchat-fullscreen-viewer__body-video`
Audio container	`.cometchat-fullscreen-viewer__audio-container`
File preview	`.cometchat-fullscreen-viewer__file-preview`
Nav prev	`.cometchat-fullscreen-viewer__nav-button--prev`
Nav next	`.cometchat-fullscreen-viewer__nav-button--next`
Error state	`.cometchat-fullscreen-viewer__error-state`

Customization Matrix

What to change	Where	Property/API	Example
Handle close	Component props	`onClose`	`onClose={() => setOpen(false)}`
Set media type	Component props	`mediaType`	`mediaType="video"`
Enable gallery	Component props	`attachments`	`attachments={[...]}`
Track navigation	Component props	`onIndexChange`	`onIndexChange={(i) => ...}`
Handle download	Component props	`onDownload`	`onDownload={(a) => ...}`
Change colors, fonts	Global CSS	`.cometchat-fullscreen-viewer`	See selectors above

Props

All props are optional unless noted.

isOpen

Whether the viewer is open. Required.


Type	`boolean`
Default	—

onClose

Callback when the viewer requests to close. Required.


Type	`() => void`
Default	—

url

Media URL (single mode).


Type	`string`
Default	`undefined`

mediaType

Type of media to display.


Type	`'image' \| 'video' \| 'audio' \| 'file'`
Default	`'image'`

fileName

File name displayed in header and file preview.


Type	`string`
Default	`undefined`

fileSize

File size in bytes.


Type	`number`
Default	`undefined`

attachments

Array of media attachments for gallery mode.


Type	`CometChatMediaAttachment[]`
Default	`[]`

interface CometChatMediaAttachment {
  url: string;
  type: 'image' | 'video' | 'audio' | 'file';
  name?: string;
  size?: number;
}

startIndex

Starting index for gallery mode.


Type	`number`
Default	`0`

senderName

Sender name displayed in header.


Type	`string`
Default	`undefined`

senderAvatar

Sender avatar URL displayed in header.


Type	`string`
Default	`undefined`

senderStatus

Sender status text displayed in header.


Type	`string`
Default	`undefined`

sentAt

Formatted timestamp string displayed in header.


Type	`string`
Default	`undefined`

onIndexChange

Callback when the gallery index changes.


Type	`(index: number) => void`
Default	`undefined`

onDownload

Callback when the download button is clicked.


Type	`(attachment: CometChatMediaAttachment \| string) => void`
Default	`undefined`

enablePictureInPicture

Enable Picture-in-Picture for video.


Type	`boolean`
Default	`true`

className

Custom CSS class applied to the root element.


Type	`string`
Default	`undefined`

CSS Selectors

Target	Selector
Root overlay	`.cometchat-fullscreen-viewer`
Header	`.cometchat-fullscreen-viewer__header`
Header left	`.cometchat-fullscreen-viewer__header-left`
Header center	`.cometchat-fullscreen-viewer__header-center`
Header right	`.cometchat-fullscreen-viewer__header-right`
Sender info	`.cometchat-fullscreen-viewer__sender-info`
Avatar	`.cometchat-fullscreen-viewer__avatar`
Avatar image	`.cometchat-fullscreen-viewer__avatar-image`
Avatar initials	`.cometchat-fullscreen-viewer__avatar-initials`
Sender name	`.cometchat-fullscreen-viewer__sender-name`
Sender status	`.cometchat-fullscreen-viewer__sender-status`
Sender date	`.cometchat-fullscreen-viewer__sender-date`
File info header	`.cometchat-fullscreen-viewer__file-info-header`
File info name	`.cometchat-fullscreen-viewer__file-info-name`
Gallery index	`.cometchat-fullscreen-viewer__index-display`
Action button	`.cometchat-fullscreen-viewer__action-button`
Close icon	`.cometchat-fullscreen-viewer__close-icon`
Body	`.cometchat-fullscreen-viewer__body`
Image	`.cometchat-fullscreen-viewer__body-image`
Video container	`.cometchat-fullscreen-viewer__video-container`
Video	`.cometchat-fullscreen-viewer__body-video`
Audio container	`.cometchat-fullscreen-viewer__audio-container`
Audio icon	`.cometchat-fullscreen-viewer__audio-icon`
Audio filename	`.cometchat-fullscreen-viewer__audio-filename`
File preview	`.cometchat-fullscreen-viewer__file-preview`
File icon	`.cometchat-fullscreen-viewer__file-icon`
File extension	`.cometchat-fullscreen-viewer__file-extension`
File name	`.cometchat-fullscreen-viewer__file-preview-name`
File size	`.cometchat-fullscreen-viewer__file-preview-size`
Download button	`.cometchat-fullscreen-viewer__download-button`
Nav button	`.cometchat-fullscreen-viewer__nav-button`
Nav prev	`.cometchat-fullscreen-viewer__nav-button--prev`
Nav next	`.cometchat-fullscreen-viewer__nav-button--next`
Error state	`.cometchat-fullscreen-viewer__error-state`
Error icon	`.cometchat-fullscreen-viewer__error-icon`
Error text	`.cometchat-fullscreen-viewer__error-text`

Documentation Index

​Where It Fits

​Minimal Render

​Media Types

​Gallery Mode

​Actions and Events

​Callback Props

​onClose

​onIndexChange

​onDownload

​Common Patterns

​Image viewer with sender info

​Minimal viewer (no sender info)

​File download

​CSS Architecture

​Key Selectors

​Customization Matrix

​Props

​isOpen

​onClose

​url

​mediaType

​fileName

​fileSize

​attachments

​startIndex

​senderName

​senderAvatar

​senderStatus

​sentAt

​onIndexChange

​onDownload

​enablePictureInPicture

​className

​CSS Selectors

Where It Fits

Minimal Render

Media Types

Gallery Mode

Actions and Events

Callback Props

onClose

onIndexChange

onDownload

Common Patterns

Image viewer with sender info

Minimal viewer (no sender info)

File download

CSS Architecture

Key Selectors

Customization Matrix

Props

isOpen

onClose

url

mediaType

fileName

fileSize

attachments

startIndex

senderName

senderAvatar

senderStatus

sentAt

onIndexChange

onDownload

enablePictureInPicture

className

CSS Selectors