Skip to main content
Version: v6

Channel List Screen

The easiest way to set up a screen that shows the active user's channels and give them the ability to search for a specific channel is to use one of the following components:

  • ChannelListFragment: A Fragment that represents a self-contained channel list screen.
  • ChannelListActivity: An Activity that is just a thin wrapper around ChannelListFragment.

The ChannelListFragment contains these four inner components:


Fragments and Activities representing self-contained screens are easy to use. They allow you to explore the SDK's features in a breeze, however, they offer limited customization.


To use the channel list screen, simply start ChannelListActivity from the SDK:


This single line of code will produce a fully working solution, as shown in the image below.

The Channel List Screen Component

Alternatively, you can achieve the same result by adding ChannelListFragment from the SDK to your Fragment or Activity:

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android=""
android:layout_height="match_parent" />
class MyChannelListActivity : AppCompatActivity(R.layout.fragment_container) {

override fun onCreate(savedInstanceState: Bundle?) {
if (savedInstanceState == null) {
.replace(, ChannelListFragment.newInstance())

Next, let's see how to handle actions on the screen.

Handling Actions

To handle actions supported by ChannelListFragment you have to implement corresponding click listeners in the parent Fragment or Activity:

class MyChannelListActivity : AppCompatActivity(R.layout.fragment_container),
ChannelListFragment.SearchResultClickListener {

override fun onCreate(savedInstanceState: Bundle?) {
// Add ChannelListFragment to the layout

override fun onUserAvatarClick() {
// Handle header avatar click

override fun onActionButtonClick() {
// Handle header action button click

override fun onChannelClick(channel: Channel) {
// Handle channel click

override fun onSearchResultClick(message: Message) {
// Handle search result click

These are the main click listeners you can use with the ChannelListFragment:

  • HeaderActionButtonClickListener: Click listener for the right button in the header. Not implemented by default.
  • HeaderUserAvatarClickListener: Click listener for the left button in the header represented by the avatar of the current user. Not implemented by default.
  • ChannelListItemClickListener: Click listener for channel item clicks. Navigates to MessageListActivity by default.
  • SearchResultClickListener: Click listener for search result items. Navigates to MessageListActivity by default.


The channel list screen component offers limited customization. The ChannelListFragment exposes a builder with the following methods:

  • setFragment: Sets a custom channel list Fragment. The Fragment must be a subclass of ChannelListFragment.
  • customTheme: Custom theme for the screen.
  • showHeader: Whether the header is shown or hidden.
  • showSearch: Whether the search input is shown or hidden.
  • headerTitle: Header title. "Stream Chat" by default.

Other than that, you can use inheritance for further customization as shown in the example below:

class CustomChannelListFragment : ChannelListFragment() {

override fun setupChannelListHeader(channelListHeaderView: ChannelListHeaderView) {
// Customize channel list header view

// For example, set a custom listener for the avatar
channelListHeaderView.setOnUserAvatarClickListener {
// Handle avatar click

override fun setupChannelList(channelListView: ChannelListView) {
// Customize channel list view

override fun setupSearchInput(searchInputView: SearchInputView) {
// Customize search input field

override fun setupSearchResultList(searchResultListView: SearchResultListView) {
// Customize search result list

override fun getFilter(): FilterObject? {
// Provide custom filter
return null

override fun getSort(): QuerySorter<Channel> {
// Provide custom sort
return super.getSort()

class CustomChannelListActivity : ChannelListActivity() {

override fun createChannelListFragment(): ChannelListFragment {
return ChannelListFragment.newInstance {

Then you need to add CustomChannelListActivity to your AndroidManifest.xml, create an Intent for it using the ChannelListActivity.createIntent() method, and finally start the Activity:

context = context,
activityClass =

Fragments and Activities representing self-contained screens can be styled using the options described in the theming guide.

Did you find this page helpful?