# Channel List Header
`ChannelListHeaderView` is a component that shows the title of the channels list, the current connection status, the avatar of the current user, and provides an action button that can be used to create a new conversation. It is designed to be displayed at the top of the channels screen of your app.
| Light Mode | Dark Mode |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|  |  |
## Usage
To use `ChannelListHeaderView`, include it in your XML layout as shown below:
```xml
```
`ChannelListHeaderView` is designed to work with `ChannelListHeaderViewModel`. The basic setup of the ViewModel and connecting it with the View can be done in the following way:
```kotlin
// Instantiate the ViewModel
val viewModel: ChannelListHeaderViewModel by viewModels()
// Bind the ViewModel with ChannelListHeaderView
viewModel.bindView(channelListHeaderView, viewLifecycleOwner)
```
```java
// Instantiate the ViewModel
ChannelListHeaderViewModel viewModel = new ViewModelProvider(this).get(ChannelListHeaderViewModel.class);
// Bind it with ChannelListHeaderView
ChannelListHeaderViewModelBinding.bind(viewModel, channelListHeaderView, getViewLifecycleOwner());
```
The `ChannelListHeaderViewModel::bindView` function provides all the logic of subscribing to data emitted by the ViewModel. By default, the ViewModel will make the View display the avatar of the currently logged-in user as well as the "Waiting for network" state when needed.
The `ChannelListHeaderViewModel` exposes the following properties that you can observe:
- `currentUser: LiveData` - The user who is currently logged in.
- `connectionState: LiveData` - The state of the connection (Connected, Connecting, or Offline).
| Light Mode | Dark Mode |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
|  |  |
## Handling Actions
The View displays an avatar and action button by default. You can set listeners to handle when users click on these elements:
```kotlin
channelListHeaderView.setOnActionButtonClickListener {
// Handle action button click
}
channelListHeaderView.setOnUserAvatarClickListener {
// Handle user avatar click
}
channelListHeaderView.setOnTitleClickListener {
// Handle title click
}
channelListHeaderView.setOnTitleLongClickListener {
// Handle title long click
}
```
```java
channelListHeaderView.setOnActionButtonClickListener(() -> {
// Handle action button click
});
channelListHeaderView.setOnUserAvatarClickListener(() -> {
// Handle user avatar click
});
channelListHeaderView.setOnTitleClickListener(() -> {
// Handle title click
});
channelListHeaderView.setOnTitleLongClickListener(() -> {
// Handle title long click
});
```
## Customization
### Using XML Attributes
The appearance of `ChannelListHeaderView` can be conveniently modified using its XML attributes.
```xml
```
The example above hides the avatar view, makes the title text bold, and sets the drawable of the action button to a custom icon.
| Before | After |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
|  |  |
The available XML attributes allow you to customize:
- **User Avatar**: `streamUiShowUserAvatar` - Show or hide the user avatar.
- **Online Title**: `streamUiOnlineTitleTextSize`, `streamUiOnlineTitleTextColor`, `streamUiOnlineTitleTextFont`, `streamUiOnlineTitleFontAssets`, `streamUiOnlineTitleTextStyle` - Customize the title text when online.
- **Offline Title**: `streamUiOfflineTitleTextSize`, `streamUiOfflineTitleTextColor`, `streamUiOfflineTitleTextFont`, `streamUiOfflineTitleFontAssets`, `streamUiOfflineTitleTextStyle` - Customize the title text when offline.
- **Progress Bar**: `streamUiShowOfflineProgressBar`, `streamUiOfflineProgressBarTint` - Show or hide the offline progress bar and customize its color.
- **Action Button**: `streamUiShowActionButton`, `streamUiActionButtonIcon`, `streamUiActionBackgroundTint` - Show or hide the action button and customize its appearance.
- **Separator**: `streamUiChannelListSeparatorBackgroundDrawable` - Customize the separator at the bottom of the header.
A full list of available XML attributes is available [here](https://github.com/GetStream/stream-chat-android/blob/main/stream-chat-android-ui-components/src/main/res/values/attrs_channel_list_header_view.xml).
### Customizing the Header Programmatically
The `ChannelListHeaderView` also provides several methods to customize its appearance programmatically:
- `setUser(user: User)` - Sets the user whose avatar will be displayed.
- `setOnlineTitle(title: String)` - Sets the title text when online.
- `showOnlineTitle()` - Displays the online title.
- `showConnectingTitle()` - Displays the connecting title.
- `showOfflineTitle()` - Displays the offline title.
---
This page was last updated at 2026-03-10T10:49:18.928Z.
For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/android/ui/channel-components/channel-list-header/](https://getstream.io/chat/docs/sdk/android/ui/channel-components/channel-list-header/).