BlazorChat – API Reference

Usage

Only ThreadId and ChatSender are required. Everything else has a sensible default.

@using BlazorChat.Components
@using BlazorChat.Shared.Models

<ChatWidget ThreadId="release-1.2.3"
            ChatSender="@currentUser" />

@code {
    private ChatSender currentUser = new() { Id = "user-1", DisplayName = "Alice" };
}

With Callbacks

<ChatWidget ThreadId="@ticketId"
            ChatSender="@currentUser"
            ThreadTitle="Incident Response"
            MentionableUsers="@teamMembers"
            ThemePreset="ChatThemePreset.Teams"
            OnMessageSent="@HandleSent"
            OnOfflineMention="@SendPushNotification"
            OnConnectionStateChanged="@UpdateConnectionBadge" />

Core Parameters

Parameter	Type	Default	Description
`ThreadId` required	`string`	`""`	Identifies the conversation. Use your workflow ID — release number, ticket ID, task reference, etc.
`ChatSender`	`ChatSender`	`new()`	Identity of the current user. Populate `Id` and `DisplayName`.
`ThreadTitle`	`string`	`"Conversation"`	Displayed in the widget header. Overridden by `CaptionText` when provided.
`CaptionText`	`string`	`""`	When non-empty, replaces `ThreadTitle` in the header.
`MentionableUsers`	`List<ChatSender>`	`[]`	Users available for @mention autocomplete. Required for `OnOfflineMention` to fire.

Transport Parameters

Control how the widget connects to its backing IChatService.

Parameter	Type	Default	Description
`AutoCreateChatService`	`bool`	`true`	When `true` and no service is registered in DI, the widget creates a SignalR-backed service that connects to BlazorChat.Server using `HubUrl`. Set to `false` when registering `InMemoryChatService` manually.
`HubUrl`	`string`	`"/chathub"`	BlazorChat.Server's SignalR hub endpoint used when `AutoCreateChatService` is `true`.
`ChatServiceOverride`	`IChatService?`	`null`	Directly supplies a custom `IChatService` instance, bypassing both DI and `AutoCreateChatService`.

Appearance Parameters

Parameter	Type	Default	Description
`ThemePreset`	`ChatThemePreset`	`Default`	Built-in colour theme. Options: `Default`, `BlazorChat`, `Light`, `Dark`, `Teams`, `Slack`, `Discord`, `WhatsApp`, `Sunset`, `Cyberpunk`, `Ocean`.
`CustomTheme`	`ChatTheme?`	`null`	Fully custom `ChatTheme` object. Takes precedence over `ThemePreset` when set.
`AvatarSize`	`AvatarSize`	`Medium`	Size of avatars in message bubbles and the typing indicator. Options: `Small`, `Medium`, `Large`.
`MessageTemplate`	`RenderFragment<ChatMessage>?`	`null`	Custom Blazor template for rendering each message bubble. Receives the `ChatMessage` as its context parameter.

Message Lifecycle Callbacks

Callback	Type	Description
`OnMessageSent`	`EventCallback<ChatMessage>`	Fired after a message is successfully sent.
`OnMessageEdited`	`EventCallback<ChatMessage>`	Fired after a message is edited.
`OnMessageDeleted`	`EventCallback<ChatMessage>`	Fired after a message is deleted.
`OnMessageReceived`	`EventCallback<ChatMessage>`	Fired when a message arrives from another user (not the current sender). Use for notification sounds or unread badges outside the widget.
`OnMessageSendFailed`	`EventCallback<(ChatMessage, Exception?)>`	Fired when sending fails. The tuple carries the unsent message and the exception.
`OnMessageEditFailed`	`EventCallback<(ChatMessage, Exception?)>`	Fired when an edit fails.
`OnMessageDeleteFailed`	`EventCallback<(ChatMessage, Exception?)>`	Fired when a delete fails.

Reaction Callbacks

