MaterialDesignInXamlToolkit Documentation

File: README.md Copy Chapter

Material Design In XAML Toolkit

)
)

Comprehensive and easy to use Material Design theme and control library for the Windows desktop (WPF).

• Material Design styles for all major WPF Framework controls
• Additional controls to support the theme, including Multi Action Button, Cards, Dialogs, Clock
• Easy configuration of palette (at design and runtime), according to Google's guidelines
• Full Material Design Icons icon pack
• Easy transition effects
• Compatible with Dragablz, MahApps
• Demo applications included in the source project

See screenshots

Table of contents

• Getting started
• Building the source
• Screenshots
• More examples
• FAQ
• Contributing
• Mentions
• Backers
• Sponsors

Getting started Copy Chapter

[!NOTE]
See the full starting guide for more in-depth information.

This quick guide assumes you have already created a WPF project and are using Microsoft Visual Studio 2022.

• Install the toolkit through the visual NuGet package manager in Visual Studio or use the following command:

Install-Package MaterialDesignThemes

• Alter your App.xaml

<Application 
  x:Class="Example.App"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:materialDesign="http://materialdesigninxaml.net/winfx/xaml/themes"
  StartupUri="MainWindow.xaml">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <materialDesign:BundledTheme BaseTheme="Light" PrimaryColor="DeepPurple" SecondaryColor="Lime" />

                <ResourceDictionary Source="pack://application:,,,/MaterialDesignThemes.Wpf;component/Themes/MaterialDesign2.Defaults.xaml" /> 
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

• If you want to target Material Design 3, alter the ResourceDictionary line in the snippet above to use MaterialDesign3.Defaults.xaml.

• Alter your MainWindow.xaml

<Window [...]
  Style="{StaticResource MaterialDesignWindow}"
  [...] >

XML Namespaces Copy Section

The toolkit exposes two XML namespaces for use in XAML:

[!WARNING]
Types exposed via the materialDesignInternal namespace are considered internal implementation details and are not guaranteed to maintain backwards-compatibility between versions. Use them at your own risk.

To use the internal namespace in XAML:

<Window ...
  xmlns:materialDesignInternal="http://materialdesigninxaml.net/winfx/xaml/themes-internal">

Building the source Copy Chapter

To build the project, following is required:

• Microsoft Visual Studio 2022
• .NET desktop development workload

This repository also contains 3 different demo applications:

• MaterialDesignDemo - Reference WPF app with Material Design 2 styling, this contains all controls and is a recommended tool when developing apps with this library
• MaterialDesign3Demo - Reference WPF app with Material Design 3 styling, under development
• MahAppsDragablzDemo - Demo app for combining with Dragablz and MahApps

Screenshots Copy Chapter

Material Design 3 demo app screenshots

Material Design 2 demo app screenshots

[!WARNING]
The screenshots below are taken from the Material Design 2 demo app.
Material Design 3 is the latest version, so the UI shown here may differ from the latest design.

More examples Copy Chapter

• Keboo/MaterialDesign.Examples
• Motion List

FAQ Copy Chapter

• How to increase rendering performance?

Contributing Copy Chapter

Before contributing code read the Contribution Guidelines

• GitHub issues are for bugs and feature requests.
• For questions, help and chat in general, please use the GitHub discussion tab or the Discord server.
• Stack Overflow tag: material-design-in-xaml

Want to say thanks? 🙏🏻

• Hit the :star: star :star: button
• If you'd like to make a very much appreciated financial donation please visit open collective

This project exists thanks to all the people who contribute.

Mentions Copy Chapter

• James Willock
  - Founder of the project
• Kevin Bost
  - Maintainer of the repository
• Snalty
  - Designer of the logo
• Icon pack sourced from Material Design Icons
• ControlzEx - Library used in MaterialDesignInXAML
• Ignace Maes - Whose Material Skin project inspired the original material design theme for Dragablz, which in turn led James Willock start this project
• Material Design Extensions - A community repository based on this library that provides additional controls and features.
• Contributors - A big thank you to all the contributors of the project!

Backers Copy Chapter

Thank you to all our backers! 🙏 Become a backer.

Sponsors Copy Chapter

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Become a sponsor.

File: docs/Freezable_Object_for_Enhanced_Performance.md Copy Chapter

Home > Using Freezable Objects for Enhanced Performance

Using `Freezable` Objects for Enhanced Performance

Background information Copy Chapter

WPF provides the Freezable class for objects that can be made immutable to optimize performance, such as brushes, pens, and transforms.

Setting Objects as `Freezable` Copy Chapter

When an object is frozen, it becomes immutable, which reduces memory usage and allows WPF to optimize rendering.

SolidColorBrush myBrush = new SolidColorBrush(Colors.Blue);
if (myBrush.CanFreeze)
{
    myBrush.Freeze();
}

Frozen objects cannot be modified, so only freeze objects that don’t require changes.

Benefits of Freezable Objects Copy Chapter

Freezable objects improve rendering speed, especially for large visuals or repeated animations. This technique is particularly useful in complex UIs with many reused resources.

File: docs/Optimize_UI_Thread_Performance.md Copy Chapter

Home > How to Optimize UI Thread Performance?

How to Optimize UI Thread Performance?

Background information Copy Chapter

The UI thread in WPF is responsible for rendering controls and handling user interactions. Heavy computations or complex bindings on the UI thread can lead to sluggish performance and poor user experience.

Using `Dispatcher.BeginInvoke` Copy Chapter

For non-UI-intensive tasks that still need to interact with the UI, use Dispatcher.BeginInvoke to move tasks off the UI thread without blocking it:

