Image Preview & Caption - CometChat Docs

AI Agent Component Spec

Field	Value
Package	`cometchat_chat_uikit`
Key components	`CometChatCompactMessageComposer`, `CometChatMessageList`, `CometChatMessageTemplate`
Init	`CometChatUIKit.init(uiKitSettings)` then `CometChatUIKit.login(uid)`
Entry point	Attachment tap → image pick → inline preview → send with caption
Extension points	`attachmentOptions`, `headerView`, `stateCallBack`, `onSendButtonTap`, `templates`
Sample app	GitHub
Related	Compact Message Composer · Message Template · All Guides

This guide adds two capabilities to the default messaging experience:

When a user picks an image, an inline preview appears above the composer. They can type a caption, then tap send — or cancel to discard.
Image messages that include a caption display the caption text below the thumbnail in the message bubble.

No UIKit source files are modified. Everything uses the UIKit’s public extension points. Before starting, complete the Getting Started guide.

Components

Component / Class	Role
`CometChatCompactMessageComposer`	Composer with `headerView`, `stateCallBack`, `onSendButtonTap`, and `attachmentOptions` slots
`CometChatMessageList`	Renders messages using custom `templates`
`CometChatMessageTemplate`	Defines a custom `contentView` for image messages with caption rendering
`MediaPicker`	Picks images from gallery or camera
`InlineImagePreview`	Custom widget shown above the composer (created in this guide)

Architecture

User picks image
       │
       ▼
attachmentOptions (custom onItemClick)
       │
       ▼
_showImagePreviewPanel()
  ├─ setState() → stores pending image path
  ├─ Injects zero-width space into text field (enables send button)
  └─ headerView renders InlineImagePreview
       │
       ▼
User types caption + taps Send
       │
       ▼
onSendButtonTap → _handleSendButtonTap()
  ├─ Reads caption from the TextMessage object
  ├─ Strips zero-width space placeholder
  ├─ Calls CometChatUIKit.sendMediaMessage() with caption
  └─ Clears pending state
       │
       ▼
Message list renders via custom template
  ├─ Reads caption from mediaMessage.caption OR metadata['text']
  └─ Renders Text widget below the image bubble

Integration Steps

1. Add State for Pending Image

Track the pending image path and a reference to the composer controller in your messages screen state.

class _MessagesSampleState extends State<MessagesSample> {
  String? _pendingImagePath;
  String? _pendingImageType;
  CometChatCompactMessageComposerController? _composerController;

  // ...
}

This widget renders a thumbnail and cancel button above the composer. It uses FileUtils.normalizeFilePath() to handle percent-encoded iOS file paths. File: image_preview_screen.dart

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

class InlineImagePreview extends StatelessWidget {
  final String filePath;
  final VoidCallback onCancel;

  const InlineImagePreview({
    super.key,
    required this.filePath,
    required this.onCancel,
  });

  @override
  Widget build(BuildContext context) {
    final colorPalette = CometChatThemeHelper.getColorPalette(context);
    final spacing = CometChatThemeHelper.getSpacing(context);
    final normalizedPath = FileUtils.normalizeFilePath(filePath);
    final file = File(normalizedPath);

    return Container(
      padding: EdgeInsets.all(spacing.padding3 ?? 12),
      margin: EdgeInsets.symmetric(horizontal: spacing.margin2 ?? 8),
      decoration: BoxDecoration(
        color: colorPalette.background1,
        borderRadius: BorderRadius.only(
          topLeft: Radius.circular(spacing.radius3 ?? 12),
          topRight: Radius.circular(spacing.radius3 ?? 12),
        ),
        border: Border.all(
          color: colorPalette.borderDefault ?? Colors.transparent,
        ),
      ),
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          ClipRRect(
            borderRadius: BorderRadius.circular(spacing.radius2 ?? 8),
            child: SizedBox(
              width: 80,
              height: 80,
              child: Image.file(
                file,
                fit: BoxFit.cover,
                errorBuilder: (context, error, stackTrace) {
                  return Container(
                    color: colorPalette.background3,
                    child: Icon(
                      Icons.broken_image,
                      color: colorPalette.iconTertiary,
                      size: 32,
                    ),
                  );
                },
              ),
            ),
          ),
          SizedBox(width: spacing.padding3 ?? 12),
          Expanded(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(
                  filePath.split('/').last,
                  maxLines: 1,
                  overflow: TextOverflow.ellipsis,
                  style: TextStyle(
                    color: colorPalette.textPrimary,
                    fontSize: 14,
                    fontWeight: FontWeight.w500,
                  ),
                ),
                const SizedBox(height: 4),
                Text(
                  'Tap send to share',
                  style: TextStyle(
                    color: colorPalette.textTertiary,
                    fontSize: 12,
                  ),
                ),
              ],
            ),
          ),
          IconButton(
            onPressed: onCancel,
            icon: Icon(
              Icons.close,
              color: colorPalette.iconSecondary,
              size: 20,
            ),
            padding: EdgeInsets.zero,
            constraints: const BoxConstraints(),
          ),
        ],
      ),
    );
  }
}

