Build a Flutter Chat App With The Stream SDK

Flutter Chat SDK Setup

First of all we need to setup our new project and have a working development environment for Flutter. If you do not have Flutter or an IDE configured to work with it, we highly recommend following the Install and Set up an editor steps from the official documentation.

Please make sure you are using the latest version of Flutter from the stable channel:

Now open your IDE and start a new Flutter application called awesome_flutter_chat. If you are using Android Studio (recommended) make sure to create the project as a Flutter application and keep all default settings.

Set up demo messaging app in Android Studio

Next step is to add stream_chat_flutter to your dependencies, to do that just open pubspec.yaml and add it inside the dependencies section.

Stream has several packages that you can use to integrate chat into your application.

In this tutorial, we will be using the stream_chat_flutter package which contains pre-built UI elements for you to use.

If you need more control over the UI, stream_chat_flutter_core provides bare-bones implementation with logic and controllers that you can use to build your own UI.

For the most possible control, the stream_chat package allows access to the low-level client.

Add Stream Chat to your Flutter application

Let’s start by adding the top-level Chat widget and initialize your application. There are three important things to notice that are common to all Flutter application using StreamChat:

  1. The Dart API client is initialized with your API Key
  2. The current user is set by calling connectUser on the client
  3. The client is then passed to the top-level StreamChat widget

StreamChat is an inherited widget and must be the parent of all Chat related widgets, we will cover later how you can leverage the inherited widget APIs to build more advanced customizations to your application.

Let’s open the main.dart file and replace its content with this:

Tutorial Screen

Please note that while Flutter can be used to build both mobile and web applications; in this tutorial we are going to focus on mobile, make sure when running the app you use a mobile device.

Let's have a look at what we've built so far:

  • We set up the Chat Client with the API key
  • We set the the current user for Chat with StreamChatClient.connectUser and a pre-generated user token
  • We make StreamChat the root Widget of our application
  • We create a single ChannelPage widget under StreamChat with three widgets: StreamChannelHeader, StreamMessageListView and StreamMessageInput

If you now run the simulator you will see a single channel UI.

Rich Messaging

The widgets we have dropped on our code earlier provide several rich interactions out of the box.

  1. URL previews
  2. User mentions
  3. Chat commands
  4. Image uploads

Multiple Conversations

Most chat applications handle more than just one single conversation. Apps like Facebook Messenger, Whatsapp and Telegram allows you to have multiple one to one and group conversations.

Let’s find out how we can change our application chat screen to display the list of conversations and navigate between them.

Note: the SDK uses Flutter’s Navigator to move from one route to another, this allows us to avoid any boiler-plate code. Of course you can take total control of how navigation works by customizing widgets like Channel and ChannelList.

Let’s open again main.dart and make some small changes:

Chat List Screen

If you run your application now, you will see that the first screen shows a list of conversations, you can open each by tapping and go back to the list.

Every single widget involved in this UI can be customized or swapped with your own.

The ChannelListPage widget retrieves the list of channels based on a custom query and ordering as defined in the instance of the StreamChannelListController. In this case we are showing the list of channels the current user is a member and we order them based on the time they had a new message. StreamChannelListView handles pagination and updates automatically out of the box when new channels are created or when a new message is added to a channel.

Customize Channel Preview

So far you’ve learned how to use the default widgets. The library has been designed with composition in mind and to allow all common customizations to be very easy. This means that you can change any component in your application by swapping the default widgets with the ones you build yourself.

Let’s see how we can make some changes to the SDK’s UI components. We will start by changing how channel tiles are shown in the channel list and include the number of unread messages for each.

We're passing a custom widget to itemBuilder in the StreamChannelListView, this will override the default StreamChannelListTile and allows you to create one yourself.

Channel Preview Screen

