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

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 AppBar with 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. day is 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. null removes 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. null removes 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 selected messages.
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. cancelled is true when the user slid away to discard it.