Skip to main content

chat_toolkit 1.5.1 copy "chat_toolkit: ^1.5.1" to clipboard
chat_toolkit: ^1.5.1 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
Grouping & sorting Automatic message grouping (customizable), tie-breaker sorting for identical timestamps
Scrolling New-message notification, load older messages, only visible groups are built

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),
    ),
  ),
)

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

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

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.

7
likes
0
points
1.23k
downloads

Publisher

unverified uploader

Weekly Downloads

A comprehensive and customizable chat widget toolkit for Flutter applications with message handling, real-time updates, and extensive customization options.

Repository (GitHub)
View/report issues

License

unknown (license)

Dependencies

flutter, gap, intl, super_sliver_list, uuid

More

Packages that depend on chat_toolkit