3. Build Custom Attachment Options

Replace the default image/camera attachment options with versions that pick the file but show a preview instead of sending immediately. Non-image options (video, audio, file) have no onItemClick, so they fall through to the default pick-and-send behavior.

List<CometChatMessageComposerAction> _buildAttachmentOptionsWithImagePreview(
  BuildContext context,
  User? user,
  Group? group,
) {
  final colorPalette = CometChatThemeHelper.getColorPalette(context);
  final List<CometChatMessageComposerAction> actions = [];

  // Camera — pick and preview
  actions.add(CometChatMessageComposerAction(
    id: 'takePhoto',
    title: Translations.of(context).camera,
    icon: Icon(Icons.photo_camera, color: colorPalette.iconHighlight, size: 24),
    onItemClick: (ctx, u, g) async {
      final pickedFile = await MediaPicker.takePhoto();
      if (pickedFile == null) return;
      _showImagePreviewPanel(pickedFile.path, MessageTypeConstants.image);
    },
  ));

  // Gallery — pick and preview
  actions.add(CometChatMessageComposerAction(
    id: MessageTypeConstants.attachPhoto,
    title: Translations.of(context).attachImage,
    icon: Icon(Icons.image, color: colorPalette.iconHighlight, size: 24),
    onItemClick: (ctx, u, g) async {
      final pickedFile = await MediaPicker.pickImage();
      if (pickedFile == null) return;
      final type = pickedFile.fileType ?? MessageTypeConstants.image;
      _showImagePreviewPanel(pickedFile.path, type);
    },
  ));

  // Video, audio, file — no onItemClick, default behavior
  actions.add(CometChatMessageComposerAction(
    id: MessageTypeConstants.attachVideo,
    title: Translations.of(context).attachVideo,
    icon: Icon(Icons.videocam_rounded, color: colorPalette.iconHighlight, size: 24),
  ));

  actions.add(CometChatMessageComposerAction(
    id: MessageTypeConstants.audio,
    title: Translations.of(context).attachAudio,
    icon: Icon(Icons.headphones, color: colorPalette.iconHighlight, size: 24),
  ));

  actions.add(CometChatMessageComposerAction(
    id: MessageTypeConstants.file,
    title: Translations.of(context).attachDocument,
    icon: Icon(Icons.description, color: colorPalette.iconHighlight, size: 24),
  ));

  return actions;
}

4. Show and Clear the Preview Panel

When an image is picked, store the path and inject a zero-width space (\u200B) into the text field to enable the send button. On cancel, clear the state and remove the placeholder only if no real text was typed.

void _showImagePreviewPanel(String filePath, String messageType) {
  setState(() {
    _pendingImagePath = filePath;
    _pendingImageType = messageType;
  });

  final currentText = _composerController?.textEditingController?.text ?? '';
  if (currentText.trim().isEmpty) {
    _composerController?.textEditingController?.text = '\u200B';
  }
}

void _clearPendingImage() {
  setState(() {
    _pendingImagePath = null;
    _pendingImageType = null;
  });

  final currentText = _composerController?.textEditingController?.text ?? '';
  if (currentText.replaceAll('\u200B', '').trim().isEmpty) {
    _composerController?.textEditingController?.clear();
  }
}

