chatx library
Backend-agnostic, zero-dependency chat UI for Flutter.
chatx renders conversations; your app owns the data. Messages live in a ChatController and ChatView draws them, with the input bar, menus, reactions and everything else.
final controller = ChatController();
ChatView(
controller: controller,
currentUser: const ChatUser(id: 'me', name: 'Me'),
onSendMessage: (text, replyTo) {
controller.insert(TextMessage(
id: uuid(),
author: const ChatUser(id: 'me', name: 'Me'),
createdAt: DateTime.now(),
text: text,
replyToId: replyTo?.id,
status: MessageStatus.sending,
));
myBackend.send(text, replyTo);
},
)
Main pieces
- ChatController: the messages, typing users, replies, edits, selection, pins and attachments. Update it from your backend.
- ChatView: the complete conversation screen.
- ChatMessage: a sealed hierarchy. TextMessage for text and AI answers; ImageMessage, VideoMessage, FileMessage and VoiceMessage for media; PollMessage, SurveyMessage, EventMessage, ChecklistMessage, ProductMessage, PaymentMessage, LocationMessage, ContactMessage, CallMessage, CountdownMessage and StickerMessage for rich content; SystemMessage for notices; CustomMessage for your own types.
- ChatTheme: colors, text styles and bubble shapes, derived from your Material theme by default.
- ChatLocalizations: every string, in English, Spanish, Portuguese, French and German.
- Standalone widgets: ChatInput, ChatHeader, ChatSearchBar, ChatEmojiPicker, ChatText, ChatMediaGallery, ChatMemberList and ChatUserProfile.
The README has a guide for every feature, recipes for Firebase, Supabase, WebSockets and LLM streaming, and a testing guide: https://pub.dev/packages/chatx
Classes
- CallMessage
- An entry of the call log: a voice or video call and how it ended.
- ChatAttachment
- A file the user picked, waiting in the input until it is sent.
- ChatAvatar
- Circular avatar of a ChatUser.
- ChatBubbleBorder
- The shape of a chat bubble: a rounded rectangle with an optional tail.
- ChatController
- Holds the messages and typing state of one conversation.
- ChatEdit
- A previous version of an edited TextMessage.
- ChatEmojiPicker
- Emoji keyboard with categories, search and recently used emoji.
- ChatHeader
-
Title for an
AppBarwith avatar, name and live status. - ChatImage
- One image of an ImageMessage.
- ChatInput
- Message composer: a growing text field and a send button.
- ChatLinkPolicy
- Decides which links found in message text become tappable.
- ChatLinkPreview
- Metadata of a link shown as a card under a TextMessage.
- ChatLocalizations
- User-facing strings of chatx.
- ChatMediaGallery
- Every photo, video, file and link shared in a conversation, in three tabs. Newest first.
- ChatMemberList
- List of the members of a group, with roles and presence.
- ChatMessage
- Base type of every item shown in a conversation.
- ChatMessageAction
- An entry of the message menu.
- ChatMessageButton
- A button inside a TextMessage, typically sent by a bot.
- ChatMessageDetails
- Layout information about one message in the list.
- ChatProduct
- A product shown in a ProductMessage.
- ChatProfileAction
- An action button of ChatUserProfile.
- ChatPrompt
- A suggested prompt shown in the empty state of AI chats.
- ChatQuickReply
- A suggested answer shown as a chip above the input.
- ChatReaction
- One emoji reaction on a message, with the users who chose it.
- ChatReadReceipt
- A user who read a message, and when.
- ChatReasoning
- The reasoning an AI model showed before its answer.
- ChatRoleBadge
- Small badge with the role of a user: owner, admin or moderator.
- ChatScrollRequest
- A request to scroll to a message, sent by ChatController.scrollToMessage.
- ChatSearchBar
- Search field with a result counter and buttons to move between results.
- ChatSearchController
- Searches a conversation and moves between the results.
- ChatSelectionAction
- An action of the selection bar, applied to every selected message.
- ChatSource
- A source an AI answer cites. Shown as a numbered chip under the answer.
- ChatSticker
- A sticker that can be sent from the picker.
- ChatStickerPack
-
A group of stickers shown as a tab in
ChatEmojiPicker. - ChatSurveyResponse
- Answers to a SurveyMessage, keyed by SurveyQuestion.id.
- ChatSwipeAction
- Action performed when the user swipes a message bubble sideways.
- ChatText
- Renders message text with chatx's markdown subset.
- ChatTheme
- Visual overrides for chatx widgets.
- ChatThemeData
- Fully resolved visual values used by chatx widgets.
- ChatThreadSummary
- Summary of the thread started from a message.
- ChatToolCall
- A tool an AI model used while answering, such as a web search.
- ChatUser
- A participant in a conversation.
- ChatUserProfile
- Profile of a user: large avatar, name, role, status and actions.
- ChatView
- A complete conversation screen: message list plus input bar.
- ChatVoicePlayback
-
What your audio player is doing, reported to
ChatView.voicePlayback. - ChatWordFilter
- Hides offensive words by replacing their letters with asterisks.
- ChecklistItem
- An item of a ChecklistMessage.
- ChecklistMessage
- A shared to-do list that everyone in the chat can check.
- ChoiceQuestion
-
Pick one (or several) options. The answer is a
List<String>of choice IDs. - ContactMessage
- A shared contact card.
- CountdownMessage
- An announcement with a live countdown to endsAt.
- CustomMessage
-
A message rendered by your own
customMessageBuilder. - EventMessage
- An event invitation with RSVP: going, maybe or not going.
- FileMessage
- A file attachment: icon, name, size and optional upload progress.
- ImageMessage
- One to many images, shown as a grid, with an optional caption.
- LocationMessage
- A place on a map, or the live location of the author.
- MessageStatusIcon
- Small icon that represents a MessageStatus.
- NpsQuestion
-
Net Promoter Score: "How likely are you to recommend us?" from 0 to 10.
The answer is an
int. - PaymentMessage
- A request for money, or a payment the author sent.
- PollMessage
- A quick vote: one question with closed options to decide something now.
- PollOption
- One answer of a PollMessage.
- ProductMessage
- One product card, or a carousel when there are several products.
- RatingQuestion
-
Rate from 1 to max. The answer is an
int. - StickerMessage
- A sticker or GIF, shown large and without a bubble.
- SurveyChoice
- An option of a ChoiceQuestion.
- SurveyMessage
- A questionnaire with several questions to learn what people think.
- SurveyQuestion
- One question of a SurveyMessage.
- SystemMessage
- A centered, author-less notice such as "Ana joined the group".
- TextMessage
- A message whose text is rendered with chatx's markdown subset.
- TextQuestion
-
Free-text answer. The answer is a
String. - TypingDots
- Three bouncing dots, used for typing users and empty streaming messages.
- TypingIndicator
- Bubble that tells which users are typing.
- VideoMessage
- A video with a thumbnail, duration and play button.
- VoiceMessage
- A voice note: play button, waveform and duration.
Enums
- ChatAttachmentKind
- Kind of a ChatAttachment.
- ChatBubbleTail
- Where a chat bubble draws its tail.
- ChatButtonStyle
- Visual weight of a ChatMessageButton.
- ChatCallKind
- Kind of call in a CallMessage.
- ChatCallOutcome
- How a call ended.
- ChatConnectionState
-
Network state shown by
ChatView.connectionState. - ChatContactAction
- What the user chose on a contact card.
- ChatFeedback
- Rating of an AI answer.
- ChatMessageMenuStyle
- How the message menu is shown.
- ChatMessageMenuTrigger
- Which gesture opens the message menu.
- ChatPaymentAction
- What the user did with a PaymentMessage.
- ChatPaymentStatus
- State of a PaymentMessage.
- ChatRole
- Role of a user in a group, shown as a badge next to the name.
- ChatRsvp
- Answer to an EventMessage.
- ChatToolStatus
- State of a ChatToolCall.
- MessageStatus
- Delivery state of a message sent by the current user.
- RatingStyle
- How a RatingQuestion is drawn.
Typedefs
-
ChatAttachmentsCallback
= void Function(List<
ChatAttachment> attachments, String caption, ChatMessage? replyTo) - Called when the user sends the attachments waiting in the input, with the text of the field as a caption (may be empty).
- ChatAvatarBuilder = Widget Function(BuildContext context, ChatUser user)
-
Builds the avatar of
user. - ChatBubbleBuilder = Widget Function(BuildContext context, ChatMessageDetails details, Widget defaultBubble)
- Wraps or replaces the default bubble of a message.
- ChatCountLabel = String Function(int count)
- Formats a label that depends on a count.
- ChatCustomMessageBuilder = Widget Function(BuildContext context, CustomMessage message, ChatMessageDetails details)
-
Builds the content of a
CustomMessage. The result is placed inside the regular bubble. - ChatDateSeparatorBuilder = Widget Function(BuildContext context, DateTime day)
-
Builds the label between messages of different days.
dayis the local date at midnight. - ChatEditCallback = void Function(TextMessage message, String newText)
- Called when the user saves an edited message.
- ChatFeedbackCallback = void Function(TextMessage message, ChatFeedback? feedback)
-
Called when the user rates an AI answer.
nullremoves the rating. - ChatImageTapCallback = void Function(ImageMessage message, int index)
- Called when the user taps an image of an ImageMessage.
-
ChatInputBuilder
= Widget Function(BuildContext context, ValueChanged<
String> send, TextEditingController textController) - Builds the input bar.
-
ChatMessageActionsBuilder
= List<
ChatMessageAction> Function(BuildContext context, ChatMessage message, List<ChatMessageAction> defaults) -
Returns the menu entries for
message. - ChatNameLabel = String Function(String name)
- Formats a label that includes a user's display name.
- ChatPinCallback = void Function(ChatMessage message, bool pinned)
- Called when the user pins or unpins a message.
- ChatPollVoteCallback = void Function(PollMessage message, String optionId)
- Called when the user votes in a poll.
- ChatReactionCallback = void Function(ChatMessage message, String emoji)
- Called when the user picks or taps a reaction.
- ChatReactionLabel = String Function(String emoji, int count, {required bool includesYou})
- Formats the accessibility label of a reaction chip.
- ChatRsvpCallback = void Function(EventMessage message, ChatRsvp? rsvp)
-
Called when the user answers an event invitation.
nullremoves the answer. - ChatRsvpLabel = String Function(int going, int maybe)
- Formats the RSVP counters of an event.
- ChatScheduleCallback = void Function(String text, DateTime at, ChatMessage? replyTo)
- Called when the user schedules a message.
- ChatScrollToBottomBuilder = Widget Function(BuildContext context, int unreadCount, VoidCallback scrollToBottom)
- Builds the scroll-to-bottom button.
-
ChatSelectionActionsBuilder
= List<
ChatSelectionAction> Function(BuildContext context, List<ChatMessage> selected, List<ChatSelectionAction> defaults) -
Returns the buttons of the selection bar for
selectedmessages. - ChatSendCallback = void Function(String text, ChatMessage? replyTo)
- Called when the user sends a message.
- ChatStepLabel = String Function(int going, int maybe)
- Formats a step label such as "Question 2 of 5".
- ChatSystemMessageBuilder = Widget Function(BuildContext context, SystemMessage message)
-
Builds a
SystemMessage. -
ChatTypingIndicatorBuilder
= Widget Function(BuildContext context, List<
ChatUser> users) -
Builds the typing indicator for a non-empty list of
users. -
ChatTypingLabel
= String Function(List<
String> names) - Formats the "is typing" label for the given display names.
- ChatVoiceRecordEndCallback = void Function(Duration duration, {required bool cancelled})
-
Called when a voice recording ends.
cancelledistruewhen the user slid away to discard it.