# Working with Attachments/Files

The SDK allows users to add attachments to a message. Several attachment types are supported, such as image, video, file and Giphy.

## Attachment Gallery

`AttachmentGalleryActivity` is an Activity used to display image and video attachments that the users have sent in the chat. Users can view, share, and download the attachments, and use an overview to easily navigate through them.

| Light Mode                                                                                                       | Dark Mode                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| ![Attachment gallery example 1 light](@chat-sdk/android/v6-latest/_assets/attachment_gallery_example1_light.png) | ![Attachment gallery example 2 dark](@chat-sdk/android/v6-latest/_assets/attachment_gallery_example1_dark.png) |
| ![Attachment gallery example 1 light](@chat-sdk/android/v6-latest/_assets/attachment_gallery_example2_light.png) | ![Attachment gallery example 2 dark](@chat-sdk/android/v6-latest/_assets/attachment_gallery_example2_dark.png) |

### Handling Actions

There are four user actions that can be customized by the following handlers:

- `AttachmentReplyOptionHandler`
- `AttachmentShowInChatOptionHandler`
- `AttachmentDownloadOptionHandler`
- `AttachmentDeleteOptionHandler`

These are called when the user selects one of the options from the overflow menu in the top right corner:

| Light                                                                                                       | Dark                                                                                                      |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| ![Attachment gallery example light](@chat-sdk/android/v6-latest/_assets/attachment_activity_menu_light.png) | ![Attachment gallery example dark](@chat-sdk/android/v6-latest/_assets/attachment_activity_menu_dark.png) |

As the gallery is usually opened from `MessageListView`, you can set these handlers on the View in the following way:

<tabs>

<tabs-item value="kotlin" label="Kotlin">

```kotlin
messageListView.setAttachmentReplyOptionClickHandler { resultItem ->
    resultItem.messageId
    // Handle reply to attachment
}

messageListView.setAttachmentShowInChatOptionClickHandler { resultItem ->
    resultItem.messageId
    // Handle show in chat
}

messageListView.setDownloadOptionHandler { resultItem ->
    resultItem.assetUrl
    // Handle download the attachment
}

messageListView.setAttachmentDeleteOptionClickHandler { resultItem ->
    resultItem.assetUrl
    resultItem.imageUrl
    // Handle delete
}
```

</tabs-item>

<tabs-item value="java" label="Java">

```java
messageListView.setAttachmentReplyOptionClickHandler(resultItem -> {
    resultItem.getMessageId();
    // Handle reply to attachment
});

messageListView.setAttachmentShowInChatOptionClickHandler(resultItem -> {
    resultItem.getMessageId();
    // Handle show in chat
});

messageListView.setDownloadOptionHandler(resultItem -> {
    resultItem.getAssetUrl();
    // Handle download the attachment
});

messageListView.setAttachmentDeleteOptionClickHandler(resultItem -> {
    resultItem.getAssetUrl();
    resultItem.getImageUrl();
    // Handle delete
});
```

</tabs-item>

</tabs>

### Navigating to the Attachment Gallery

By default, the Attachment Gallery is opened when a user clicks on an attachment in `MessageListView`. In which case, all actions mentioned above have a default implementation, which can be changed by overriding `MessageListView`'s handlers.

You can also navigate to `AttachmentGalleryActivity` manually from anywhere else in your code. In this case, you will need to implement all available actions:

<tabs>

<tabs-item value="kotlin" label="Kotlin">

```kotlin
// Create Attachment Gallery Destination
val destination = AttachmentGalleryDestination(
    requireContext(),
    attachmentReplyOptionHandler = { resultItem ->
        // Handle reply
    },
    attachmentShowInChatOptionHandler = { resultItem ->
        // Handle show image in chat
    },
    attachmentDownloadOptionHandler = { resultItem ->
        // Handle download image
    },
    attachmentDeleteOptionClickHandler = { resultItem ->
        // Handle delete image
    },
)

// Register destination with the ActivityResultRegistry
activity?.activityResultRegistry?.let { registry ->
    destination.register(registry)
}

// Set the data to display
destination.setData(attachmentGalleryItems = listOf(), attachmentIndex = 0)

// Fire the navigation request
ChatUI.navigator.navigate(destination)
```