Callback	Type	Description
`OnReactionOptimistic`	`EventCallback<ChatReaction>`	Fired immediately when the user clicks an emoji reaction, before server confirmation. Use for optimistic UI updates.
`OnReactionToggled`	`EventCallback<(ChatReaction, bool)>`	Fired when the user toggles a reaction. The second tuple value is `true` when the reaction was removed.
`OnReactionSummaryUpdated`	`EventCallback<ChatReactionSummary>`	Fired when an authoritative reaction summary is broadcast from the server to all connected clients.
`OnReactionFailed`	`EventCallback<(ChatReaction, Exception?)>`	Fired when sending a reaction fails.

Presence & Connection Callbacks

Callback	Type	Description
`OnOfflineMention`	`EventCallback<ChatMentionNotification>`	Fired when a sent message @mentions a user who is not currently active in the thread. Use this to dispatch email, push, or Teams notifications from your host app.
`OnUserJoined`	`EventCallback<ChatSender>`	Fired when a user connects to the thread.
`OnUserLeft`	`EventCallback<ChatSender>`	Fired when a user disconnects from the thread.
`OnConnectionStateChanged`	`EventCallback<bool>`	Fired when the hub connection state changes. Value is `true` when connected, `false` when disconnected.
`OnActiveUserCountChanged`	`EventCallback<int>`	Fired when the count of active users in the thread changes.

Styling Parameters

All styling parameters accept any valid CSS value (e.g., "#1a1a2e", "1rem", "600px"). An empty string leaves the value to the active ThemePreset or CustomTheme.

Caption (Header Bar)

Parameter	Default	Description
`CaptionBackground`	`""`	Background colour of the widget header bar.
`CaptionFontColor`	`""`	Text colour of the header bar.
`CaptionFontFamily`	`""`	Font family of the header bar text.
`CaptionFontSize`	`""`	Font size of the header bar text.
`CaptionFontWeight`	`""`	Font weight of the header bar text.
`CaptionFontStyle`	`""`	Font style (`normal` / `italic`) of the header bar text.

Message Bubbles

Parameter	Default	Description
`BubbleWidth`	`"80%"`	Max width of each message bubble.
`BubbleFontFamily`	`""`	Font family inside message bubbles.
`BubbleFontSize`	`""`	Font size inside message bubbles.
`BubbleFontWeight`	`""`	Font weight inside message bubbles.
`BubbleFontStyle`	`""`	Font style inside message bubbles.
`BubbleFontColor`	`""`	Text colour for both sent and received bubbles (overridden by the `Mine`/`Other` variants below).
`BubbleBackgroundMine`	`""`	Background colour for the current user's bubbles.
`BubbleBackgroundOther`	`""`	Background colour for other users' bubbles.
`BubbleColorMine`	`""`	Text colour for the current user's bubbles.
`BubbleColorOther`	`""`	Text colour for other users' bubbles.
`MessageGap`	`""`	Vertical gap between consecutive message bubbles.
`MessageContainerBackground`	`""`	Background colour of the scrollable message area.
`MessageContainerFontColor`	`""`	Default text colour inside the message area.

Composer (Input Area)

Parameter	Default	Description
`ComposerBackground`	`""`	Background colour of the message input area.
`ComposerBorderColor`	`""`	Border colour of the message input area.
`ComposerTextColor`	`""`	Text colour inside the message input area.
`SendButtonBackground`	`""`	Background colour of the send button.
`SendButtonColor`	`""`	Icon/text colour of the send button.

Widget Dimensions

Parameter	Default	Description
`WidgetWidth`	`""`	Explicit width of the widget container.
`WidgetMinWidth`	`""`	Minimum width of the widget container.
`WidgetMaxWidth`	`""`	Maximum width of the widget container.
`WidgetHeight`	`""`	Explicit height of the widget container.
`WidgetMinHeight`	`""`	Minimum height of the widget container.
`WidgetMaxHeight`	`""`	Maximum height of the widget container.