Stream Chat Flutter: three layers, and a version 10 that redrew the widgets

Three layers, and the choice between them

The SDK is layered, and each package builds on the one before it, which is the fastest way to understand what to install.

`stream_chat` is the low-level client, the LLC, a pure Dart package that wraps the Stream Chat API. It has no UI and no opinion about one, and the README says to use it directly if you want to build your own UI and state layer.

`stream_chat_flutter_core` provides the business logic, the controllers and the builders needed to integrate Stream Chat into a Flutter app, and it ships no UI of its own. It is the layer for a team with its own design system that does not want to own the message list, the channel list and the composer.

`stream_chat_flutter` is the full UI SDK, a set of reusable and customizable widgets on top of the core and the low-level client, and it is the recommended starting point for most apps. The reasoning in the README is blunt: unless your UI is completely different from the common industry standard, you should be able to customize the built-in widgets to match your needs.

Two more packages sit alongside. `stream_chat_persistence` provides a Drift-backed persistence client for offline storage and plugs into any of the packages above, and `stream_chat_localizations` provides the localizations for the UI SDK.

The mixing is explicitly allowed, and it is the part that makes the layering useful rather than ceremonial. It is common to use the UI SDK for most screens and drop down to the low-level client for specific operations, so a team can adopt the widgets and then replace the one screen that has to look different.

The repository is a monorepo built with Melos, the packages live in the `packages` directory, and the configuration and top-level commands live in `melos.yaml`.

V10 rebuilt theming around a ThemeExtension

Version 10 is described as a major update to the Stream Chat Flutter SDK, and the changes fall into three groups: a modern redesign, a unified design system, and an improved developer experience.

The redesign covers the components a user touches most. The channel list, the message list, the composer, the reactions, the avatars and the media viewer all have a cleaner, more polished default look.

The design system is the part with consequences for an application. Design tokens, which the README lists as colors, typography, spacing and icons, are now consistent across all Stream SDK platforms. Theming is rebuilt around `StreamTheme`, a Flutter `ThemeExtension` registered on `MaterialApp.theme`. The choice of a `ThemeExtension` is the detail worth knowing, because that is the mechanism Flutter provides for a library to add its own typed theme values to the application's theme, so an application can override a single token and have it apply everywhere, rather than overriding each widget separately.

The developer experience changes are structural. `StreamComponentFactory` is a single customization entry point that replaces the scattered builder slots that previously lived on each widget, which is the classic fix for a widget library that grew one injection point per component until nobody could remember them all. Cross-platform name alignment means APIs and component names now match the iOS, Android, React and React Native counterparts, with `StreamMessageComposer` and `StreamChannelListItem` given as examples. A team that also maintains the same product on another platform gets the same vocabulary, and a developer moving between the SDKs does not have to relearn what a thing is called.

There is a cookbook as well, described as new task-oriented recipes for common customizations, and a V10 migration guide with the full list of breaking changes and upgrade instructions. The breaking changes are the part to budget time for, because renaming is invisible until the compiler stops compiling.

What the widget set actually covers

The feature list is long, and the way to read it is as a list of the features a chat product is expected to have on day one.

There is rich media message support with Markdown rendering, reactions, threads and quoted replies, typing and read indicators, and channel and message lists. The composer supports autocomplete triggers, with `@` for mentions and `/` for commands, which is the point where a chat product stops being a list of text bubbles and starts being a command surface. Uploads cover image, video and file, with previews and a built-in media gallery viewer, and there are voice messages, polls, drafts, pinned messages and message reminders.

The message actions context menu lists reply, edit, copy, pin, delete, flag, mute and block, which is the set of permissions a chat product has to expose and a moderation product has to enforce. Message search and Giphy support are there as well.

Three features stand out as newer expectations. AI assistant streaming responses put a model inside the message list. Push notifications cover Firebase, APN and Huawei, which is a deliberate spread across the three mobile push stacks a Flutter application is likely to meet. Offline storage with optimistic updates means the interface can accept a message before the server has confirmed it, which is a state machine rather than a flag, and it is where the `stream_chat_persistence` package with its Drift backend comes in.

There is also static and live location sharing, and localization through the separate localizations package.

The repository carries a `sample_app` that is described as a fully functional messenger built with `stream_chat_flutter`, and it is the recommended reference when wiring things up in an application of your own.

Getting started: melos bootstrap and the sample app

The setup instruction is short, because a monorepo of this size needs its own bootstrap step.

melos bootstrap

That command has to be run after cloning the project, and it is the Melos equivalent of installing dependencies for every package in the monorepo and wiring the local packages to each other. The badge in the README states that the repository is maintained with Melos.

From there the README points at the Flutter Chat tutorial as the best place to start, since it teaches how to use the SDK and shows how to make frequently required changes. Every package folder also includes a fully functional `example` with setup instructions, which is the pattern that makes a monorepo of five packages navigable: a reader who wants to know what the low-level client can do opens that package and runs its example.

