In this tutorial, we will use the Stream SDK for Flutter to add chat capabilities to our Flutter apps. The SDK for Flutter is available along with the docs.
This tutorial has been checked to work on:
- Flutter 3.32 (or latest)
- Stream Chat SDK for Flutter 10.0.0 (or latest)
By the end of this tutorial, we will have an application that has:
- Stream Chat Client integrated and set up.
- Set up multiple conversations in the app.
- Customize the preview for channels.
- Provide custom UI for the messages.
For inspiration, this repository contains sample Flutter projects to demonstrate the use of Stream Chat SDK for Flutter.
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:
12flutter channel stable flutter upgrade
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.
12345dependencies: flutter: sdk: flutter stream_chat_flutter: ^10.0.0
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:
- 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:
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101import 'package:flutter/material.dart'; import 'package:stream_chat_flutter/stream_chat_flutter.dart'; void main() async { /// Create a new instance of [StreamChatClient] passing the apikey obtained from your /// project dashboard. final client = StreamChatClient( 'b67pax5b2wdq', logLevel: Level.INFO, ); /// Set the current user. In a production scenario, this should be done using /// a backend to generate a user token using our server SDK. /// Please see the following for more information: /// https://getstream.io/chat/docs/flutter-dart/tokens_and_authentication/ await client.connectUser( User(id: 'tutorial-flutter'), 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidHV0b3JpYWwtZmx1dHRlciJ9.S-MJpoSwDiqyXpUURgO5wVqJ4vKlIVFLSEyrFYCOE1c', ); /// Creates a channel using the type `messaging` and `flutterdevs`. /// Channels are containers for holding messages between different members. To /// learn more about channels and some of our predefined types, checkout our /// our channel docs: https://getstream.io/chat/docs/flutter-dart/creating_channels/ /// /// We pass the current user inside `extraData.members` so the channel is /// created with them already added — this is what makes the channel appear /// in the member-filtered query we use in the next step. final channel = client.channel( 'messaging', id: 'flutterdevs', extraData: const { 'members': ['tutorial-flutter'], }, ); /// `.watch()` is used to create and listen to the channel for updates. If the /// channel already exists, it will simply listen for new events. await channel.watch(); runApp( MyApp( client: client, channel: channel, ), ); } class MyApp extends StatelessWidget { const MyApp({ super.key, required this.client, required this.channel, }); /// Instance of [StreamChatClient] we created earlier. This contains /// information about our application and connection state. final StreamChatClient client; /// The channel we'd like to observe and participate in. final Channel channel; Widget build(BuildContext context) { return MaterialApp( builder: (context, widget) { return StreamChat( client: client, child: widget, ); }, home: StreamChannel( channel: channel, child: const ChannelPage(), ), ); } } /// Displays the list of messages inside the channel. class ChannelPage extends StatelessWidget { const ChannelPage({super.key}); Widget build(BuildContext context) { final colorScheme = context.streamColorScheme; return Scaffold( backgroundColor: colorScheme.backgroundApp, appBar: const StreamChannelHeader(), body: Column( children: <Widget>[ const Expanded( child: StreamMessageListView(), ), StreamMessageComposer(), ], ), ); } }

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.
Launch the app in
Runmode. The dependencies emit a lot of signals and debugger captures these events and pauses the execution of the code.
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.connectUserand a pre-generated user token - We create a
messagingchannel with idflutterdevs, passing the current user insideextraData.membersso they're a member from the moment the channel is created - this is what makes the channel appear in the member-filtered query we use in the next step - We make
StreamChatthe root Widget of our application - We create a single ChannelPage widget under
StreamChatwith three widgets:StreamChannelHeader,StreamMessageListViewandStreamMessageComposer - We paint the
Scaffoldbackground withcontext.streamColorScheme.backgroundAppso the screen blends with the SDK's theme tokens
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.
- URL previews
- User mentions
- Chat commands
- 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
StreamChannelandStreamChannelListView.
Let's open again main.dart and make some small changes:
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116import 'package:flutter/material.dart'; import 'package:stream_chat_flutter/stream_chat_flutter.dart'; void main() async { final client = StreamChatClient( 'b67pax5b2wdq', logLevel: Level.INFO, ); await client.connectUser( User(id: 'tutorial-flutter'), 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoidHV0b3JpYWwtZmx1dHRlciJ9.S-MJpoSwDiqyXpUURgO5wVqJ4vKlIVFLSEyrFYCOE1c', ); runApp( MyApp( client: client, ), ); } class MyApp extends StatelessWidget { const MyApp({ super.key, required this.client, }); /// Instance of [StreamChatClient] we created earlier. This contains /// information about our application and connection state. final StreamChatClient client; Widget build(BuildContext context) { return MaterialApp( builder: (context, child) => StreamChat( client: client, child: child, ), home: const ChannelListPage(), ); } } /// Displays the list of channels for the current user. class ChannelListPage extends StatefulWidget { const ChannelListPage({super.key}); State<ChannelListPage> createState() => _ChannelListPageState(); } class _ChannelListPageState extends State<ChannelListPage> { late final _listController = StreamChannelListController( client: StreamChat.of(context).client, filter: Filter.in_( 'members', [StreamChat.of(context).currentUser!.id], ), channelStateSort: const [SortOption.desc('last_message_at')], limit: 20, ); void dispose() { _listController.dispose(); super.dispose(); } Widget build(BuildContext context) { final colorScheme = context.streamColorScheme; return Scaffold( backgroundColor: colorScheme.backgroundApp, appBar: const StreamChannelListHeader(), body: StreamChannelListView( controller: _listController, onChannelTap: (channel) { Navigator.of(context).push( MaterialPageRoute( builder: (context) { return StreamChannel( channel: channel, child: const ChannelPage(), ); }, ), ); }, ), ); } } /// Displays the list of messages inside the channel. class ChannelPage extends StatelessWidget { const ChannelPage({super.key}); Widget build(BuildContext context) { final colorScheme = context.streamColorScheme; return Scaffold( backgroundColor: colorScheme.backgroundApp, appBar: const StreamChannelHeader(), body: Column( children: <Widget>[ const Expanded( child: StreamMessageListView(), ), StreamMessageComposer(), ], ), ); } }

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.
We use StreamChannelListHeader as the appBar to render a title, the current user's avatar, and the connection state - matching the look of the StreamChannelHeader we used on the channel page.
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 StreamChannelListItem and allows you to create one yourself.
Add the collections dependency to your project.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293/// Displays the list of channels for the current user. class ChannelListPage extends StatefulWidget { const ChannelListPage({super.key}); State<ChannelListPage> createState() => _ChannelListPageState(); } class _ChannelListPageState extends State<ChannelListPage> { late final _listController = StreamChannelListController( client: StreamChat.of(context).client, filter: Filter.in_( 'members', [StreamChat.of(context).currentUser!.id], ), channelStateSort: const [SortOption.desc('last_message_at')], limit: 20, ); void dispose() { _listController.dispose(); super.dispose(); } Widget build(BuildContext context) { final colorScheme = context.streamColorScheme; return Scaffold( backgroundColor: colorScheme.backgroundApp, appBar: const StreamChannelListHeader(), body: StreamChannelListView( controller: _listController, itemBuilder: _channelTileBuilder, onChannelTap: (channel) { Navigator.of(context).push( MaterialPageRoute( builder: (context) { return StreamChannel( channel: channel, child: const ChannelPage(), ); }, ), ); }, ), ); } Widget _channelTileBuilder(BuildContext context, List<Channel> channels, int index, StreamChannelListItem defaultChannelListItem) { final channel = channels[index]; final lastMessage = channel.state?.messages.reversed.firstWhereOrNull( (message) => !message.isDeleted, ); final subtitle = lastMessage == null ? 'nothing yet' : lastMessage.text!; final unreadCount = channel.state?.unreadCount ?? 0; final opacity = unreadCount > 0 ? 1.0 : 0.5; return ListTile( onTap: () { Navigator.push( context, MaterialPageRoute( builder: (_) => StreamChannel( channel: channel, child: const ChannelPage(), ), ), ); }, leading: StreamChannelAvatar( channel: channel, ), title: StreamChannelName( channel: channel, textStyle: StreamChannelListItemTheme.of(context).titleStyle?.copyWith( color: context.streamColorScheme.textPrimary.withValues(alpha: opacity), ), ), subtitle: Text(subtitle), trailing: unreadCount > 0 ? CircleAvatar( radius: 10, child: Text(unreadCount.toString()), ) : const SizedBox(), ); } }
You may need to import the collections package for firstWhereOrNull to work. If you see an error, import:
1import 'package:collection/collection.dart';

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 channel-list item theme (
StreamChannelListItemTheme.of(context).titleStyle) and only change the color attribute, dimming it for read channels viacontext.streamColorScheme.textPrimary.withValues(alpha: opacity) - 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?.unreadCount
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:
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576/// Displays the list of messages inside the channel. class ChannelPage extends StatelessWidget { const ChannelPage({super.key}); Widget build(BuildContext context) { final colorScheme = context.streamColorScheme; return Scaffold( backgroundColor: colorScheme.backgroundApp, appBar: const StreamChannelHeader(), body: Column( children: <Widget>[ Expanded( child: StreamMessageListView( threadBuilder: (_, parentMessage) => ThreadPage( parent: parentMessage!, ), ), ), StreamMessageComposer(), ], ), ); } } /// Displays the thread replies for a parent message. class ThreadPage extends StatefulWidget { const ThreadPage({ super.key, required this.parent, }); /// The root message this thread is replying to. final Message parent; State<ThreadPage> createState() => _ThreadPageState(); } class _ThreadPageState extends State<ThreadPage> { late final _controller = StreamMessageComposerController( message: Message(parentId: widget.parent.id), ); void dispose() { _controller.dispose(); super.dispose(); } Widget build(BuildContext context) { final colorScheme = context.streamColorScheme; return Scaffold( backgroundColor: colorScheme.backgroundApp, appBar: StreamThreadHeader( parent: widget.parent, ), body: Column( children: <Widget>[ Expanded( child: StreamMessageListView( parentMessage: widget.parent, ), ), StreamMessageComposer( messageComposerController: _controller, ), ], ), ); } }

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.
Replacing the built-in message component with your own is done by passing a builder function as the messageBuilder parameter of the StreamMessageListView widget.
The builder receives the usual BuildContext, the Message being rendered, and a StreamMessageItemProps object that already has every list-level callback wired in. You can use the props as-is to build the default message item, or call .copyWith(...) to tweak individual fields before rendering.
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758/// Displays the list of messages inside the channel with a custom message widget. class ChannelPage extends StatelessWidget { const ChannelPage({super.key}); Widget build(BuildContext context) { final colorScheme = context.streamColorScheme; return Scaffold( backgroundColor: colorScheme.backgroundApp, appBar: const StreamChannelHeader(), body: Column( children: <Widget>[ Expanded( child: StreamMessageListView( messageBuilder: _messageItemBuilder, ), ), StreamMessageComposer(), ], ), ); } Widget _messageItemBuilder( BuildContext context, Message message, StreamMessageItemProps defaultProps, ) { final isCurrentUser = StreamChat.of(context).currentUser!.id == message.user!.id; final textAlign = isCurrentUser ? TextAlign.right : TextAlign.left; final color = isCurrentUser ? Colors.blueGrey : Colors.blue; return Padding( padding: const EdgeInsets.all(5), child: DecoratedBox( decoration: BoxDecoration( border: Border.all( color: color, ), borderRadius: const BorderRadius.all( Radius.circular(5), ), ), child: ListTile( title: Text( message.text!, textAlign: textAlign, ), subtitle: Text( message.user!.name, textAlign: textAlign, ), ), ), ); } }

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
StreamChator part of a channel, you can useStreamChat.of,StreamChannel.ofandStreamChatTheme.ofto use the API client directly or to retrieve outer scope needed such as messages fromchannel.state.
The third parameter of the messageBuilder function - StreamMessageItemProps - describes everything the SDK would have used to render the default message item. If you want to keep most of the default behaviour and only tweak a few things, call defaultProps.copyWith(...) and pass the result to DefaultStreamMessageItem instead of returning a fully custom widget.
Custom Styles
The Flutter SDK ships fully designed widgets that you can theme to match your app. Theming works in two layers:
- Design tokens - a
StreamThemeregistered as aThemeDataextension. Set a brand color here and Stream derives the rest of its semantic palette from the swatch automatically. - Per-widget overrides - a
StreamChatThemeDatapassed toStreamChat.themeData. Tweak individual components without touching the rest of the theme.
We'll start with the brand color, then layer a granular override on top.
Register a StreamTheme extension on MaterialApp.theme (and a matching one on darkTheme) with a custom green brand swatch. Message bubbles, sending indicators, unread badges, the composer cursor, the audio recorder, and other accents all pick up the new tone in one go - we'll see the combined result alongside the per-widget override below.
123456789101112131415161718192021222324252627282930313233343536373839404142class MyApp extends StatelessWidget { const MyApp({ super.key, required this.client, }); /// Instance of [StreamChatClient] we created earlier. This contains /// information about our application and connection state. final StreamChatClient client; Widget build(BuildContext context) { final greenBrand = StreamColorSwatch.fromColor(Colors.green); final greenBrandDark = StreamColorSwatch.fromColor(Colors.green, brightness: Brightness.dark); return MaterialApp( theme: ThemeData( brightness: Brightness.light, extensions: [ StreamTheme( brightness: Brightness.light, colorScheme: StreamColorScheme.light(brand: greenBrand), ), ], ), darkTheme: ThemeData( brightness: Brightness.dark, extensions: [ StreamTheme( brightness: Brightness.dark, colorScheme: StreamColorScheme.dark(brand: greenBrandDark), ), ], ), builder: (context, child) => StreamChat( client: client, child: child, ), home: const ChannelListPage(), ); } }
Now let's layer a per-widget override on top. StreamChatThemeData exposes a theme object for every Stream component; we'll tweak channelListItemTheme to give every channel a light green tint and bolder titles, reusing greenBrand.shade100 - the same swatch shade Stream uses to paint outgoing message bubbles - so the channel list and the message list share the same green tone.
Build the customTheme inside build() and pass it to StreamChat via the themeData argument. The same pattern works for any other Stream component: provide the per-component *ThemeData you want to override and Stream merges it on top of the defaults.
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849class MyApp extends StatelessWidget { const MyApp({ super.key, required this.client, }); /// Instance of [StreamChatClient] we created earlier. This contains /// information about our application and connection state. final StreamChatClient client; Widget build(BuildContext context) { final greenBrand = StreamColorSwatch.fromColor(Colors.green); final greenBrandDark = StreamColorSwatch.fromColor(Colors.green, brightness: Brightness.dark); final customTheme = StreamChatThemeData( channelListItemTheme: StreamChannelListItemThemeData( titleStyle: const TextStyle(fontWeight: FontWeight.bold), backgroundColor: WidgetStateProperty.all(greenBrand.shade100), ), ); return MaterialApp( theme: ThemeData( brightness: Brightness.light, extensions: [ StreamTheme( brightness: Brightness.light, colorScheme: StreamColorScheme.light(brand: greenBrand), ), ], ), darkTheme: ThemeData( brightness: Brightness.dark, extensions: [ StreamTheme( brightness: Brightness.dark, colorScheme: StreamColorScheme.dark(brand: greenBrandDark), ), ], ), builder: (context, child) => StreamChat( client: client, themeData: customTheme, child: child, ), home: const ChannelListPage(), ); } }


Conclusion
In this tutorial, we built a Flutter application that exposes chat capabilities and allows you to connect to the Stream SDK, list the channels, view the channels, and send messages to the channel.
Now that you've completed the tutorial on Stream Chat, you can use our chat SDK to build your apps. If you have a use-case that doesn't quite seem to work, or simply have questions, please don't hesitate to reach out to our team.
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.

