## File: README.md

# Material Design In XAML Toolkit 

[](https://www.nuget.org/packages/MaterialDesignThemes/)
[](https://www.nuget.org/packages/MaterialDesignColors/)

[)](https://www.nuget.org/packages/MaterialDesignThemes/)
[)](https://www.nuget.org/packages/MaterialDesignColors/)

[](#backers) 
[](#sponsors) 
[][discord-server-url]
[](https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/issues)


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](https://material.io/design/)
- Full [Material Design Icons](https://materialdesignicons.com/) icon pack
- Easy transition effects
- Compatible with [Dragablz](https://github.com/ButchersBoy/Dragablz), [MahApps](https://github.com/MahApps/MahApps.Metro)
- Demo applications included in the source project

[See screenshots](#screenshots)


  Table of contents

- [Getting started](#getting-started)
- [Building the source](#building-the-source)
- [Screenshots](#screenshots)
- [More examples](#more-examples)
- [FAQ](#faq)
- [Contributing](#contributing)
- [Mentions](#mentions)
- [Backers](#backers)
- [Sponsors](#sponsors)



---

## Getting started

> [!NOTE]
> See the [full starting guide](https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/wiki/Getting-Started) 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`

```xml
<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`

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

### XML Namespaces

The toolkit exposes two XML namespaces for use in XAML:

| Prefix | URI | Description |
|--------|-----|-------------|
| `materialDesign` | `http://materialdesigninxaml.net/winfx/xaml/themes` | Primary namespace for all public Material Design types, controls, and converters. |
| `materialDesignInternal` | `http://materialdesigninxaml.net/winfx/xaml/themes-internal` | Namespace for types in internal sub-namespaces (`MaterialDesignThemes.Wpf.Internal`, `MaterialDesignThemes.Wpf.Converters.Internal`, `MaterialDesignThemes.Wpf.Behaviors.Internal`). |

> [!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:

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


## Building the source

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


  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

* [Keboo/MaterialDesign.Examples](https://github.com/Keboo/MaterialDesignInXaml.Examples)
* [Motion List](https://github.com/MaterialDesignInXAML/MotionList)

## FAQ

* [How to increase rendering performance?](docs/rendering-performance.md)

## Contributing

Before contributing code read the [Contribution Guidelines](.github/CONTRIBUTING.md)
* GitHub issues are for bugs and feature requests.
* For questions, help and chat in general, please use the [GitHub discussion tab](https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/discussions) or the [Discord server][discord-server-url].
* Stack Overflow tag: [`material-design-in-xaml`](http://stackoverflow.com/questions/tagged/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](https://opencollective.com/materialdesigninxaml)

This project exists thanks to all the people who contribute.

<a href="https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/graphs/contributors">
  
</a>

## Mentions

- **[James Willock](https://github.com/ButchersBoy)
[](https://twitter.com/James_Willock)** - Founder of the project
- **[Kevin Bost](https://github.com/Keboo)
[](https://twitter.com/kitokeboo)** - Maintainer of the repository
- [Snalty](https://github.com/snalty)
[](https://twitter.com/snalty) - Designer of the logo
- Icon pack sourced from [Material Design Icons](https://materialdesignicons.com/)
- [ControlzEx](https://github.com/ControlzEx/ControlzEx) - Library used in MaterialDesignInXAML
- [Ignace Maes](https://github.com/IgnaceMaes) - Whose [Material Skin](https://github.com/IgnaceMaes/MaterialSkin) project inspired the original material design theme for [Dragablz](https://github.com/ButchersBoy/Dragablz), which in turn led James Willock start this project
- [Material Design Extensions](https://github.com/spiegelp/MaterialDesignExtensions) - A community repository based on this library that provides additional controls and features.
- **[Contributors](https://github.com/MaterialDesignInXAML/MaterialDesignInXamlToolkit/graphs/contributors)** - A big thank you to all the contributors of the project!

## Backers

Thank you to all our backers! 🙏 [Become a backer.](https://opencollective.com/materialdesigninxaml#backer)

[](https://opencollective.com/materialdesigninxaml#backers)

## Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor.](https://opencollective.com/materialdesigninxaml#sponsor)

[](https://opencollective.com/materialdesigninxaml/sponsor/0/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/1/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/2/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/3/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/4/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/5/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/6/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/7/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/8/website)
[](https://opencollective.com/materialdesigninxaml/sponsor/9/website)

[discord-server-url]: https://discord.keboo.dev

---

## File: docs/Freezable_Object_for_Enhanced_Performance.md

[Home](..\README.md) > Using `Freezable` Objects for Enhanced Performance

---

# Using `Freezable` Objects for Enhanced Performance

## Background information

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`

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

```csharp
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

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

[Home](..\README.md) > How to Optimize UI Thread Performance?

---

# How to Optimize UI Thread Performance?

## Background information

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`

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:

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

## Avoiding Complex Bindings

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.

```xaml

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

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

## Use `VirtualizingStackPanel` for Large Lists

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

```xaml
<ListBox VirtualizingStackPanel.IsVirtualizing="True" />
```

This reduces memory usage and improves scrolling performance in lists.

---

## File: docs/Optimizing-WPF-Rendering-Performance.md

[Home](..\README.md) > Optimizing WPF UI Animation and Rendering Performance

---

# Optimizing WPF UI Animation and Rendering Performance

## Background Information

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

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

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

```xaml

```

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

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

```xaml
<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

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

```csharp
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

| Method                             | Performance Impact                                                                                   |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Reducing Visual Layers             | Lowers CPU and GPU workload by limiting the number of visual elements rendered                       |
| Using `RenderOptions.BitmapScalingMode` | Improves image scaling performance, particularly during animation                                  |
| Enabling Virtualization            | Optimizes scrolling in large data sets, leading to faster rendering times                           |
| `CompositionTarget` for Animations | Provides smoother animations at the expense of higher complexity; best suited for high-priority elements |

## Further Reading

Additional resources for improving WPF performance:
- [Optimizing WPF Application Performance](https://learn.microsoft.com/dotnet/desktop/wpf/advanced/optimizing-wpf-application-performance?view=netdesktop-7.0)
- [Rendering Performance Best Practices](https://learn.microsoft.com/dotnet/desktop/wpf/graphics-multimedia/rendering-performance-best-practices?view=netdesktop-7.0)

---

## File: docs/Reducing_Layout_Complexity.md

# Reducing Layout Complexity

## Background information

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

## Avoid Nested Grids and StackPanels

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

```xaml

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

## Prefer Static Resources Over Dynamic Resources

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

```xaml

<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

[Home](..\README.md) > How to increase rendering performance?

---

# How to increase rendering performance?

## Background information

Every class inheriting from [`UIElement`](https://learn.microsoft.com/dotnet/api/system.windows.uielement?view=windowsdesktop-8.0) 
contains a property [`CacheMode`](https://learn.microsoft.com/dotnet/api/system.windows.uielement.cachemode?view=windowsdesktop-8.0). 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](https://learn.microsoft.com/dotnet/api/system.windows.media.bitmapcache?view=windowsdesktop-8.0).

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

## Setting `UIElement.CacheMode`

An example how to set a `CacheMode`:

```xaml


<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`

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:
```xaml


<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

| With `CacheMode` set                                                                                                              | Without `CacheMode` set                                                                                                           |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|  |  |

## Further reading

Some interesting articles with more in-depth information:
* [Property value inheritance (WPF .NET)](https://learn.microsoft.com/dotnet/desktop/wpf/properties/property-value-inheritance?view=netdesktop-7.0)
* [UIElement.CacheMode Property](https://learn.microsoft.com/dotnet/api/system.windows.uielement.cachemode?view=windowsdesktop-8.0)