# Channels Screen
`ChannelsScreen` is a ready-to-use screen that displays the current user's channel list. It's typically the first screen users see after logging in.
**Included features:**
- **Header** with user avatar, customizable title, and action button
- **Search** for channels by name or message content
- **Channel list** with pagination, unread counts, and last message preview
- **Long-press menu** for channel actions (leave, delete, mute, view info)
- **Empty state** when no channels match filters
- **Loading state** while fetching channels
For most apps, `ChannelsScreen` provides everything you need. If you require a different layout or want to embed the channel list in a more complex UI, use the individual [bound components](/chat/docs/sdk/android/v6/compose/channel-components/channel-list/) instead.
## Usage
To use `ChannelsScreen`, you just need to call it within `setContent()` in your `Activity` or `Fragment`:
```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
ChatTheme {
ChannelsScreen()
}
}
}
```
The `ChannelsScreen` can be used without any parameters, but we advise that you pass in the title of your app, as well as the action handlers.
This small snippet will produce a fully working solution, as shown in the image below.
|  |  |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
To get a better feel of the component, you'll want to customize its actions.
## Handling Actions
When it comes to action handlers exposed in the `ChannelsScreen` signature you have access to the following:
```kotlin
fun ChannelsScreen(
// ... ViewModel factory and UI customization
onHeaderActionClick: () -> Unit = {},
onHeaderAvatarClick: () -> Unit = {},
onChannelClick: (Channel) -> Unit = {},
onSearchMessageItemClick: (Message) -> Unit = {},
onViewChannelInfoAction: (Channel) -> Unit = {},
onBackPressed: () -> Unit = {},
)
```
There are several action handlers you can use with the `ChannelsScreen`:
- `onHeaderActionClick`: Handler for the default header trailing icon click action.
- `onHeaderAvatarClick`: Handler for the clicks on the user avatar in the header.
- `onChannelClick`: Handler for a `Channel` being clicked.
- `onSearchMessageItemClick`: Handler for a `Message` being clicked.
- `onViewChannelInfoAction`: Handler for the **View info** action selected in `SelectedChannelMenu`.
- `onBackPressed`: Handler for the system back button being clicked.
All of these actions are empty by default, but if you want to customize them, you can do the following:
```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
ChatTheme {
ChannelsScreen(
onChannelClick = {
// Open messages screen
},
onSearchMessageItemClick = {
// Open messages screen and scroll to the message
},
onHeaderActionClick = {
// Handle the header click action
},
onHeaderAvatarClick = {
// Handle the header avatar clicks
},
onViewChannelInfoAction = {
// Show UI to view more channel info
},
onBackPressed = { finish() }
)
}
}
}
```
## Overriding the ViewModels
In case you want to control the logic when using the `ChannelsScreen`, you can do so by providing a `ChannelViewModelFactory` that you use to build the respective ViewModels yourself.
Here's an example:
```kotlin
class ChannelsActivity : AppCompatActivity() {
// 1
private val factory by lazy {
ChannelViewModelFactory(
chatClient = ChatClient.instance(),
querySort = QuerySortByField.descByName("last_updated"),
filters = null
)
}
// 2
private val listViewModel: ChannelListViewModel by viewModels { factory }
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
ChannelsScreen(
viewModelFactory = factory // 3
)
}
}
}
```
There are a few steps here that allow you to override and control the ViewModels:
1. You create the `ChannelViewModelFactory` yourself, which lets you describe the data and configuration used to build the `ViewModel`s.
2. You lazily create an instance of the `ChannelListViewModel`. This means that you'll either build the `ViewModel` first and then pass it to the Compose component, or your Compose component will create the `ViewModel` and you'll get access to it here.
3. You pass in the factory to the `ChannelsScreen`, which allows this connection to happen.
The `ViewModel`s should be the same and you should easily be able to react to things like item clicks, changes in the state and more.
Even though `ChannelsScreen` offers limited customization, you can still achieve a unique look and feel by modifying `ChatTheme` parameters.
For more information on how to do so read our [Customizing Components](/chat/docs/sdk/android/v6/compose/general-customization/chat-theme/) page.
## Customization
`ChannelsScreen` is one of our **screen components** and as such it doesn't offer much customization. As with any component, you can customize the content theme and styling by wrapping it in the [`ChatTheme`](/chat/docs/sdk/android/v6/compose/general-customization/chat-theme/).
When it comes to UI and behavior customization in the `ChannelsScreen` signature you have access to the following:
```kotlin
fun ChannelsScreen(
viewModelFactory: ChannelViewModelFactory = ChannelViewModelFactory(),
viewModelKey: String? = null,
title: String = "Stream Chat",
isShowingHeader: Boolean = true,
searchMode: SearchMode = SearchMode.None,
// ... Action handlers
)
```
- `viewModelFactory`: The factory that you build yourself, if you want access to `ViewModels` for custom behavior. This lets you control not just the way the `ViewModel`s are built, but also their lifecycle, as you can share them between components. You can also customize its parameters to affect the behavior of the screen.
- `viewModelKey`: An optional key to differentiate between multiple `ChannelListViewModel` instances. Useful when you have multiple `ChannelsScreen` components in your app.
- `title`: The title of the `ChannelListHeader`.
- `isShowingHeader`: Flag that controls whether the `ChannelListHeader` is shown. `true` by default.
- `searchMode`: The search mode to be configured for the screen. `SearchMode.None` by default. It can take the following values:
- `SearchMode.None`: Hides the search input.
- `SearchMode.Channels`: Shows a search input that allows users to search for channels by name.
- `SearchMode.Messages`: Shows a search input that allows users to search for messages across channels.
## ChannelViewModelFactory Configuration
The `ChannelViewModelFactory` provides configuration options for customizing the behavior of the channels screen. Here's a complete overview of all available parameters:
```kotlin
ChannelViewModelFactory(
// Query configuration
querySort = QuerySortByField.descByName("last_updated"),
filters = null,
// Pagination limits
channelLimit = 30,
memberLimit = 30,
messageLimit = 1,
// Features
isDraftMessageEnabled = false,
// Search
messageSearchSort = null,
)
```
### Query Configuration
- `querySort`: Defines the sorting order for channels. Defaults to `QuerySortByField.descByName("last_updated")`, which sorts channels by their last update time in descending order (most recently updated first). You can also sort by `last_message_at`.
- `filters`: Optional filters to apply when querying channels. When `null` (default), all channels the user is a member of are shown. Use `Filters` to create complex filter conditions.
Example with custom sorting and filtering:
```kotlin
ChannelViewModelFactory(
querySort = QuerySortByField.descByName("last_message_at"),
filters = Filters.and(
Filters.eq("type", "messaging"),
Filters.`in`("members", listOf(currentUserId))
)
)
```
### Pagination Limits
- `channelLimit`: Number of channels to fetch per page. Defaults to `30`.
- `memberLimit`: Number of members to fetch for each channel when loading the channel list. Defaults to `30`.
- `messageLimit`: Number of messages to fetch for each channel when loading the channel list. Defaults to `1`.
### Feature Parameters
- `isDraftMessageEnabled`: When `true`, enables draft message support. Draft messages are shown in the channel list instead of the last message preview when present. Defaults to `false`.
### Search Configuration
- `messageSearchSort`: Defines the sort order for message search results. When `null` (default), the server-side default ordering is used. Pass a `QuerySorter` to control the order in which matching messages appear.
Example with custom message search sort:
```kotlin
ChannelViewModelFactory(
messageSearchSort = QuerySortByField.ascByName("created_at")
)
```
### Advanced Parameters
- `chatEventHandlerFactory`: Factory for creating `ChatEventHandler` instances that handle real-time events for the channel list. For more details, see [Channels State and Filtering](/chat/docs/sdk/android/v6/client/guides/channels/).
If you want to build a completely custom channel list, follow our [Custom Channel List](/chat/docs/sdk/android/v6/compose-cookbook/custom-channel-list/) Cookbook recipe.
---
This page was last updated at 2026-04-17T17:33:31.525Z.
For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/android/v6/compose/channel-components/channels-screen/](https://getstream.io/chat/docs/sdk/android/v6/compose/channel-components/channels-screen/).