Syncfusion .NET MAUI Chat (SfChat)

The Syncfusion .NET MAUI Chat control (SfChat) delivers a contemporary conversational UI for building chatbot interfaces, customer support screens, and multi-user messaging experiences. It supports rich message types, real-time typing indicators, suggestions, load-more history, swiping, and deep styling customization.

When to Use This Skill

• Building a chat UI, chatbot interface, or messaging screen in .NET MAUI
• Displaying conversations between two or more users
• Sending/receiving text, images, cards, hyperlinks, or date/time picker messages
• Implementing typing indicators, message suggestions, or load-more history
• Customizing message appearance, shapes, delivery states, or themes
• Adding swipe actions, time-break grouping, or attachment buttons
• Localizing the chat UI or enabling accessibility features

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• NuGet installation (Syncfusion.Maui.Chat)
• Handler registration in MauiProgram.cs
• Basic SfChat initialization in XAML and C#
• ViewModel setup with Messages and CurrentUser
• Binding messages to the chat control
• Running the application

Messages

📄 Read: references/messages.md

• TextMessage, DatePickerMessage, TimePickerMessage, CalendarMessage
• HyperlinkMessage, ImageMessage, CardMessage
• Delivery states (ShowDeliveryState, DeliveryState enum, custom icons)
• Pin message (AllowPinning, PinnedMessages, events, template)
• Message template and ChatMessageTemplateSelector
• Customizable incoming/outgoing views
• Message spacing, shape, timestamp format, avatar/author visibility
• Sending messages, keyboard, multiline input, hide input view

Data Binding

📄 Read: references/data-binding.md

• Binding ObservableCollection<object> to Messages
• CurrentUser differentiation of sender/receiver
• Custom data models with IMessage / ITextMessage
• ItemsSourceConverter for external model binding
• Dynamically updating messages at runtime

Suggestions

📄 Read: references/suggestions.md

• Chat-level suggestions (SfChat.Suggestions)
• Message-level suggestions (TextMessage.Suggestions)
• SuggestionItemSelected event and command
• Customizing suggestion item templates

Typing Indicator

📄 Read: references/typing-indicator.md

• Enabling the typing indicator (ShowTypingIndicator)
• Setting author and message on TypingIndicator
• Customizing appearance
• Showing/hiding dynamically

Load More

📄 Read: references/load-more.md

• Enabling load more (LoadMoreBehavior)
• LoadMore event and LoadMoreCommand
• Loading older messages on scroll
• IsLazyLoading property
• Disabling after all messages are loaded

Events & Commands

📄 Read: references/events.md

• SendMessage / SendMessageCommand
• ImageTapped / ImageTappedCommand
• CardTapped / CardCommand
• SuggestionItemSelected
• MessagePinned / MessageUnpinned
• LoadMore / LoadMoreCommand
• Handling and cancelling event args

Styles & Appearance

📄 Read: references/styles.md

• Incoming and outgoing message styling
• Message input view styling
• Time-break and typing indicator styling
• Suggestion view styling
• MessageShape options
• Theme support (Material 3, Fluent)

Accessibility & Localization

📄 Read: references/accessibility-localization.md

• WCAG 2.0 compliance
• Keyboard navigation and screen reader support
• AutomationId for UI testing
• Localization with .resx resource files
• Supported localizable strings
• RTL layout support

Scrolling

📄 Read: references/scrolling.md

• Programmatic scroll to a specific message (ScrollToMessage)
• Auto-scroll to bottom on new message (CanAutoScrollToBottom)
• Scroll to bottom floating button (ShowScrollToBottomButton)
• Customizing the scroll to bottom button (ScrollToBottomButtonTemplate)
• Scrolled event and ChatScrolledEventArgs (IsBottomReached, IsTopReached, ScrollOffset)

Advanced Features

📄 Read: references/advanced-features.md

• Message swiping (left/right, SwipeStarted, SwipeEnded, swipe templates)
• Time-break grouping (custom time-break template)
• Attachment button (adding, customizing, AttachmentButtonView)
• Liquid glass effect (enabling, platform support, customization)
• MessageSpacing configuration
• Hiding the message input view (ShowMessageInputView)

