MahApps.Metro: a WPF UI toolkit that restyles the controls you already have

The WPF problem MahApps.Metro actually solves

WPF shipped a styling system and then left most of the visual work to whoever was building the app. A stock Button, TextBox or DataGrid looks like Windows 7 era chrome out of the box, and the pieces people expect from a desktop application, a title bar you can put commands in, a theme that switches at runtime, a dialog that does not freeze the window behind it, were never part of the framework. Teams either write that layer themselves or buy into a control vendor.

The project's own framing is that it restyles what you already have. That is the whole pitch, and it is a narrower claim than most UI libraries make. You do not rename Button to MetroButton. You reference the package, merge two resource dictionaries, and your existing controls pick up the new look. For a codebase with hundreds of views, that difference decides whether adoption takes an afternoon or a quarter.

MetroWindow, ThemeManager and attached properties

Three mechanisms carry most of the toolkit. The first is MetroWindow, which replaces the Windows title bar with one you control: commands to the left and right of the title, a coloured glow border, an overlay area for dialogs, and flyouts that slide in from any edge. MetroNavigationWindow is the page-based variant.

The second is theming. A theme is a base theme, Light or Dark, plus an accent colour, and ThemeManager switches it at runtime. The README states that ThemeManager can follow the Windows accent colour and the system light/dark setting, and that you can generate your own themes from the same scheme the built-in ones use. Style variants follow Visual Studio, Windows 10 or WinUI conventions.

The third is the attached property pattern. Watermarks, clear buttons, per-control corner radii and selected-item brushes arrive as attached properties such as TextBoxHelper.Watermark. That means behaviour attaches to a stock control instead of requiring you to inherit from a special subclass, which keeps your XAML portable and your control tree ordinary.

Dialogs follow the same idea. Message, input, login and progress dialogs are shown as an overlay inside your window rather than as a blocking modal, and the README says they are awaitable and usable from a view model. That is a real architectural difference: a blocking ShowDialog in a view model is awkward to test, and an awaitable overlay is not.

Getting MahApps.Metro into a WPF project

The package is published on NuGet as MahApps.Metro, and the README links both the Documentation and the Quick Start under a Let's get started heading. It also points at Visual Studio Templates and a demo application as entry points, which are the faster route if you are starting a new project rather than retrofitting one. The README does not print an install command or the merge snippet, so the place to copy the exact dictionary names and the current MetroWindow namespace from is the Quick Start page rather than this article.

The README describes the wiring in prose only: reference the toolkit, merge two resource dictionaries, and the controls you already have are restyled in place. It also names the attached property that carries a watermark, TextBoxHelper.Watermark, as the example of how behaviour is attached to a stock control instead of a subclass. Those two names, the package id MahApps.Metro and the attached property TextBoxHelper.Watermark, are the parts of the setup that the repository itself states. Everything around them, the pack URI for the dictionaries and the XAML namespace for the controls, lives in the documentation and in the Visual Studio Templates, and it changes between the 2.4 and 3.0 lines.

That is the honest shape of the setup for this project. The retrofit promise is real, but the first twenty minutes are spent in the Quick Start and the templates rather than in the README, and the version you pick determines which snippet is correct.

Where MahApps.Metro is the wrong tool

The toolkit is WPF and Windows. Nothing in the README suggests otherwise, and the supported targets are .NET Framework 4.6.2 and greater, .NET 6 and .NET 8, all on Windows. If your roadmap is WinUI 3, MAUI or Avalonia, this package does not follow you there.

Version choice is the second trap. The README describes 2.4 as running on .NET Framework 4.5.2 and newer plus .NET Core 3.x, while 3.0 is on NuGet as a release candidate targeting .NET Framework 4.6.2, .NET 6 and .NET 8. The release list shows 2.4.11 as the most recent stable tag, with 2.4.10 before it in 2023 and 2.4.9 in 2021. A team that wants the Windows 11 caption-button behaviour, where the maximise button participates in snap layouts and the window can use newer backdrop materials, has to take the 3.0 candidate line described in the README rather than the stable 2.4 line. That is a real decision, not a formality.

The third limitation is the one that applies to every styling toolkit: restyling in place is only free if you were not already styling. Applications with heavily templated controls, custom ControlTemplates or their own theme dictionaries will find that merged dictionaries compete with what they already wrote, and the resolution order becomes something you have to reason about per control. The README does not document rollback, so treat the merge as a change you test view by view rather than a switch you flip.

MahApps.Metro compared with Material Design in XAML

The obvious alternative in the WPF space is Material Design in XAML, and the difference is not quality, it is design language and scope. Material Design in XAML implements Google's Material spec: elevation, ripple, the Material colour system, Material-styled dialogs and a component set built to match. If your product's visual identity is Material, adopting MahApps.Metro means fighting the toolkit's own conventions to get there.

MahApps.Metro aims at the Metro and Windows conventions instead, with style variants that follow Visual Studio, Windows 10 or WinUI. Its differentiator is the retrofit story: the README is explicit that it restyles the standard controls you already use rather than asking you to swap them, and that there is no vendor lock-in on your XAML. A team with a large existing WPF codebase gets a modern look without a control-by-control migration.

The two are not mutually exclusive in principle, since both work through resource dictionaries, but mixing them means maintaining two styling systems and deciding which one owns each control. For a new project, pick the design language first and the library second.

Licence, governance and what maintenance costs

MahApps.Metro is MIT licensed, and the repository carries a LICENSE and a NOTICE.md at the top level. MIT is permissive: you can use it in closed-source commercial applications. That is a statement about the licence text, not legal advice; if your organisation has a policy on third-party notices, the NOTICE.md file is the one to route through it.

Governance is worth noting. The README states the project has been part of the .NET Foundation since 2020, started on 29 January 2011, and that more than 160 people have contributed. The default branch is develop, with main also built in CI, and the repository is not archived. The last push was on 2026-09-21, and the most recent release, 2.4.11, is dated 2025-09-14.

Upgrade cost is the practical question. Moving from 2.4 to 3.0 is not a patch bump: the target frameworks change, and the window chrome is reworked so caption buttons register as non-client controls. If you have customised MetroWindow's title bar template, that is the code to audit first. Staying on 2.4 keeps you on the stable line but leaves the Windows 11 chrome work on the other side of the upgrade.

Editorial conclusion

Adopt MahApps.Metro if you have a WPF application on .NET Framework 4.6.2, .NET 6 or .NET 8 and you want modern chrome, theming and dialogs without renaming a single control in your XAML. Do not adopt it for WinUI 3, MAUI, Avalonia or any cross-platform target: the toolkit is WPF and Windows only. Before committing, verify which major version you are pulling, because the README describes 2.4 as the stable line on .NET Framework 4.5.2 and .NET Core 3.x while 3.0 is described as a release candidate, and check the release notes for the .NET Framework 4.6.2 floor that 3.0 introduces. Then open one existing view, merge the resource dictionaries as the Quick Start describes, and confirm your own styles still win where you expect them to.

Frequently asked questions

Official sources

1. License: MIT
2. MahApps/MahApps.Metro on GitHub
3. Project website
4. README
5. Releases