There are a couple interesting things we do in this widget:

  • Instead of creating a whole new style for the channel name, we inherit the text style from the parent theme (StreamChatTheme.of) and only change the color attribute
  • We loop over the list of channel messages to search for the first not deleted message(channel.state.messages)
  • We retrieve the count of unread messages from channel.state

Message Threads

Stream Chat supports message threads out of the box. Threads allows users to create sub-conversations inside the same channel.

Using threaded conversations is very simple and mostly a matter of plugging the StreamMessageListView to another widget that renders the widget. To make this simple, such a widget only needs to build StreamMessageListView with the parent attribute set to the thread’s root message.

Here’s how the builder and the change to the channel page looks like:

Message Threads Screen

Now we can open threads and create new ones as well, if you long press a message you can tap on Reply and it will open the same ThreadPage.

Custom Message

Customizing how messages are rendered is another very common use-case that the SDK supports easily.

Replace the built-in message component with your own is done by passing it as a builder function to the StreamMessageListView widget.

The message builder function will get the usual context argument as well as the message object and its position inside the list.

Custom Message Screen

If you look at the code you can see that we use StreamChat.of to retrieve the current user so that we can style own messages in a different way.

Since custom widgets and builders are always children of StreamChat or part of a channel, you can use StreamChat.of, StreamChannel.of and StreamTheme.of to use the API client directly or to retrieve outer scope needed such as messages from the channel.state.

The last parameter of the messageBuilder function is the message widget that is already built by the SDK. This is useful if you want to modify the widget that is already built by the SDK using defaultMessageWidget.copyWith() and passing the parameters you want to override.

Custom Styles

The Flutter SDK comes with a fully designed set of widgets which you can customize to fit with your application style and typography. Changing the theme of Chat widgets works in a very similar way that MaterialApp and Theme do.

Out of the box all chat widgets use their own default styling, there are two ways to change the styling:

  1. Initialize the StreamChatTheme from your existing MaterialApp style
  2. Construct a custom theme ad provide all the customizations needed

Let’s first see how we can re-use an existing material design style to change the styling of your chat UI.

First we create a new Material Theme and pick green as swatch color. The theme is then passed to MaterialApp as usual.

With the next step we create a new StreamChatTheme from the green theme we just created. After saving the app, you will see the UI will update several widgets to match with the new color.

Let’s now do something more complex such as changing the message color posted by the current user. You can perform these more granular style changes using StreamChatTheme.copyWith.


We hope that you enjoyed this tutorial. By using Stream’s Chat Components, you and your team will be able to get your Flutter application, with chat, up and running in minutes.

Now that you’ve completed the tutorial on Stream Chat, you can build anything chat related with our components. If you have a use-case that doesn’t quite seem to work, or simply have questions, please don’t hesitate to reach out here.

Final Thoughts

In this chat app tutorial we built a fully functioning Flutter messaging app with our Flutter SDK component library. We also showed how easy it is to customize the behavior and the style of the Flutter chat app components with minimal code changes.

Both the chat SDK for Flutter and the API have plenty more features available to support more advanced use-cases such as push notifications, content moderation, rich messages and more. Please check out our React tutorial too. If you want some inspiration for your app, download our free chat interface UI kit.

Give us Feedback!

Did you find this tutorial helpful in getting you up and running with Flutter for adding chat to your project? Either good or bad, we’re looking for your honest feedback so we can improve.

Kiddom logo

We’ve been going at lightspeed to build more communication functionality into Kiddom. The only way to achieve this in four months was to do a chat integration with Stream because we needed to do it reliably and at scale.

Head of Product, Kiddom profile picture

Nick Chen

Head of Product, Kiddom

Next Steps

Create your free Stream account to try out all our Chat product has to offer. No commitment or credit card required. If you want a custom plan or have questions, we are eager to talk with you.

Activity Feeds

Build any kind of feed without the headache of scalability or reliability of your feeds.

Learn more about $ Activity Feeds


Available 99.999% uptime SLAs and industry-leading security to power the world's largest apps.

Learn more about $ Enterprise