</tabs-item>

<tabs-item value="java" label="Java">

```java
// Create Attachment Gallery Destination
AttachmentGalleryDestination destination = new AttachmentGalleryDestination(
        activity,
        resultItem -> {
            // Handle reply
        },
        resultItem -> {
            // Handle show image in chat
        },
        resultItem -> {
            // Handle download image
        },
        resultItem -> {
            // Handle delete image
        }
);

// Register destination with the ActivityResultRegistry
destination.register(activity.getActivityResultRegistry());

// Set the data to display
int attachmentIndex = 0;
destination.setData(Collections.emptyList(), attachmentIndex);

// Fire the navigation request
ChatUI.getNavigator().navigate(destination);
```

</tabs-item>

</tabs>

### Customization

The gallery can be customized through the use of styleable attributes. These are organized into individual styles which apply to a certain aspect or feature of the gallery.

You can find all of the styles listed [here](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/attrs_attachment_gallery_activity.xml).<br/>
Some of these styles are applied directly to stock Android components. These accept any attribute that is normally applicable to the given stock Android component. Others power Stream UI components and have custom made styled attributes.

- `streamUiAttachmentGalleryCloseButtonStyle`: Styles the button used to close the gallery. Accepts all `ImageView` attributes.
- `streamUiAttachmentGalleryTitleStyle`: Styles the title seen in the header. Accepts all `TextView` attributes.
- `streamUiAttachmentGalleryDateStyle`: Styles the date section in the header. Accepts all `TextView` attributes.
- `streamUiAttachmentGalleryActionsMenuStyle`: Styles the button used to activate the options menu. Accepts all `ImageView` attributes.
- `streamUiAttachmentGalleryBottomBarImageCountStyle`: Styles the text displaying the number of all media attachments contained within the message and the position of the one currently being viewed. Accepts all `TextView` attributes.
- `streamUiAttachmentGalleryBottomBarLeftIconStyle`: Styles the left icon inside the bottom bar. By default it shows a share icon. Accepts all `ImageView` attributes.
- `streamUiAttachmentGalleryBottomBarRightIconStyle`: Styles the right icon inside the bottom bar. By default it shows a tiled icon that opens the menu. Accepts all `ImageView` attributes.
- `streamUiAttachmentGalleryOptionsStyle`: Styles the actions menu. Accepts custom Stream attributes, all of which are listed [here](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/attrs_attachment_options_view.xml).
- `streamUiAttachmentGalleryVideoAttachmentsStyle`: Styles how video attachments are displayed in the main viewing area of the gallery. Accepts custom Stream attributes, all of which are listed [here](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/attrs_attachment_gallery_video_attachments.xml).
- `streamUiMediaAttachmentGridViewStyle`: Styles how the media overview menu is displayed. Accepts custom Stream attributes, all of which are listed [here](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/attrs_media_attachment_grid_view.xml).

#### Creating styles to change the appearance

Let's start customizing our screen by styling the play button displayed over videos so that it features a flat design.

1. Create a style which changes the way the play button is displayed in the main viewing area of the gallery:

```xml
<style name="CustomAttachmentGalleryVideoAttachmentStyle">
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconTint">@color/stream_ui_literal_white</item>
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconCornerRadius">5dp</item>
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconBackgroundColor">@color/stream_ui_literal_black</item>
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconPaddingTop">5dp</item>
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconPaddingBottom">5dp</item>
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconPaddingStart">5dp</item>
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconPaddingEnd">5dp</item>
    <item name="streamUiAttachmentGalleryViewMediaPlayVideoIconElevation">0dp</item>
</style>
```

2. Create a style which changes the way the play button is displayed in the overview:

