Material.Avalonia themes an Avalonia app and splits extras into packages

A theme for Avalonia, not a general purpose UI kit

Avalonia is a cross platform UI framework for .NET, and Material.Avalonia is described as a customizable Material Design implementation for it. The scope is specific: the library is a collection of styles and controls that help you customize an Avalonia application with a Material Design theme, and the feature list starts with Material Design styles for almost all Avalonia controls.

That first line is the whole product in miniature, and it is also where the caveats sit. Almost all is not all, so a control you rely on may not be styled, and the gap between the two words is where a development day goes. The second bullet is where the project adds more than a palette: additional controls to support snackbars, side sheets, floating buttons, cards and dialogs. Those are the pieces a Material interface needs that a theme file alone does not give you.

The audience is a .NET team that has already chosen Avalonia and now needs the application to look like a Material application, with a palette that matches guidelines, a set of themed controls, and dialogs and snackbars that do not look bolted on. The comparison point is not another theme library but the alternative of writing all of that yourself in XAML, where a palette change means editing styles across your control set.

There is also a fork in the road about the icon pack that the overview is unusually explicit about, and the sections below come back to it, because it is the decision most likely to surprise someone in the first hour of use.

One MaterialTheme element holds the palette

The theming mechanism is a single resource you declare in your application styles. The XAML in the getting started section shows the whole shape of it: a namespace declaration for the themes, and then a MaterialTheme element inside Application.Styles carrying a BaseTheme, a PrimaryColor and a SecondaryColor.

<Application ...
  xmlns:themes="clr-namespace:Material.Styles.Themes;assembly=Material.Styles"
  ...>
  <Application.Styles>
    <themes:MaterialTheme BaseTheme="Dark" PrimaryColor="Purple" SecondaryColor="Lime" />
  </Application.Styles>
</Application>

The namespace points at the themes namespace of the Material.Styles assembly, which tells you the theme control lives in a styles assembly rather than in the top level package. The overview states that all styles are included automatically when you use MaterialTheme, so a single element is the switch that pulls the whole style set into the application.

The palette is described as easy to configure, both at design time and at runtime, according to the Material Guidelines. Design time matters for a designer handing you a colour specification, and runtime matters for an application with a theme switcher, since a user toggling between light and dark expects the change to take effect without a restart. The advanced theming page in the wiki is linked from the overview for the cases the attribute list does not cover.

The repository layout explains where the code sits: Material.Styles/ for the styles and theme, Material.Colors/ for the palette, Material.Ripple/ for the ripple effect that Material interfaces use to signal touch, and Material.Avalonia/ for the top level package. The other folders are the satellite packages and the demos, and the root carries Directory.Build.props and Directory.Packages.props, which is how versions are managed centrally across all of them.

Icons are a separate install, on purpose

The overview states that the library supports the full Material Design Icons pack, and in the same sentence explains that the pack must be installed separately, in favour of small library size. The icon project is Material.Icons, and it lives in its own repository rather than inside this one.

This is the trade-off most adopters meet first, so it is worth stating plainly. A Material interface without icons looks like a 2009 web page, and the icon set is the single largest chunk of assets in any Material styled application. The project has decided that bundling it would make the core package heavy for the many applications that already have their own icon strategy, or use a different icon set, or need the small package for a tool rather than a product.

The consequence for you is that there are two installation steps where a theme library usually has one, and if you forget the icon package you will be looking at empty squares in your design. The consequence for the maintainer is a smaller core package and no versioning lock between the theme and the icons, so you can update the icon pack without touching the theme.

Other satellite packages follow the same pattern. Material.Avalonia.DataGrid themes the DataGrid control, Material.Avalonia.TreeDataGrid brings the community TreeDataGrid control by Wieslaw Soltes into the theme, and Material.Avalonia.Dialogs supplies the dialog support. A separate package for dialogs is a deliberate choice as well, since a dialog implementation pulls in a host control and a service locator pattern, and applications that already have a dialog strategy should keep it.

Adding the packages and wiring the theme into App.xaml

The getting started instructions are four steps, from the base package to the optional packages. The base theme is added with the standard dotnet package command:

dotnet add package Material.Avalonia

Then the application file is edited to reference the theme resource, which is the XAML shown earlier with the MaterialTheme element placed inside Application.Styles. After that the optional packages are added as required, each with its own dotnet add package command:

dotnet add package Material.Avalonia.DataGrid
dotnet add package Material.Avalonia.TreeDataGrid
dotnet add package Material.Avalonia.Dialogs