For more applications and demos, the README points at the `GetStream/flutter-samples` repository. The `sample_app` directory in this repository is the reference implementation, and it is a full messenger rather than a snippet.

Two things are worth setting up before writing any code. The first is an API key, obtained by registering for a trial on the Stream site, because the SDK talks to the hosted service. The second is the cost question, and the README answers it in a section titled Free for Makers. Stream is free for most side and hobby projects, and the qualification is defined precisely: the project or company needs to have fewer than five team members and under $10,000 in monthly revenue. Anything above that is on the pricing page.

That is a business constraint rather than a technical one, but it is stated in the README rather than buried, and it is the kind of threshold that decides whether the SDK is a dependency or an operating cost.

Versioning, and the two release lines in flight

The versioning policy is written down, and it has one clause that a consumer of a UI kit should read carefully.

All of the Stream Chat packages follow semantic versioning. Bug fixes and behaviour improvements cause a patch version bump, new features ship with an increased minor version, and incompatible API changes cause a major version increase. Then there is the exception: occasionally the SDK can include visual changes, in whitespace, color and sizing, in minor versions, as the default look of the widgets is continuously improved.

That clause matters more than it sounds. A UI kit whose minor releases can change the appearance of its widgets is not a drop-in dependency in the strict sense, because a minor bump can change what the user sees. Teams that treat upgrades as a review exercise, with screenshots, will find that a minor bump of the chat SDK can produce a pull request that touches nothing in their own code and changes the product.

The release history in the repository shows two lines in flight at once. The recent tags are v10.5.0 from 2026-09-30, v9.31.0 from the same day, and v9.30.0 from 2026-09-22. The 9.x line and the 10.x line are being released side by side, which is what a major version migration looks like while it is still being rolled out, and it means a team can stay on the older line while it plans the migration.

The repository itself is organised for that kind of work. Alongside `melos.yaml`, `pubspec.yaml` and the packages directory there is a `migrations/` directory, a `tools/` directory, a `docs/` directory and the `sample_app/`. The conventions are documented in separate root files: `STYLE_GUIDE.md`, `TESTING.md`, `EFFECTIVE_DART_DOC.md`, `FLUTTER_BLOCKED.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `SECURITY.md`, and there is a `.fvmrc` file that pins the Flutter version the project is developed against.

The licence is not classified by GitHub under a standard name, so the `LICENSE` file in the root is the text to read, and it is worth doing that before a commercial application depends on it.

Where this SDK is the wrong tool

The limits are not in the widgets, they are in the model.

The first is that the SDK is a client for somebody else's service. The data lives in Stream Chat, the API is Stream's, and the persistence package stores a local copy of somebody else's data model. That is a perfectly good arrangement for a social product that wants chat and nothing else, and a poor one for a company whose users own their conversations and whose compliance team needs the data in a system it controls. The low-level client does not change that, it only removes the widgets.

The second is the cost shape. The free tier is generous for a small team and then it is not, and the threshold is a team size and a revenue number rather than a message count, so a company that crosses five people has to look at the pricing page even if its chat volume is trivial. A team that expects to grow into the paid tier should model that cost before it adopts the SDK rather than after.

The third is the version 10 transition itself. The redesign, the new theming model, the new component factory and the cross-platform renaming are all improvements, and all of them are breaking changes, and they land in a repository that also has a 9.x line being maintained in parallel. Migrating a large application onto v10 is a project, not an upgrade.

The alternative, for a team that wants its own chat interface, is to build on `stream_chat`, the pure Dart client, and write the state layer and the widgets. That is more work and it removes the widget set, the offline support, the push integration and the localisation, so it only makes sense when the interface is genuinely different from the industry standard, which is the same condition the README itself sets for not using the UI package.

The alternative for a team that does not want a hosted backend at all is a different product, and that is where the SDK stops being an option rather than being a limitation. Nothing in this repository stores messages anywhere else, and the persistence package is an offline cache of a remote conversation, not a database of record.

Editorial conclusion

The Stream Chat Flutter SDK fits a Flutter team that wants a complete chat experience, with threads, uploads, reactions, push notifications and offline support, in the platform's own idiom, and that accepts building on a hosted backend rather than running one. It is the wrong choice for a product that needs its chat data in its own systems, because the SDK is a client for somebody else's service, and it is a poor fit for a team that wants full control of the interface, where the low-level Dart client is the honest starting point rather than the UI package. Before adopting it, read the V10 migration guide, because the breaking changes span names, theming and the customization entry point, and read the pricing note in the README, since the free tier for makers is defined by a team size and a monthly revenue limit rather than by usage.

Frequently asked questions

Official sources

1. GetStream/stream-chat-flutter on GitHub
2. Issues
3. Project website
4. README
5. Releases