NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev · #1159 most downloaded on pub.dev
Free and open-source chat SDK. Build fast, real-time apps and generative AI agents with a high-performance, customizable, cross-platform UI.
Last release 26 days ago
12 Sep 2026
Ships unpredictably
gaps range from 8 days to 9 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
125 releases · first in 2020
REFACTOR: replace flutter material imports with material_ui and update package dependencies (#893).
FIX: change definition of OnMessageSecondaryTapCallback.
One column per quarter.
FIX : handle null checks for message gesture callbacks in ChatMessage widget ( #861 ).
Update dependencies to latest, require min dart 3.8 and flutter 3.32. Migrate monorepo to pub workspaces.
Update dependencies to latest, require min dart 3.8 and flutter 3.32. Migrate monorepo to pub workspaces.
FIX: chat messages rebuilt after sending new message.
FIX: add content insertion configuration to Composer widget (#852).
…operations except update . This is not a breaking change, but if you'd like to use it, you can update your controller like so:
This release introduces two-sided pagination. You can now load newer messages using the new onStartReached callback, while onEndReached continues to work for older messages. For pagination to work correctly, messages should be inserted instantly, without animation.
To allow this and offer more granular control, a new optional animated parameter has been added to all controller operations except update. This is not a breaking change, but if you'd like to use it, you can update your controller like so:
insertMessage(Message message, {int? index}) // ❌
insertMessage(Message message, {int? index, bool animated = true}) // ✅
ChatOperation.insert(..., animated: animated) // add animated to insert operations
insertAllMessages(List<Message> messages, {int? index}) // ❌
insertAllMessages(List<Message> messages, {int? index, bool animated = true}) // ✅
ChatOperation.insertAll(..., animated: animated) // add animated to insertAll operations
removeMessage(Message message) // ❌
removeMessage(Message message, {bool animated = true}) // ✅
ChatOperation.remove(..., animated: animated) // add animated to remove operations
setMessages(List<Message> messages) // ❌
setMessages(List<Message> messages, {bool animated = true}) // ✅
ChatOperation.set(..., animated: animated) // add animated to set operationsAs an optional improvement, you can use this parameter to disable animations when clearing the chat, which is now the default behaviour in the example apps.
ChatOperation.set(messages, animated: messages.isEmpty ? false : animated) // inside the controller⚠️ There is a small potential breaking change: LoadMoreNotifier was updated for two-sided loading. If you used a custom LoadMore widget and used LoadMoreNotifier to measure its height, that logic has been removed as it was not used. Additionally, the internal property _isLoading is now _isLoadingOlder, and _isLoadingNewer has been added.
FIX: composer inputClearMode and fix custom editing controller.
FEAT: allow for top widgets within the bubble ( #814 ).
FEAT : link preview package ( #790 ).
FIX: new loadingBuilder for stream message.
Use utf8 codec to parse chinese symbols
Update dependencies. Requires Dart >= 2.15.1.
FIX: add sendButtonDisabled and sendButtonHidden #828.
onMessageTap and onMessageLongPress added BuildContext as a first parameter, so if you had something like this:
⚠️ Breaking Changes ⚠️
onMessageTap and onMessageLongPress added BuildContext as a first parameter, so if you had something like this:
void _handleMessageLongPress(
Message message, {
int? index,
LongPressStartDetails? details,
})replace it with this:
void _handleMessageLongPress(
BuildContext context,
Message message, {
int? index,
LongPressStartDetails? details,
})Updated dependencies (requires Dart >=2.14.0)
Fixed Android example. Thanks @rvndsngwn for reporting!
- FIX: update dependencies.
Update a dependency to the latest release.
- FIX: re-enable composer blur.
Revert meta upgrade, because pub.dev is analyzing code with an old Flutter version
FIX : introduce status field back ( #809 ).
Update to Flutter 2.5
Rename REGEX_EMAIL to regexEmail and REGEX_LINK to regexLink
All message builders will also provide isSentByMe and groupStatus now. Just pass
⚠️ Breaking Changes ⚠️
All message builders will also provide isSentByMe and groupStatus now. Just pass
{
required bool isSentByMe,
MessageGroupStatus? groupStatus,
}after the index param. It is fine not to use these fields if not needed.
Even though this is a patch release, it depends on flutter_chat_core , which introduced a small breaking change. I realized I didn’t bump flutter_chat…
⚠️ Breaking Changes ⚠️
Even though this is a patch release, it depends on flutter_chat_core, which introduced a small breaking change. I realized I didn’t bump flutter_chat_ui to a new minor version before publishing - sorry about that!
Fix is simple: if you have a custom ChatController, the set operation now requires a messages array.
Renamed LinkPreview → LinkPreviewData
⚠️ Breaking Changes ⚠️
Renamed LinkPreview → LinkPreviewData
LinkPreview.imageUrl → LinkPreviewData.image.url
Both LinkPreviewData.image.width and LinkPreviewData.image.height are now required
FIX: add physics param to the ChatAnimatedList(Reversed).
FIX: add emptyChatListWidget (#771).
FIX: scroll to bottom button appearance threshold #769 (#774).
Fix completer that never completes and add corsProxy parameter. Thanks @wer-mathurin for the PR!
Export getPreviewData to allow you to create your own implementation of a link preview.
FIX: list rebuilding when keyboard opens/closes.
Significantly overhauled for robust handling of asynchronous controller updates.
⚠️ Breaking Changes ⚠️
ChatAnimatedList Redesign:
update operation (ChatOperation.update) now requires the index of the message to be updated.ChatControllers, you MUST now fetch the most up-to-date message instance from your data source before passing it to remove or update operations. The internal list now relies on the exact object reference. Failing to do so will lead to errors or unexpected behavior. (See InMemoryChatController for an example of fetching the actual message before emitting ChatOperation.remove or ChatOperation.update).✨ Key Enhancements & Fixes ✨
ChatAnimatedList now uses an internal operation queue to serialize updates, preventing race conditions and resolving prior StreamOperation issues.ChatAnimatedList instances has been factorized, improving maintainability.insertAllMessages to ChatController and ChatAnimatedList for efficient bulk message additions with animations.ChatController's setMessages now uses an improved DiffUtil (with move support), fixing "out of bounds" errors during complex list updates.ChatAnimatedList to validate list operations and item positioning.FIX: hide attachmentButton if no there is no onAttachmentTap provided (#757).
- FIX: add audio message type.
- FIX: add video message type.
Chat controller methods have been renamed to avoid name conflicts with Riverpod.
⚠️ Breaking Changes ⚠️
Chat controller methods have been renamed to avoid name conflicts with Riverpod.
insert -> insertMessage
update -> updateMessage
remove -> removeMessage
set -> setMessages
FEAT: rename chat controller methods. (dc1bf57d)
FIX: improve documentation and add example.
Fix paddings for an empty preview data
Limit number of images parsed
Fix regex
- FIX: document public APIs.
Version 2.0.0 is a major update where we completely rebuilt the library. This version focuses on better performance, more customization options, and i
Enhanced pagination functionality for the ChatAnimatedList widget. If you utilize the paginationThreshold parameter, please refer to the comments in t
⚠️ Breaking Changes ⚠️
ChatAnimatedList widget. If you utilize the paginationThreshold parameter, please refer to the comments in the ChatAnimatedList widget implementation for detailed guidance.Message model to rename parentId to replyToMessageIdcreatedAt field is now optional in the message modelsending field has been removed from the message model; instead, you can set sending: true in the metadata of the Message model to achieve the same functionality.isOnlyEmoji property has been removed from the text message model; to indicate that a message contains only emojis, use isOnlyEmoji: true in the metadata of the text message.firstName and lastName fields in the User model have been consolidated into a single name field for improved simplicity.null have been removed. Instead, please use Colors.transparent, BorderRadius.zero, or TextStyle() to achieve the desired effect. Passing null will now use the standard configuration.⚠️ New Features ⚠️
headerWidget to the ChatMessage widget, enabling the display of a custom header for each message. You have the flexibility to control the header's position; wrap it with a Center widget for centering.sentMessageColumnAlignment, receivedMessageColumnAlignment, sentMessageRowAlignment, and receivedMessageRowAlignment for the ChatMessage widget. These allow for precise control over the positioning of leadingWidget, trailingWidget, topWidget, and bottomWidget. Ensure correct defaults are set for proper alignment, especially when using the topWidget.TextStreamMessage type to support text streamingtextStreamMessageBuilder to the Builders class to support text streaming UI widgetOther changes
MessageID and UserID typedefs to provide clearer context, while maintaining their underlying type as StringsRename ChatInputHeightNotifier to ComposerHeightNotifier
⚠️ Breaking Changes ⚠️
ChatInput to ComposerChatInputHeightNotifier to ComposerHeightNotifierinputBuilder to composerBuilderReplace status field with a computed getter that determines message state based on lifecycle timestamps (createdAt, deletedAt, sending, failedAt, sent
⚠️ Breaking Changes ⚠️
status field with a computed getter that determines message state based on lifecycle timestamps (createdAt, deletedAt, sending, failedAt, sentAt, deliveredAt, seenAt, updatedAt). This enables granular message history tracking and status transitions, matching the behavior of popular chat applications.overlay to hasOverlay in ImageMessageOther changes
intl package version for better compatibility with other Flutter packagesFileMessage support to the example projectindexed_db to idb_shim for improved cross-platform compatibility and better performancePackage requires intl package for date/time formatting
⚠️ Breaking Changes ⚠️
intl package for date/time formatting⚠️ New features ⚠️
Changed dependency from flutter_markdown to gpt_markdown for the FlyerChatTextMessage class
⚠️ Breaking Changes ⚠️
flutter_markdown to gpt_markdown for the FlyerChatTextMessage classonMessageTap callback now includes message index and tap up details - updated parameters to (Message item, {int? index, TapUpDetails? details})ChatInput, with default capitalization set to sentencesChatInput to create a newline instead of sending message
textInputAction: TextInputAction.send when configuring ChatInput through builderslocal.dart example for how to use builders to customize input behavior⚠️ New features ⚠️
ScrollToMessageMixin to enable programmatic scrolling in chat list:
scrollToMessage(messageId): Scrolls to a specific message by IDscrollToIndex(index): Scrolls to a message at a specific indexChatController instance🐛 Bug Fixes
Require Flutter 3.29 and Dart 3.7
⚠️ Breaking changes ⚠️
🐛 Bug Fixes
Changed signature of chatMessageBuilder to include isRemoved and groupStatus parameters.
⚠️ Breaking changes ⚠️
chatMessageBuilder to include isRemoved and groupStatus parameters.imageUrl to imageSource for the User model. Change is necessary to show that not only remote URLs are supported but also local assets.messageGroupingTimeoutInSeconds is now set via chatAnimatedListBuilder.⚠️ New features ⚠️
hintText to the ChatInput widget.chatMessageBuilder now returns isRemoved and groupStatus parameters. Group status returns information about message's position in the group. isRemoved is true if message is removed.leadingWidget and trailingWidget to the ChatMessage widget.Replaced user parameter with currentUserId (String) and resolveUser function
⚠️ Breaking Changes ⚠️
👥 User Management:
user parameter with currentUserId (String) and resolveUser functionresolveUser⚙️ API Changes:
ChatInputHeightNotifier.updateHeight() to setHeight()builders: chatAnimatedListBuilder: ... return ChatAnimatedList(scrollController: _scrollController)ChatInput widget🔄 Core Changes:
author (type User) is replaced with authorId (type String) for simpler user managementDateTime properties now use milliseconds instead of microseconds for JSON serialization🎨 Theme Simplification: Theme has been streamlined to 3 key parameters:
colors - Uses Material 3 semantic names (e.g. primary, onPrimary, secondary) making it easy to apply color schemestypography - Follows Flutter's TextTheme semantic naming conventionsshape - Controls border radius of all messages (rounded vs square messages)✨ New Features:
👨💻 Chat Experience:
📜 List Behavior Controls:
shouldScrollToEndWhenSendingMessage: Auto-scroll on message sendshouldScrollToEndWhenAtBottom: Auto-scroll when at bottominitialScrollToEndMode: Controls initial scroll behavior for non-reversed list. Because list is not reversed, you must scroll to the end to see latest messages. Available options:
none: No automatic scrolling, do nothinganimate: Smooth scroll to endjump: Instant scroll to end (wrong position or UI jumps are expected since Flutter does not know exact size of the list)🎯 Improvements:
⚠️ Contains breaking changes ⚠️
⚠️ Contains breaking changes ⚠️
⚠️ Contains breaking changes ⚠️
⚠️ Contains breaking changes ⚠️
⚠️ Requires Flutter ^3.19 and Dart ^3.3 ⚠️
delete(String key) – delete entriesupdateKey(String key, String newKey) – rename keys while keeping the dataCustomNetworkImage is now CachedNetworkImage and has been moved to the cross-cache packageset method for better flexibilitycustomMessageBuilder for building custom messagesoverlay parameter to ImageMessageImageMessageTheme (replacing imagePlaceholderColor)InputTheme (adding textFieldColor)ScrollToBottomThemeTextMessageThemeUploadProgressMixin for handling upload progress trackingChatInputHeightNotifierChatAnimatedList with:
topSliver and bottomSliver for custom widgets at the top or bottom of the chat (both scrollable)imageMessageTheme🚀 Exciting pre-release of v2! This version is a complete rewrite, focusing on extensibility, customizability, performance, and stability. 🛠️
v2! This version is a complete rewrite, focusing on extensibility, customizability, performance, and stability. 🛠️v2 or review the code, I'd love to hear your thoughts! 💬Last release of v1 and v2 is replacing it on main branch soon.
v1 and v2 is replacing it on main branch soon.code (single backtick).assets/). Thanks @thomers for the PR!While v2 is still in the works (unexpected blockers, see GitHub for progress) releasing a small patch update with improvements.
v2 is still in the works (unexpected blockers, see GitHub for progress) releasing a small patch update with improvements.preferPosition to scrollController.scrollToIndex. Thanks @chdo002 for the PR!isComposingRangeValid check from the input to hopefully fix send button that does not appear.usesSafeArea option to the inputOptions to be able to remove safe area backed inside the input.While v2 is still in the works (unexpected blockers, see GitHub for progress) releasing a small patch update with improvements.
v2 is still in the works (unexpected blockers, see GitHub for progress) releasing a small patch update with improvements.bubbleMargin property using ChatTheme. Thanks @ishchhabra for the PR!Remove defaultBubbleMessage from the bubbleBuilder as it breaks compatibility. If you need this please use previous release, this is the only change h
defaultBubbleMessage from the bubbleBuilder as it breaks compatibility. If you need this please use previous release, this is the only change here. Next should be v2.0.0 preview.Small patch release while 2.0.0 is still in the works.
messageMaxWidth to the theme. Thanks @bobz392 for the PR!isLeftStatus to display status on the left side of the message. Thanks @hndrr for the PR!bubbleBuilder. Thanks @asoap for the PR!messageWidthRatio to the chat. Thanks @elihaialgoaitech for the PR!customTypingWidget, customTypingIndicatorBuilder, typingWidgetBuilder and multiUserTextBuilder to the TypingIndicatorOptions. Thanks @phamconganh for the PR!Possibly last release before 2.0.0, which will be a complete re-write focused on extensibility, customizability, performance and stability.
slidableMessageBuilder. Thanks @leeyisoft for the PR!avatarBuilder now provides whole user object. Thanks @kahyoongho for the PR!- Update dependencies
Downgrade intl to make it compatible with latest Flutter
intl to make it compatible with latest Flutterautofocus to the InputOptions. Thanks @josefwilhelm for the PR!BREAKING CHANGE: nameBuilder now passes the whole user class, instead of just an id. Thanks @vintage for the PR!
nameBuilder now passes the whole user class, instead of just an id. Thanks @vintage for the PR!typingIndicatorOptions. Thanks @gtalha07 for the PR! Huge one!imageProviderBuilder. Thanks @marinkobabic for the PR!autocorrect and enableSuggestions to the InputOptions. By default, both values will be true. Thanks @g0dzillaa for the PR!keyboardType to the InputOptions. Thanks @Gramatton for the PR!Add audioMessageBuilder (no default implementation yet). Thanks @marinkobabic for the PR!
audioMessageBuilder (no default implementation yet). Thanks @marinkobabic for the PR!videoMessageBuilder (no default implementation yet).SystemMessage and systemMessageBuilder. Thanks @felixgabler for the PR!dateIsUtc to use UTC time for parsing dates inside the chat. Thanks @marinkobabic for the PR!TextMessageOptions. Thanks @jld3103 for the PR!listBottomWidget. Thanks @MaddinMade for the PR!useTopSafeAreaInset to the Chat widget, by default enabled on mobile platforms. Use it to disable top safe area inset. Thanks @jld3103 for reporting!BREAKING CHANGE: PreviewTapOptions -> TextMessageOptions
PreviewTapOptions -> TextMessageOptionsisTextMessageTextSelectable -> TextMessageOptions.isTextSelectableimageHeaders. Allows to pass headers to all images used in the chat. Thanks @marinkobabic for the PR!BREAKING CHANGE: Add InputOptions. onTextChanged, onTextFieldTap and sendButtonVisibilityMode are now under InputOptions class, just move the same val…
InputOptions. onTextChanged, onTextFieldTap and sendButtonVisibilityMode are now under InputOptions class, just move the same values to inputOptions: InputOptions().inputClearMode to InputOptions. Allows you to disable automatic text field clear on submit.textEditingController to InputOptions. Allows you to provide a custom editing contoller, but preferably use InputTextFieldController we export from the library, if you want to use it to programmatically clear text field or similar.keyboardDismissBehavior.TextMessageOptions. Thanks @felixgabler for the PR!Added an option to align sent bubbles to the right or left for RTL languages. Thanks @Faaatman for reporting! Use bubbleRtlAlignment.
bubbleRtlAlignment.customStatusBuilder. Thanks @skllll06 for the PR!Update documentation about opening files
Add bold, italic, strikethrough & code style to the input. Thanks @hareshgediya for the PR!
BREAKING CHANGE: copyWith on messages works differently (keeping previous values unless set to null), and sometimes casting to a specific message type…
copyWith on messages works differently (keeping previous values unless set to null), and sometimes casting to a specific message type is required. Please check your codebase if you're using it. Thanks!Fix emoji messages. Thanks @felixgabler for the PR!
SafeArea anymore. Thanks @AdrKacz for reporting!Your coding agent can read these notes before it upgrades. Set up the MCP server →