// Execute this in the background without freezing the UI
Dispatcher.BeginInvoke((Action)(() =>
{
    // Update UI elements here
}));

Avoiding Complex Bindings Copy Chapter

Complex bindings, especially with large data sets, can slow down the UI. Consider simplifying bindings, reducing converters, or using INotifyPropertyChanged with view models to optimize data flow.

<TextBlock Text="{Binding User.Name}" />

[!NOTE]
Always test performance impacts when using nested or complex bindings.

Use `VirtualizingStackPanel` for Large Lists Copy Chapter

For large collections, use VirtualizingStackPanel to only create visuals for items in view:

<ListBox VirtualizingStackPanel.IsVirtualizing="True" />

This reduces memory usage and improves scrolling performance in lists.

File: docs/Optimizing-WPF-Rendering-Performance.md Copy Chapter

Home > Optimizing WPF UI Animation and Rendering Performance

Optimizing WPF UI Animation and Rendering Performance

Background Information Copy Chapter

WPF applications often have complex animations and UI interactions, which can lead to performance bottlenecks if not optimized. Understanding the techniques for efficient rendering and leveraging WPF's internal capabilities can significantly enhance the user experience by making the interface smoother and more responsive.

Reducing Visual Complexity Copy Chapter

One effective approach to improving rendering performance is reducing visual complexity. This involves:

• Minimizing Visual Layers: Each layer that a control or element has can add rendering overhead. Consider consolidating overlapping elements.
• Avoiding Overdraw: Redundant drawing layers, where multiple visual elements overlap, increase rendering work for the GPU. Arrange visuals to reduce the overdraw effect.
• Limiting the Use of Effects: Avoid heavy effects such as DropShadowEffect or BlurEffect where possible, as these can slow down rendering.

Using the `RenderOptions` Property Copy Chapter

The RenderOptions class in WPF provides properties for fine-tuning rendering options. The BitmapScalingMode property, for instance, helps adjust the scaling performance of images.

Setting BitmapScalingMode to LowQuality helps improve performance when scaling images, especially useful for animations.

[!TIP]
Use HighQuality scaling mode sparingly, as it increases GPU workload.

Implementing Virtualization Copy Chapter

For controls that display large data sets, such as ListView or DataGrid, enable virtualization to improve scrolling performance:

<ListView VirtualizingStackPanel.IsVirtualizing="True" 
          VirtualizingStackPanel.VirtualizationMode="Recycling" />

Virtualization helps reduce memory usage by creating only the items currently in view, thus speeding up scrolling and rendering.

Optimize Animation with CompositionTarget Copy Chapter

For custom animations, consider leveraging CompositionTarget.Rendering, which allows you to hook into the render loop directly:

CompositionTarget.Rendering += (s, e) =>
{
    // Custom animation logic
};

This method provides more control over frame-by-frame updates, but should be used cautiously as it can impact performance if not handled efficiently.

Example Comparison Copy Chapter

Further Reading Copy Chapter

Additional resources for improving WPF performance:

• Optimizing WPF Application Performance
• Rendering Performance Best Practices

File: docs/Reducing_Layout_Complexity.md Copy Chapter

Reducing Layout Complexity

Background information Copy Chapter

Complex layouts can slow down WPF performance, especially with nested controls or excessive use of Grid and StackPanel.

Avoid Nested Grids and StackPanels Copy Chapter

Overuse of nested layouts can create rendering bottlenecks. Try to simplify the structure or use a UniformGrid or DockPanel for simpler arrangements.

<DockPanel>
    <TextBlock Text="Header" DockPanel.Dock="Top" />
    <ListView DockPanel.Dock="Bottom" />
</DockPanel>

Prefer Static Resources Over Dynamic Resources Copy Chapter

Static resources are faster to load compared to dynamic ones. Use dynamic resources only if you need runtime changes in resource values.

<Style x:Key="ButtonStyle" TargetType="Button" BasedOn="{StaticResource BaseButtonStyle}" />

[!NOTE]
Dynamic resources are reevaluated each time they’re used, which may impact performance.

File: docs/rendering-performance.md Copy Chapter

Home > How to increase rendering performance?

How to increase rendering performance?

Background information Copy Chapter

Every class inheriting from UIElement
contains a property CacheMode. To quote Microsoft's documentation:

Set the CacheMode property when you need to increase performance for content that is time consuming to render. For
more information, see BitmapCache.

The default value is null as to not use any form of caching. This makes the controls sharp and crisp.

Setting `UIElement.CacheMode` Copy Chapter

An example how to set a CacheMode:

<ToggleButton>
    <ToggleButton.CacheMode>
        
    </ToggleButton.CacheMode>
</ToggleButton>

Increase the RenderAtScale value, will sharpen the control, but it will also make it more pixelized when drawn smaller.

[!NOTE]
The default value of UIElement.CacheMode is null.

Advanced: setting `ShadowAssist.CacheMode` Copy Chapter

Material Design in XAML toolkit also provides you with an attached property ShadowAssist.CacheMode.
This attached property is used in places where a simple CacheMode property would not suffice. This could be in situations
where the property should be inherited, as UIElement.CacheMode does not support property inheritance.

This attached property is set through binding on a CacheMode property under the parent control.

An example of this property being used:

<AdornerDecorator CacheMode="{Binding RelativeSource={RelativeSource Self}, Path=(wpf:ShadowAssist.CacheMode)}">
    <Ellipse x:Name="Thumb" ... />
</AdornerDecorator>

[!NOTE]
The default value of ShadowAssist.CacheMode is null.

Example Copy Chapter

Further reading Copy Chapter

Some interesting articles with more in-depth information:

• Property value inheritance (WPF .NET)
• UIElement.CacheMode Property