```xml
<style name="CustomMediaAttachmentGridView">
    <item name="streamUiMediaAttachmentGridViewPlayVideoButtonIcon">@drawable/stream_ui_ic_play</item>
    <item name="streamUiMediaAttachmentGridViewPlayVideoIconElevation">3dp</item>
    <item name="streamUiMediaAttachmentGridViewPlayVideoIconPaddingTop">2dp</item>
    <item name="streamUiMediaAttachmentGridViewPlayVideoIconPaddingBottom">2dp</item>
    <item name="streamUiMediaAttachmentGridViewPlayVideoIconPaddingStart">3dp</item>
    <item name="streamUiMediaAttachmentGridViewPlayVideoIconPaddingEnd">2dp</item>
    <item name="streamUiMediaAttachmentGridViewPlayVideoIconCornerRadius">24dp</item>
    <item name="streamUiMediaAttachmentGridViewPlayVideoIconBackgroundColor">@color/stream_ui_literal_white</item>
    <item name="streamUiMediaAttachmentGridViewImagePlaceholder">@drawable/stream_ui_picture_placeholder</item>
</style>
```

3. Use the newly created style to create a custom Stream theme:

```xml
<style name="CustomStreamUiTheme" parent="@style/StreamUiTheme">
    <item name="streamUiMediaAttachmentGridViewStyle">@style/CustomMediaAttachmentGridView</item>
    <item name="streamUiAttachmentGalleryVideoAttachmentsStyle">@style/CustomAttachmentGalleryVideoAttachmentStyle</item>
</style>
```

4. Add the custom theme to your attachment gallery Activity theme, along with a few lines that make the status and navigation bars look prettier:

```xml
<style name="CustomAttachmentGalleryTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar">
    <!-- Style the status and navigation bars -->
    <item name="android:windowLightStatusBar">?attr/isLightTheme</item>
    <item name="android:statusBarColor">@android:color/transparent</item>
    <item name="android:navigationBarColor">@android:color/transparent</item>

    <!-- Add custom stream theme you've created -->
    <item name="streamUiTheme">@style/CustomStreamUiTheme</item>
</style>
```

5. Finally, override the default gallery theme in your app's manifest:

```xml
<activity
   android:name="io.getstream.chat.android.ui.feature.gallery.AttachmentGalleryActivity"
   android:theme="@style/CustomAttachmentGalleryTheme"
   tools:replace="android:theme" />
```

These few simple steps result in the following UI:

| Light Mode                                                                                                                                | Dark Mode                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| ![Attachment gallery customization example light](@chat-sdk/android/v6-latest/_assets/attachment_gallery_customization_example_light.png) | ![Attachment gallery customization example dark](@chat-sdk/android/v6-latest/_assets/attachment_gallery_customization_example_dark.png) |

As you can see, we've replaced the elevated white circular play button shown in the first few screenshots with a flat black squircle.

We can customize other aspects of the gallery, for instance by removing menu options which we want to restrict from the user.<br/>
Let's remove the download and delete options:

1. Create a style that disables the previously mentioned options:

```xml
<style name="CustomAttachmentGalleryOptionsStyle">
    <item name="streamUiDeleteEnabled">false</item>
    <item name="streamUiSaveMediaEnabled">false</item>
</style>
```

2. Add it to the custom Stream theme we've created in the previous example:

```xml
<style name="CustomStreamUiTheme" parent="@style/StreamUiTheme">
    <item name="streamUiMediaAttachmentGridViewStyle">@style/CustomMediaAttachmentGridView</item>
    <item name="streamUiAttachmentGalleryVideoAttachmentsStyle">@style/CustomAttachmentGalleryVideoAttachmentStyle</item>
    <!-- Add the custom options style to the custom theme -->
    <item name="streamUiAttachmentGalleryOptionsStyle">@style/CustomAttachmentGalleryOptionsStyle</item>
</style>
```

Which gives the options menu the following appearance:

| Light                                                                                                                                             | Dark                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| ![Attachment gallery customization example light](@chat-sdk/android/v6-latest/_assets/attachment_gallery_customization_example_options_light.png) | ![Attachment gallery customization example dark](@chat-sdk/android/v6-latest/_assets/attachment_gallery_customization_example_options_dark.png) |

Now you have the ability to make the gallery feel like an organic part of your app.

---

This page was last updated at 2025-08-15T14:15:38.201Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/android/ui/utility-components/attachment-gallery/](https://getstream.io/chat/docs/sdk/android/ui/utility-components/attachment-gallery/).