MessageBox.Avalonia gives Avalonia apps a dialog that adapts to the platform

ShowAsync picks a popup or a window for you

The package is described as a message box for Avalonia UI, and the first line of the description of the feature set is that it now supports all platforms as an Xplat template. The mechanism is the ShowAsync method, which shows the message box depending on the type of application. If the application is a SingleViewApplicationLifetime, which covers mobile and browser hosts, the message box is shown as a popup. If the application is a ClassicDesktopStyleApplicationLifetime, which is the desktop case, it is shown as a window. That single decision is the reason to use this package rather than a dialog you write yourself, because the lifetime difference is exactly the thing an application developer has to get right and will otherwise branch on. There are also explicit variants if you want to force the behaviour. ShowWindowAsync shows the message box as a window, ShowWindowDialogAsync shows it as a window with an owner, and ShowAsPopupAsync shows it as a popup.

The manager returns a box that you await

The entry point is MessageBoxManager, and the standard case is short enough to read at a glance. You ask the manager for a standard message box with a caption, a message and a button set, then await the result:

using MsBox.Avalonia;
using MsBox.Avalonia.Enums;

var box = MessageBoxManager
    .GetMessageBoxStandard("Caption", "Are you sure you would like to delete appender_replace_page_1?",
        ButtonEnum.YesNo);

var result = await box.ShowAsync();

The names are worth noticing. The namespace inside the package is MsBox.Avalonia even though the package and the solution are called MessageBox.Avalonia, so the using directives and the assembly name differ, and the README image paths still point at MsBox.Avalonia directories. The button set is an enum, with ButtonEnum.YesNo in the example. The result is a ButtonResult, so the code that shows the box and the code that acts on the answer can be separated without threading a closure through the dialog.

Never block on the Task, because it deadlocks the UI

The README devotes a section to async and await usage, and the rule is absolute. Always use await when calling MessageBox methods, and never use .Result or .Wait() on the Task, because that will cause a deadlock and freeze your UI. The failure mode is worth understanding, because it is not an exception you can catch. The dialog runs on the UI thread, and the code that would display it is waiting for the dialog to finish, so the thread that has to service the dialog cannot run. The correct shape is a small async method that returns the result:

private async Task<ButtonResult> ShowConfirmation()
{
    var box = MessageBoxManager.GetMessageBoxStandard("Confirm", "Are you sure?", ButtonEnum.YesNo);
    return await box.ShowAsync();
}

// Usage:
var result = await ShowConfirmation();
if (result == ButtonResult.Yes)
{
    // Handle confirmation
}

The instruction is that if you need to return the result to the caller, the entire call chain has to be async, which is the part people tend to get wrong when they wrap a dialog in a synchronous helper somewhere further up.

The custom overload gives you buttons, an icon and a hyperlink

For anything beyond a standard prompt, GetMessageBoxCustom takes a MessageBoxCustomParams object and the options are extensive. You define your own buttons with a list of ButtonDefinition objects, each carrying a Name, and you set ContentTitle, ContentMessage, an Icon from the package's Icon enum, a WindowStartupLocation, CanResize, MaxWidth and MaxHeight, SizeToContent, ShowInCenter and Topmost. There is also a HyperLinkParams with Text and an Action, and the README's example shows what the action body looks like: it builds a url, checks the platform with RuntimeInformation.IsOSPlatform, and launches the browser accordingly, using the shell execute path on Windows, x-www-browser on Linux and open on macOS, throwing for an unrecognised platform. The example is long, and the reason is instructive. A message box with a hyperlink has to open a browser, and there is no cross platform API for that in .NET, so every application that uses the feature ends up writing the same platform switch, and this package writes it once.

Markdown arrives as a separate package and a style include

Rich text in the message is an opt-in extension rather than a built in feature. To enable markdown support you need two steps, installing the MessageBox.Avalonia.Markdown package, and adding the MarkdownView control from MsBox.Avalonia.Markdown to your application styles in App.axaml:

    <Application.Styles>
        <StyleInclude Source="avares://MsBox.Avalonia.Markdown/Controls/MarkdownView.axaml" />
    </Application.Styles>

The avares scheme points into the assembly's resources, so the include is resolved by Avalonia's resource loader rather than by a file path, and the control has to be present in the style collection before the message box can use it. Splitting it this way keeps the core package free of a markdown dependency for the many applications that do not need it, and it mirrors how the repository is laid out, with the main package under MsBox.Avalonia/ and the extension under MsBox.Avalonia.Markdown/.

Installing is one package reference

To start you install the MessageBox.Avalonia NuGet package, and the README gives the command, dotnet add package MessageBox.Avalonia, run in the project directory. Alternatively you can download the repository, which contains the solution file MessageBox.Avalonia.sln along with the two source directories, a sample project in a directory named Exmaple2.0, an Images folder, and a DotSettings file for the solution. That naming detail, the directory spelled Exmaple2.0, is the kind of thing that makes a newcomer hesitate, and it is worth knowing before you go looking for a samples folder. The README also asks for support at the Avalonia Telegram group, and the project carries a JetBrains sponsorship, which is the sort of arrangement that usually shows up as a funding link rather than a technical dependency.

Where a message box stops being the right tool

The boundary of this package is the shape of the dialog. A message box is a title, a message, a row of buttons and, optionally, a hyperlink and an icon. If your confirmation needs a text input, a list to pick from, a checkbox set or a custom layout, you are past it, and the alternative is a window of your own in Avalonia XAML, shown with the same kind of lifetime awareness. The difference in approach is that a custom window gives you full control of layout and behaviour but is work you repeat in every application, while the message box gives you a consistent look for the common cases for the cost of a package reference. There is a second limitation worth naming, and it is in the README rather than in the code, since the rule about awaiting is what separates a working integration from a frozen application. If your call chain cannot be made async all the way through, this package will not work for you, and no configuration change will fix that.

Editorial conclusion

Adopt MessageBox.Avalonia if you build Avalonia UI applications that run on both desktop and mobile and want one confirmation API that adapts to the platform lifetime instead of a per platform dialog you write twice. Do not adopt it if you need a dialog with a layout of your own, because a message box is a fixed shape with a title, a message, buttons and an optional hyperlink. Before you integrate, read the async rules in the README and make your call chain awaitable end to end, and check the package version you pin, since the repository has no GitHub releases and the last push was on 2026-04-21.

Frequently asked questions

Official sources

1. AvaloniaCommunity/MessageBox.Avalonia on GitHub
2. Issues
3. License: MIT
4. README