What you should see after this is an application that renders with Material styling, and the overview suggests a way to check it: the demo applications are included in the source project, and the demo has a ShowMeTheXaml button in the bottom right corner of every control which shows the markup needed to recreate it.

That button is worth more than a screenshot gallery. It is a reverse engineering tool for the theme: you can look at any control in the demo, click the button, and get the XAML that produces it, which is a shortcut past the question of how a particular Material surface is meant to be composed. The source repository carries three demo projects, Material.Avalonia.Demo, Material.Avalonia.Demo.Browser and Material.Avalonia.Demo.Desktop, so the same UI can be inspected on desktop and in a browser.

For a team that wants to see it before installing anything, there is a live demo in the browser, and the overview qualifies it directly: it is currently in the alpha stage and many things can be broken. Treat it as a rough preview of the visual direction rather than as a test environment.

Separate packages, or hand written styles in your own project

The realistic alternative to Material.Avalonia is not another library so much as two options inside Avalonia itself, and they differ from this project in ways that matter for a team.

The first is to write the theme yourself in your own project. Avalonia lets you define styles, control templates and resources in XAML, so a team that needs three screens with a brand palette can define a few resources and be done. The cost is that the work is not only the palette: a Material interface needs ripple feedback, filled and outlined button variants, text field states, snackbars and a dialog host, and each of those is a template you maintain and re-test on every Avalonia upgrade. Material.Avalonia moves that work into a package that other teams also maintain, which is the ordinary argument for using a theme library.

The second alternative is the community route the project itself points at, where the overview links DialogHost.Avalonia as a simple way to display a dialog, and where the TreeDataGrid control is a separate community project that Material.Avalonia.TreeDataGrid themes. The difference in approach is that the theme package wraps and styles other people's controls instead of reimplementing them, so you inherit their behaviour and their update cadence, and you keep the option of replacing a component without leaving the theme.

The practical distinction between the two routes is how much of the Material specification you actually need. If your application is a form and a list, hand written resources in Avalonia are a small job. If it is a product with many surfaces, the templates, the ripple behaviour and the consistent states are the work, and paying for the package in dependency risk is usually cheaper than paying for them in maintenance.

Release cadence, nightly builds and the MIT licence

The project is published under the MIT licence, with the LICENSE file in the repository root. MIT is permissive, with a notice requirement and no obligation to open source a derived work, and it is the licence you would expect for a styling library whose value is the template code rather than the assets.

The release pattern is steady and visible. v3.19.0 was tagged on 2026-08-19, v3.20.0 on 2026-09-06, and v3.21.0 on 2026-09-25, which is the same day as the last push. The repository is not archived, so the versioning is not in question, and a minor version roughly every three weeks is the shape of the history rather than a claim about the future. For a UI library that follows the framework it styles, that cadence is the main upgrade cost: you will be taking Avalonia updates and theme updates in the same period, and the theme release that adapts to a new Avalonia version is the one you want.

Two build channels exist. The NuGet pages for Material.Avalonia carry both a stable and a prerelease version badge, and the wiki links a nightly packages page describing a nightly build feed, which is where you get a build from the master branch before it is tagged. The repository also has a nuget.config and a numerge.config.json, so the package sources and version increments are managed in the repository rather than by hand.

One more signal for adoption. The repository has no homepage listed, and the documentation lives in the wiki/ directory of the repository itself, with the getting started page, the advanced theming page, the nightly feed page and a screenshots page. That means the documentation is versioned with the code, which is a plus when a theme changes shape between minor versions and the wiki page you read is the one that matches the tag.

Editorial conclusion

Material.Avalonia fits a team building a cross platform .NET desktop app with Avalonia that wants a Material look without writing a theme from scratch, and it fits teams that prefer per feature packages because a DataGrid or Dialogs dependency is opt in. It is the wrong choice if you need the icon set bundled, since the Material Design Icons pack has to be installed separately to keep the library small, and it is a poor match for judging appearance from the browser demo, which the project describes as an alpha stage where many things can be broken. Before adopting, add the base package and configure a MaterialTheme in App.xaml, then decide separately whether you need Material.Avalonia.DataGrid, Material.Avalonia.TreeDataGrid, Material.Avalonia.Dialogs and the Material.Icons pack.

Frequently asked questions

Official sources

1. AvaloniaCommunity/Material.Avalonia on GitHub
2. Issues
3. License: MIT
4. README
5. Releases