---

Quick Start

1. Install the NuGet package:

dotnet add package Syncfusion.Maui.Chat

2. Register the handler in MauiProgram.cs:

using Syncfusion.Maui.Core.Hosting;

builder.ConfigureSyncfusionCore();

3. Add SfChat in XAML:

<ContentPage xmlns:sfChat="clr-namespace:Syncfusion.Maui.Chat;assembly=Syncfusion.Maui.Chat"
             xmlns:local="clr-namespace:MyApp">
    <ContentPage.BindingContext>
        <local:ChatViewModel/>
    </ContentPage.BindingContext>
    <sfChat:SfChat Messages="{Binding Messages}"
                   CurrentUser="{Binding CurrentUser}" />
</ContentPage>

4. Define the ViewModel:

using Syncfusion.Maui.Chat;

public class ChatViewModel : INotifyPropertyChanged
{
    public ObservableCollection<object> Messages { get; set; }
    public Author CurrentUser { get; set; }

    public ChatViewModel()
    {
        CurrentUser = new Author { Name = "Nancy" };
        Messages = new ObservableCollection<object>
        {
            new TextMessage
            {
                Author = CurrentUser,
                Text = "Hello! How can I help you today?"
            },
            new TextMessage
            {
                Author = new Author { Name = "Bot", Avatar = "bot.png" },
                Text = "Hi Nancy! I am here to assist you."
            }
        };
    }

    public event PropertyChangedEventHandler PropertyChanged;
}

---

Common Patterns

Sending a message and responding

// In ViewModel
public ICommand SendMessageCommand => new Command<object>(OnSendMessage);

private void OnSendMessage(object args)
{
    var e = args as SendMessageEventArgs;
    
    // ⚠️ IMPORTANT: By default, SfChat automatically adds the user's message to the 
    // Messages collection. Do NOT manually add it unless you set e.Handled = true
    
    // Add bot response after user sends message
    MainThread.BeginInvokeOnMainThread(async () =>
    {
        await Task.Delay(500); // Simulate processing
        Messages.Add(new TextMessage
        {
            Author = new Author { Name = "Bot", Avatar = "bot.png" },
            Text = $"You said: {e.Message.Text}"
        });
    });
}

If you need full control over message addition, set Handled = true:

private void OnSendMessage(object args)
{
    var e = args as SendMessageEventArgs;
    e.Handled = true; // Prevent SfChat from auto-adding the message
    
    // Now you must manually add the message
    if (e.Message is TextMessage textMessage)
    {
        Messages.Add(textMessage); // You add it
        
        // Then handle response...
    }
}

Adding quick reply suggestions

Messages.Add(new TextMessage
{
    Author = new Author { Name = "Bot" },
    Text = "How would you like to proceed?",
    Suggestions = new ObservableCollection<ISuggestion>
    {
        new Suggestion { Text = "Option A" },
        new Suggestion { Text = "Option B" }
    }
});

Showing a typing indicator

sfChat.ShowTypingIndicator = true;
sfChat.TypingIndicator = new TypingIndicator
{
    Authors = new ObservableCollection<Author>
    {
        new Author { Name = "Bot", Avatar = "bot.png" }
    },
    Text = "Bot is typing..."
};

---

Key Properties

Property	Type	Purpose
Messages	ObservableCollection<object>	Collection of all messages
CurrentUser	Author	Identifies the local user (outgoing messages)
ShowTypingIndicator	bool	Toggle typing indicator
TypingIndicator	TypingIndicator	Set who is typing
ShowDeliveryState	bool	Show sent/delivered/read/failed icons
AllowPinning	bool	Enable message pinning
MessageShape	MessageShape	Message bubble shape
MessageSpacing	double	Vertical gap between messages
ShowMessageInputView	bool	Show/hide the message editor
LoadMoreBehavior	LoadMoreOption	Enable load-more on scroll
AllowMultilineInput	bool	Allow multi-line message entry
ShowKeyboardAlways	bool	Keep keyboard open after send