chat_toolkit 1.7.0
chat_toolkit: ^1.7.0 copied to clipboard
A comprehensive and customizable chat widget toolkit for Flutter applications with message handling, real-time updates, and extensive customization options.
Chat Toolkit #
A customizable chat widget toolkit for Flutter. It gives you a ready-to-use chat UI with message grouping, async sending with retry, and an optimized scrolling list.
Contents #
Features #
| Area | What you get |
|---|---|
| UI | Chat widget with message list, input field, profiles, timestamps, read-only mode |
| Messages | Sender/receiver messages, extensible message elements, loading / failed / success states |
| Sending | Async dispatch with result stream, retry for failed messages, blocked-message handling |
| Context menu | Long press menu on bubbles, configured separately for sender and receiver |
| Grouping & sorting | Automatic message grouping (customizable), tie-breaker sorting for identical timestamps |
| Scrolling | New-message notification, load older messages, only visible groups are built, optional entrance animation |
Installation #
dependencies:
chat_toolkit: ^latest_version
flutter pub get
Quick start #
import 'package:flutter/material.dart';
import 'package:chat_toolkit/chat_toolkit.dart';
class ChatScreen extends StatefulWidget {
const ChatScreen({super.key});
@override
State<ChatScreen> createState() => _ChatScreenState();
}
class _ChatScreenState extends State<ChatScreen> {
final chatController = ChatController();
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Chat')),
body: Chat(
chatController: chatController,
configuration: ChatConfiguration(),
),
);
}
@override
void dispose() {
chatController.dispose();
super.dispose();
}
}
Usage #
Add a message #
chatController.addMessage(
SenderMessage(
name: 'You',
timestamp: DateTime.now().toIso8601String(),
elements: [TextMessageElement(text: 'Hello!')],
),
);
Message types #
// Outgoing
SenderMessage(
name: 'User Name',
timestamp: DateTime.now().toIso8601String(),
elements: [TextMessageElement(text: 'Hello world!')],
);
// Incoming
ReceiverMessage(
id: 'unique_id',
name: 'Other User',
timestamp: DateTime.now().toIso8601String(),
elements: [TextMessageElement(text: 'Hi there!')],
);
Send asynchronously #
final result = await chatController.dispatchMessage(
message,
onDispatch: (message) async {
final response = await yourApiCall(message);
return response; // processed message, or null if it failed
},
);
While sending, the bubble shows a loading state. On failure it shows retry / delete buttons.
Handle blocked messages and failed bubbles #
// Throw from onDispatch when the server blocks the message.
// The bubble is removed and no retry entry is created.
onDispatch: (message) async {
final response = await yourApiCall(message);
if (response.isBlocked) {
throw MessageBlockedException(code: response.code, message: response.text);
}
return response.message;
},
// Delete button on a failed bubble.
// The message is removed only if this returns true.
Chat(
chatController: chatController,
onDeleteFailedMessage: (message) async => await yourDeleteApi(message),
)
// Make a failed message loaded from history retryable.
chatController.registerFailedMessage(messageId, onDispatch);
Load older messages #
Chat(
chatController: chatController,
onScrollToTop: () async {
final olderMessages = await fetchOlderMessages();
chatController.appendMessages(olderMessages);
},
)
Listen to events #
chatController.dispatchResultStream.listen((result) {
if (result.isSuccess) {
print('Message sent');
} else {
print('Failed: ${result.exception}');
}
});
chatController.newReceiveMessageStream.listen((message) {
print('New message: ${message.id}');
});
Customization #
Appearance #
Chat(
chatController: chatController,
configuration: ChatConfiguration(
senderAlignment: ChatAlignment.end,
bubbleConfiguration: BubbleConfiguration(
maxWidth: 280,
profileBuilder: (context, name) => CustomProfile(name),
senderBubbleBuilder: (context, child) => CustomBubble(child),
),
),
)
Bubble context menu #
Long pressing a bubble opens a context menu — a held touch, or a held mouse button on desktop and web. Sender and receiver menus are configured separately, so each side can offer different entries.
Chat(
chatController: chatController,
configuration: ChatConfiguration(
bubbleConfiguration: BubbleConfiguration(
menuConfiguration: BubbleMenuConfiguration(
senderItemsBuilder: (context, request) => [
BubbleMenuItem(
label: 'Copy',
icon: const Icon(Icons.copy, size: 18),
onSelected: (context, request) => copy(request.message),
),
BubbleMenuItem(
label: 'Resend',
enabled: request.message.isFailed,
onSelected: (context, request) =>
chatController.retryMessage(request.message),
),
BubbleMenuItem(
label: 'Delete',
textStyle: const TextStyle(color: Colors.red),
onSelected: (context, request) =>
chatController.removeMessageEverywhere(request.message),
),
],
receiverItemsBuilder: (context, request) => [
BubbleMenuItem(label: 'Reply', onSelected: reply),
BubbleMenuItem(label: 'Report', onSelected: report),
],
),
),
),
)
A side without an items builder has no menu, and returning an empty list suppresses the menu for that message (useful while it is still sending).
request is a BubbleMenuRequest carrying the message, isSender, the pointer's globalPosition, and the bubble's bubbleRect in global coordinates.
Animation
The default menu uses Material's popup transition (fade + vertical expand). animationStyle retimes it:
BubbleMenuConfiguration(
animationStyle: const AnimationStyle(
duration: Duration(milliseconds: 150),
curve: Curves.easeOutCubic,
reverseDuration: Duration(milliseconds: 100),
),
// or AnimationStyle.noAnimation to show it instantly
)
For a different kind of transition (scale out of the bubble, blurred backdrop, spring), present your own menu with a handler — see below. request.bubbleRect and request.globalPosition give you the anchor.
Custom menu UI
For a bottom sheet, dialog, or your own overlay, use a handler instead of items. It replaces the default popup menu for that side.
BubbleMenuConfiguration(
receiverMenuHandler: (context, request) async {
await showModalBottomSheet(
context: context,
builder: (context) => MyMenuSheet(message: request.message),
);
},
)
Options
| Option | Description |
|---|---|
senderItemsBuilder / receiverItemsBuilder |
Entries of the default menu, per side |
senderMenuHandler / receiverMenuHandler |
Custom menu presentation, per side (takes precedence over items) |
enableLongPress |
Open on long press (default: true) |
enableHapticFeedback |
Vibrate when the menu opens (default: true) |
color, surfaceTintColor, shape, elevation, constraints |
Styling of the default popup menu |
animationStyle |
Duration / curve of the default menu's transition (AnimationStyle.noAnimation to disable) |
Right click is deliberately not a trigger: on Flutter web it would open the browser's own context menu at the same time. A held mouse button works as a long press, so desktop and web users still get the menu.
Custom message elements #
class ImageElement extends MessageElement {
final String url;
const ImageElement({required this.url});
@override
Widget toWidget(BuildContext context) => Image.network(url);
@override
MessageElement copyWith() => ImageElement(url: url);
}
Sorting messages with identical timestamps #
final controller = ChatController(
customSortCallback: (a, b) => a.id.compareTo(b.id),
);
Message grouping #
By default, consecutive messages are grouped when they have the same sender, the same name, and the same minute. Add your own condition on top of that:
final controller = ChatController(
additionalGroupCondition: (group, message) {
return group.messages.length < 10; // e.g. at most 10 messages per group
},
);
API reference #
ChatConfiguration #
| Option | Description |
|---|---|
senderAlignment |
Message alignment (start / end) |
padding |
List padding (default: horizontal 30) |
customInputField |
Custom input field widget |
newReceiveMessageNotificationBuilder |
Builder for the new-message notification |
bubbleConfiguration |
Bubble appearance settings |
readOnlyWidget |
Widget shown in read-only mode |
messageAppearAnimationDuration |
Entrance animation for newly added messages (default: off) |
messagesStartAtTop |
In a reversed chat, show a few messages from the top instead of the bottom (default: false) |
BubbleConfiguration #
| Option | Description |
|---|---|
profileBuilder |
Profile widget builder |
senderBubbleBuilder |
Sender bubble builder |
receiverBubbleBuilder |
Receiver bubble builder |
timeBuilder |
Timestamp builder |
loadingWidget |
Loading indicator |
maxWidth |
Maximum bubble width |
menuConfiguration |
Long press context menu, per side |
ChatController #
| Option | Description |
|---|---|
customSortCallback |
Tie-breaker for messages with identical timestamps |
additionalGroupCondition |
Extra condition for joining a message group |
Requirements #
- Flutter SDK >= 3.24.0
- Dart SDK ^3.12.0
Dependencies: gap, intl, super_sliver_list, uuid.
Contributing #
Contributions are welcome. Feel free to open a pull request.
License #
MIT License. See LICENSE.
Support #
For issues, feature requests, or questions, visit the GitHub repository.