The zero-width space trick is needed because the composer’s send button only enables when the text field is non-empty. This invisible character activates the button without showing any visible text.

5. Intercept the Send Button

When the user taps send with a pending image, build a MediaMessage with the caption and send it via CometChatUIKit.sendMediaMessage(). Otherwise, forward to the default SDK send. The caption is read from the TextMessage object passed to the callback — not from the text field — because the controller clears the text field before calling onSendButtonTap.

void _handleSendButtonTap(
  BuildContext ctx,
  BaseMessage message,
  PreviewMessageMode? previewMode,
) {
  if (_pendingImagePath != null && _pendingImageType != null) {
    final path = _pendingImagePath!;
    final type = _pendingImageType!;
    final receiverUid = widget.user?.uid ?? widget.group?.guid ?? '';
    final receiverType = widget.user != null
        ? ReceiverTypeConstants.user
        : ReceiverTypeConstants.group;
    final parentMsgId = widget.parentMessage?.id ?? 0;

    // Read caption from the TextMessage the controller built before clearing
    final caption = (message is TextMessage)
        ? message.text.replaceAll('\u200B', '').trim()
        : '';

    _clearPendingImage();

    CometChatUIKit.sendMediaMessage(
      MediaMessage(
        receiverType: receiverType,
        type: type,
        receiverUid: receiverUid,
        file: path,
        metadata: {"localPath": path},
        parentMessageId: parentMsgId,
        muid: DateTime.now().microsecondsSinceEpoch.toString(),
        category: CometChatMessageCategory.message,
        caption: caption.isNotEmpty ? caption : null,
      ),
    );
  } else {
    // No pending image — forward to default SDK send
    if (message is TextMessage) {
      CometChatMessageEvents.ccMessageSent(message, MessageStatus.inProgress);
      CometChat.sendMessage(
        message,
        onSuccess: (TextMessage sentMessage) {
          CometChatMessageEvents.ccMessageSent(sentMessage, MessageStatus.sent);
        },
        onError: (CometChatException e) {
          if (message.metadata != null) {
            message.metadata!["error"] = e;
          } else {
            message.metadata = {"error": e};
          }
          CometChatMessageEvents.ccMessageSent(message, MessageStatus.error);
        },
      );
    }
  }
}

6. Wire Up the Composer

Pass all four extension points to CometChatCompactMessageComposer:

CometChatCompactMessageComposer(
  user: widget.user,
  group: widget.group,
  stateCallBack: (controller) {
    _composerController = controller;
  },
  headerView: _pendingImagePath != null
      ? (ctx, user, group, id) => InlineImagePreview(
            filePath: _pendingImagePath!,
            onCancel: () => _clearPendingImage(),
          )
      : null,
  onSendButtonTap: (ctx, message, previewMode) {
    _handleSendButtonTap(ctx, message, previewMode);
  },
  attachmentOptions: (ctx, user, group, composerId) {
    return _buildAttachmentOptionsWithImagePreview(ctx, user, group);
  },
)

7. Render Captions in Image Bubbles

Create a custom CometChatMessageTemplate for image messages that wraps the default image bubble with a caption Text widget below it. CometChat stores the caption in MediaMessage.caption and also in metadata['text']. The template checks both locations.

