Build a Flutter Chat App With The Stream SDK
Build a mobile chat application similar to Facebook Messenger or WhatsApp using Stream’s Flutter Chat SDK library. By the end of this tutorial, you will have a fully functioning mobile app with support for rich messages, reactions, threads, image uploads and videos.
We are also going to show how easy it is to make customizations to the built-in widgets that ship with this library and their styling.




Flutter Chat SDK Setup
Confused about "Flutter Chat SDK Setup"?
Let us know how we can improve our documentation:
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.
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
Confused about "Add Stream Chat to your Flutter application"?
Let us know how we can improve our documentation:
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:
- The Dart API client is initialized with your API Key
- The current user is set by calling connectUser on the client
- 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:
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
andStreamMessageInput
If you now run the simulator you will see a single channel UI.
Rich Messaging
Confused about "Rich Messaging"?
Let us know how we can improve our documentation:
The widgets we have dropped on our code earlier provide several rich interactions out of the box.
- URL previews
- User mentions
- Chat commands
- Image uploads
Multiple Conversations
Confused about "Multiple Conversations"?
Let us know how we can improve our documentation:
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:
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
Confused about "Customize Channel Preview"?
Let us know how we can improve our documentation:
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.
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
Confused about "Message Threads"?
Let us know how we can improve our documentation:
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:
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
Confused about "Custom Message"?
Let us know how we can improve our documentation:
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.
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
Confused about "Custom Styles"?
Let us know how we can improve our documentation:
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:
- Initialize the StreamChatTheme from your existing MaterialApp style
- 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.
Congratulations
Confused about "Congratulations"?
Let us know how we can improve our documentation:
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.
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.
Nick Chen
Head of Product, Kiddom