Skip to main content

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, you just need to add ChannelListFragment to your Activity or Fragment:

class MyChannelListActivity : AppCompatActivity() {

override fun onCreate(savedInstanceState: Bundle?) {

if (savedInstanceState == null) {
.replace(, ChannelListFragment.newInstance())

Alternatively, you can simply start ChannelListActivity from the SDK to achieve similar result with a single line of code:


This small snippet will produce a fully working solution, as shown in the image below.

The Channel List Screen Component

Handling Actions#

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

class MyChannelListActivity : AppCompatActivity(),
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 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.


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

  • setFragment: Sets 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 avatar click listener:
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 {

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

Did you find this page helpful?