CometChatMessageTemplate _imageTemplateWithCaption() {
  return CometChatMessageTemplate(
    type: MessageTypeConstants.image,
    category: MessageCategoryConstants.message,
    contentView: (BaseMessage message, BuildContext context,
        BubbleAlignment alignment,
        {AdditionalConfigurations? additionalConfigurations}) {
      if (message.deletedAt != null) {
        return CometChatUIKit.getDataSource().getDeleteMessageBubble(
            message, context, additionalConfigurations?.deletedBubbleStyle);
      }

      final mediaMessage = message as MediaMessage;
      final caption = (mediaMessage.caption != null &&
              mediaMessage.caption!.trim().isNotEmpty)
          ? mediaMessage.caption
          : (mediaMessage.metadata?['text'] as String?);

      final imageBubble = CometChatUIKit.getDataSource()
          .getImageMessageContentView(mediaMessage, context, alignment,
              additionalConfigurations: additionalConfigurations);

      if (caption == null || caption.trim().isEmpty) {
        return imageBubble;
      }

      final colorPalette = CometChatThemeHelper.getColorPalette(context);
      final typography = CometChatThemeHelper.getTypography(context);
      final spacing = CometChatThemeHelper.getSpacing(context);
      final isOutgoing = alignment == BubbleAlignment.right;

      return Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        children: [
          imageBubble,
          Padding(
            padding: EdgeInsets.only(
              top: spacing.padding2 ?? 4,
              left: spacing.padding2 ?? 4,
              right: spacing.padding2 ?? 4,
            ),
            child: Text(
              caption,
              style: TextStyle(
                color: isOutgoing
                    ? colorPalette.white
                    : colorPalette.textPrimary,
                fontSize: typography.body?.regular?.fontSize,
                fontWeight: typography.body?.regular?.fontWeight,
                fontFamily: typography.body?.regular?.fontFamily,
              ),
            ),
          ),
        ],
      );
    },
    options: CometChatUIKit.getDataSource().getMessageOptions,
  );
}

8. Apply the Custom Template to the Message List

Use the templates parameter on CometChatMessageList to replace the default image template. Filter out the built-in image template and append the custom one.

Use templates, not addTemplate. The addTemplate parameter only fills in null fields on existing templates — it cannot override an existing contentView.

CometChatMessageList(
  user: user,
  group: group,
  templates: [
    ...(CometChatUIKit.getDataSource()
        .getAllMessageTemplates()
        .where((t) => !(t.type == MessageTypeConstants.image &&
            t.category == MessageCategoryConstants.message))),
    _imageTemplateWithCaption(),
  ],
)

Key Gotchas

Issue	Cause	Solution
Send button stays disabled with image preview	Composer requires non-empty text to enable send	Inject `\u200B` (zero-width space) into the text field
Caption is empty in `onSendButtonTap`	Controller clears `textEditingController` before calling the callback	Read caption from the `TextMessage` object passed to the callback
`headerView` disappears on keystroke	`CometChatMentionsFormatter` calls `hidePanel(composerTop)` on every text change	Use `headerView` (widget property) instead of `showPanel(composerTop)`
Custom template ignored by `addTemplate`	Template merge only fills null fields; default image template already has a `contentView`	Use `templates` parameter and filter out the default image template
Image preview crashes on iOS	`MediaPicker` percent-encodes paths with spaces on iOS	Use `FileUtils.normalizeFilePath()` to decode before passing to `File()`

Feature Matrix

Feature	Extension Point	Component
Image pick without auto-send	`attachmentOptions`	`CometChatCompactMessageComposer`
Inline preview above composer	`headerView`	`CometChatCompactMessageComposer`
Controller access	`stateCallBack`	`CometChatCompactMessageComposer`
Send interception	`onSendButtonTap`	`CometChatCompactMessageComposer`
Caption in image bubbles	`templates`	`CometChatMessageList`

Next Steps

Compact Message Composer

Full reference for the compact composer component.

Message Template

Customize how message types are rendered.

Message List

Configure the message list component.

All Guides

Browse all feature and formatter guides.

​Components

​Architecture

​Integration Steps

​1. Add State for Pending Image

​2. Create the Inline Image Preview Widget

​3. Build Custom Attachment Options

​4. Show and Clear the Preview Panel

​5. Intercept the Send Button

​6. Wire Up the Composer

​7. Render Captions in Image Bubbles

​8. Apply the Custom Template to the Message List

​Key Gotchas

​Feature Matrix

​Next Steps

Compact Message Composer

Message Template

Message List

All Guides

Components

Architecture

Integration Steps

1. Add State for Pending Image

2. Create the Inline Image Preview Widget

3. Build Custom Attachment Options

4. Show and Clear the Preview Panel

5. Intercept the Send Button

6. Wire Up the Composer

7. Render Captions in Image Bubbles

8. Apply the Custom Template to the Message List

Key Gotchas

Feature Matrix

Next Steps