Attachments

A message's attachments render in its bubble, as parts of MessageContent. Message sorts them by kind into the MessageContext values images, videos, files and otherAttachments, and each kind renders in its own part of messageContentOrder: Gallery for images and videos, FileAttachmentGroup for files, and Attachment for each of the others. Every component on this page is an override key of the same name, except UrlPreview, whose default is URLPreview, and FileAttachmentIcon, whose default is FileIcon. Attachments and uploads covers the feature across the layers.

Best practices

• Render a custom attachment type by overriding Attachment, and hand every other type to the default Attachment, as below. Custom attachments builds a complete one.
• Replace one kind through its own key, such as FileAttachment or UrlPreview, rather than Attachment as a whole.
• Change what a tap on an attachment does with onPressMessage on Channel: the payload's emitter says which kind was pressed, and additionalInfo carries the attachment, the thumbnail or the URL. Call defaultHandler() to keep the SDK's behavior.
• Install a video player, an audio player and a document picker through the native handlers you need. Without a video player, videos render as files; without an audio player, audio attachments do.

Basic usage

A message with an attachment of type product, sent from your backend, renders UnsupportedAttachment by default. This override renders it as a card and hands every other attachment to the default:

import { StyleSheet, Text, View } from "react-native";
import {
  Attachment,
  type AttachmentProps,
  WithComponents,
} from "stream-chat-react-native";

const AttachmentWithProducts = (props: AttachmentProps) => {
  const { attachment } = props;

  if (attachment?.type === "product") {
    return (
      <View style={styles.card}>
        <Text style={styles.title}>{attachment.title}</Text>
        {attachment.text ? <Text>{attachment.text}</Text> : null}
      </View>
    );
  }

  return <Attachment {...props} />;
};

const overrides = { Attachment: AttachmentWithProducts };

export const MessagesWithProducts = ({
  children,
}: {
  children: React.ReactNode;
}) => <WithComponents overrides={overrides}>{children}</WithComponents>;

const styles = StyleSheet.create({
  card: { borderRadius: 12, gap: 4, padding: 12, width: 240 },
  title: { fontWeight: "600" },
});

A custom type lands in otherAttachments, which renders only while the message has no file, image or video attachment.

How attachments are sorted

A file, image or video attachment empties otherAttachments, so a message holds either those or the others. An image without an image URL isn't rendered.

Attachment

Renders one attachment by its type, in this order: Giphy for a Giphy or Imgur attachment; URLPreviewCompact or UrlPreview for one with og_scrape_url or title_link; Gallery for an image or a playable video; AudioAttachment for audio or a voice recording, with its upload progress while it uploads; FileAttachment for a file; and UnsupportedAttachment otherwise. FileAttachmentGroup renders each file through the Attachment key too.

AttachmentType is the Attachment type of stream-chat, imported under another name.

Gallery

Renders images and videos as a grid of up to four thumbnails, with "+3" over the last one when there are more. Pressing a thumbnail reports the gallery emitter with the thumbnail as additionalInfo; by default it opens the image gallery at that image or video. A prop set here wins over its context value.

The sizes of the grid come from theme.messageItemView.gallery.

VideoThumbnail

Renders a video's thumbnail with a play icon, inside a Gallery. Without thumb_url it renders only its container.

Giphy

Renders a Giphy or Imgur attachment. A Giphy preview from the /giphy command, which has actions, shows "Only visible to you" and the action buttons, such as Send, Shuffle and Cancel; pressing one calls handleAction. A sent Giphy renders the image, and pressing it reports the giphy emitter. It renders nothing without image_url or thumb_url. A prop set here wins over its context value.

GiphyImage renders the image itself, and is exported for a Giphy component of your own.

FileAttachmentGroup

Renders the message's files, each through the Attachment override, in a column.

FileAttachment

Renders a file through the FilePreview override, with the file's icon and title, and its upload progress while it uploads. Pressing it reports the fileAttachment emitter with the attachment as additionalInfo; by default it opens the file's asset_url. A prop set here wins over its context value.

FilePreview

Renders the FileAttachmentIcon override for the file's custom.mime_type, the title, and under it indicator, or the size or the duration when there's no indicator. It isn't exported; replace it with the FilePreview key.

FileIcon

Renders the icon for a MIME type, from the icons override map: PDF, DOC, SpreadSheet, Presentation, ZIP, Audio, Video, Code, or OtherFileIcon for any other type. It's the default of the FileAttachmentIcon key.

AudioAttachment

Plays an audio attachment or a voice recording: a play button, the remaining time, a waveform for a voice recording with waveform_data or a progress bar otherwise, which the user can drag to seek, and a speed button. Each message's attachment has its own player; Voice recordings and audio playback explains how players are shared and when they stop. In a message, Attachment renders it with showTitle={false} and showSpeedSettings.

URLPreview and URLPreviewCompact

URLPreview, the default of the UrlPreview key, renders a link preview as a card: the image, with a play icon for a video link, the title, the description and the URL. URLPreviewCompact renders the same in a smaller layout, and urlPreviewType="compact" on Channel picks it. Pressing either reports the urlPreview emitter with the URL as additionalInfo; by default it opens og_scrape_url. Both remount when the message updates. Link previews covers the feature.

URLPreviewCompact takes the same props without isAttachmentEqual:

UnsupportedAttachment

Renders an attachment of a type the SDK doesn't know: the FileAttachmentIcon override for its custom.mime_type, and its title, or "Unsupported Attachment". It isn't exported; replace it with the UnsupportedAttachment key, or render your type from an Attachment override as above.

Related hooks

• useMessageContext() returns the message's attachments by kind: images, videos, files and otherAttachments.
• useAudioPlayer() returns the player of an audio attachment, for a player of your own. See Voice recordings and audio playback.
• buildGallery() computes the grid Gallery lays out.