Uno Material

Material design system

Important

UnoFeatures: Material — add <UnoFeatures>Material</UnoFeatures> to your app's .csproj to add Uno Material.

The Uno Material library is enabled through the Material UnoFeatures, which brings in the required packages for new and existing Uno Platform solutions. Uno Material lets you apply Material Design 3 styling to your application with just a few lines of code.

Warning

If you are updating Uno Material to v2 from an older 1.x version of the package, additional steps will be required. Refer to the Uno Material Migration Guide.

Getting Started

Initialization of the Uno Material resources is handled by the specialized MaterialTheme ResourceDictionary.

`MaterialTheme`

Constructors

Constructor	Description
`MaterialTheme()`	Initializes a new instance of the `MaterialTheme` resource dictionary.
`MaterialTheme(ResourceDictionary? colorOverride, ResourceDictionary? fontOverride)`	Initializes a new instance of the `MaterialTheme` resource dictionary and applies the given overrides

Properties

Property	Type	Description
`Colors`	`ThemeColors`	(Optional) Groups all color configuration: seed colors (`PrimarySeed`, …), the generation mode (`SeedColorMode`), and color overrides. See Seed Color Palette.
`FontOverrideSource`	`string`	(Optional) Gets or sets a Uniform Resource Identifier that provides the source location of a `ResourceDictionary` containing overrides for the default Uno Material font resources
`FontOverrideDictionary`	`ResourceDictionary`	(Optional) Gets or sets a `ResourceDictionary` containing overrides for the default Uno Material font resources, as an inline alternative to `FontOverrideSource`
`DefaultCornerRadius`	`double`	(Optional) Base corner-radius unit driving the shape design tokens. See Design Tokens.
`DefaultSpacing`	`double`	(Optional) Base spacing unit (default 8) driving the spacing design tokens; scaled by the `DefaultDensity` mode. See Design Tokens.
`DefaultDensity`	`Density`	(Optional) Density mode (`Compact` / `Regular` / `Comfy`) scaling the spacing base unit by ×0.75 / ×1 / ×1.25. See Design Tokens.
`DefaultFontFamily`	`FontFamily`	(Optional) The font the whole type scale is generated from; left unset, Roboto stands. See Change Default Font.
`ColorOverrideSource`	`string`	(Deprecated) Use `OverrideSource` on `Colors` instead — see the migration notes.

Creating a new project with Uno Material

Note

Make sure to setup your environment first by following our instructions.

Wizard
CLI

Follow the steps in the Getting Started with Visual Studio instructions to launch the Uno Platform Template Wizard.
Select Material under the Theme section.

Installing Uno Material in an existing project

Depending on the type of project template that the Uno Platform application was created with, follow the instructions below to install Uno Material.

Edit your project file (PROJECT_NAME.csproj) and add Material to the list of UnoFeatures:
```
<UnoFeatures>Material</UnoFeatures>
```

Initialize MaterialTheme in the App.xaml:

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>

            <!-- Code ommitted of brevity -->

            <MaterialTheme xmlns="using:Uno.Material" />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

Note

Use this only when working on older multi-head templates that do not support UnoFeatures. Modern templates should use the Single Project instructions above.

In the Solution Explorer panel, right-click on your app's App Code Library project (PROJECT_NAME.csproj) and select Manage NuGet Packages...
Install the Uno.Material.WinUI

Add the following Material resources to AppResources.xaml:

<ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>

        <!-- Load Uno Material resources -->
        <MaterialTheme xmlns="using:Uno.Material" />

    </ResourceDictionary.MergedDictionaries>
</ResourceDictionary>

Note

Use this only when working on older .shproj-based solutions that do not support UnoFeatures. Modern templates should use the Single Project instructions above.

In the Solution Explorer panel, right-click on your solution name and select Manage NuGet Packages for Solution .... Choose either:
- The Uno.Material package when targetting Xamarin/UWP
- The Uno.Material.WinUI package when targetting net6.0+/WinUI
Select the following projects for installation:
- PROJECT_NAME.Wasm.csproj
- PROJECT_NAME.Mobile.csproj (or PROJECT_NAME.iOS.csproj, PROJECT_NAME.Droid.csproj, and PROJECT_NAME.macOS.csproj if you have an existing project)
- PROJECT_NAME.csproj (the net*-desktop Skia Desktop head)
- PROJECT_NAME.Windows.csproj (or PROJECT_NAME.UWP.csproj for existing projects)

Add the following resources inside App.xaml:

<Application ...>
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>

                <!-- Load WinUI resources -->
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />

                <!-- Load Uno Material resources -->
                <MaterialTheme xmlns="using:Uno.Material" />

                <!-- Load custom application resources -->
                <!-- ... -->

            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>

Customization

Seed Color Palette

The fastest way to a custom color theme: provide a single seed color — typically your brand color — and the library generates the complete Light and Dark palette from it, with readable text contrast built in. No resource dictionaries to write, and the seed can even be changed at runtime. See the Seed Color Palette documentation.

The guides below give you full manual control instead. They require the creation of new ResourceDictionary files in your application project. For more information on how to define styles and resources in a separate ResourceDictionary, refer to the resource management documentation.

Color Overrides using Material Theme Builder and DSP format

It is possible to use the Material Theme Builder to generate a custom color palette derived from your own basic colors. The generated palette is provided in the DSP format and can be used to override the default Uno Material colors.

The tooling required to generate the Material Colors Override file from a theme file (JSON file) will be present by default when creating an Uno Platform application with support for Uno Material from the Wizard.

Wizard - Theme Selection

Follow this link to get more Information about the DSP tooling.

Manual Color Overrides

Use this when you want to manually override the default color palette from the Uno Material library.

Add a new Resource Dictionary named MaterialColorsOverride.xaml to the application project, for example, under Styles/Application.

Replace the content with:

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <ResourceDictionary.ThemeDictionaries>

        <!-- Light Theme -->
        <ResourceDictionary x:Key="Light">
            <!-- Primary -->
            <Color x:Key="PrimaryColor">#6750A4</Color>
            <Color x:Key="PrimaryInverseColor">#D0BCFF</Color>
            <Color x:Key="OnPrimaryColor">#FFFFFF</Color>
            <Color x:Key="PrimaryContainerColor">#EADDFF</Color>
            <Color x:Key="OnPrimaryContainerColor">#21005E</Color>

            <!-- Primary Variant Legacy Colors -->
            <Color x:Key="PrimaryVariantDarkColor">#353FE5</Color>
            <Color x:Key="PrimaryVariantLightColor">#B6A8FB</Color>

            <!-- Secondary -->
            <Color x:Key="SecondaryColor">#625B71</Color>
            <Color x:Key="OnSecondaryColor">#FFFFFF</Color>
            <Color x:Key="SecondaryContainerColor">#E5DFF9</Color>
            <Color x:Key="OnSecondaryContainerColor">#1B192C</Color>

            <!-- Secondary Variant Legacy Colors -->
            <Color x:Key="SecondaryVariantDarkColor">#2BB27E</Color>
            <Color x:Key="SecondaryVariantLightColor">#9CFFDF</Color>

            <!-- Tertiary -->
            <Color x:Key="TertiaryColor">#7D5260</Color>
            <Color x:Key="OnTertiaryColor">#FFFFFF</Color>
            <Color x:Key="TertiaryContainerColor">#FFD8E4</Color>
            <Color x:Key="OnTertiaryContainerColor">#370B1E</Color>

            <!-- Error -->
            <Color x:Key="ErrorColor">#B3261E</Color>
            <Color x:Key="OnErrorColor">#FFFFFF</Color>
            <Color x:Key="ErrorContainerColor">#F9DEDC</Color>
            <Color x:Key="OnErrorContainerColor">#370B1E</Color>

            <!-- Background -->
            <Color x:Key="BackgroundColor">#FFFBFE</Color>
            <Color x:Key="OnBackgroundColor">#1C1B1F</Color>

            <!-- Surface -->
            <Color x:Key="SurfaceColor">#FFFBFE</Color>
            <Color x:Key="OnSurfaceColor">#1C1B1F</Color>
            <Color x:Key="SurfaceVariantColor">#E7E0EC</Color>
            <Color x:Key="OnSurfaceVariantColor">#A5A0AC</Color>
            <Color x:Key="SurfaceInverseColor">#313033</Color>
            <Color x:Key="OnSurfaceInverseColor">#F4EFF4</Color>
            <Color x:Key="SurfaceTintColor">#5946D2</Color>

            <!-- Outline -->
            <Color x:Key="OutlineColor">#79747E</Color>
            <Color x:Key="OutlineVariantColor">#C9C5D0</Color>
        </ResourceDictionary>

        <!-- Dark Theme -->
        <ResourceDictionary x:Key="Dark">
            <!-- Primary -->
            <Color x:Key="PrimaryColor">#D0BCFF</Color>
            <Color x:Key="OnPrimaryColor">#371E73</Color>
            <Color x:Key="PrimaryContainerColor">#4F378B</Color>
            <Color x:Key="OnPrimaryContainerColor">#EADDFF</Color>
            <Color x:Key="PrimaryInverseColor">#6750A4</Color>

            <!-- Primary Variant Legacy Colors -->
            <Color x:Key="PrimaryVariantDarkColor">#353FE5</Color>
            <Color x:Key="PrimaryVariantLightColor">#D4CBFC</Color>

            <!-- Secondary -->
            <Color x:Key="SecondaryColor">#CCC2DC</Color>
            <Color x:Key="OnSecondaryColor">#332D41</Color>
            <Color x:Key="SecondaryContainerColor">#474459</Color>
            <Color x:Key="OnSecondaryContainerColor">#E5DFF9</Color>

            <!-- Secondary Variant Legacy Colors -->
            <Color x:Key="SecondaryVariantDarkColor">#2BB27E</Color>
            <Color x:Key="SecondaryVariantLightColor">#9CFFDF</Color>

            <!-- Tertiary -->
            <Color x:Key="TertiaryColor">#EFB8C8</Color>
            <Color x:Key="OnTertiaryColor">#492532</Color>
            <Color x:Key="TertiaryContainerColor">#633B48</Color>
            <Color x:Key="OnTertiaryContainerColor">#FFD8E4</Color>

            <!-- Error -->
            <Color x:Key="ErrorColor">#F2B8B5</Color>
            <Color x:Key="OnErrorColor">#601410</Color>
            <Color x:Key="ErrorContainerColor">#8C1D18</Color>
            <Color x:Key="OnErrorContainerColor">#F9DEDC</Color>

            <!-- Background -->
            <Color x:Key="BackgroundColor">#1C1B1F</Color>
            <Color x:Key="OnBackgroundColor">#E6E1E5</Color>

            <!-- Surface -->
            <Color x:Key="SurfaceColor">#1C1B1F</Color>
            <Color x:Key="OnSurfaceColor">#E6E1E5</Color>
            <Color x:Key="SurfaceVariantColor">#49454F</Color>
            <Color x:Key="OnSurfaceVariantColor">#CAC4D0</Color>
            <Color x:Key="SurfaceInverseColor">#E6E1E5</Color>
            <Color x:Key="OnSurfaceInverseColor">#313033</Color>
            <Color x:Key="SurfaceTintColor">#C7BFFF</Color>

            <!-- Outline -->
            <Color x:Key="OutlineColor">#938F99</Color>
            <Color x:Key="OutlineVariantColor">#57545D</Color>
        </ResourceDictionary>

    </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

In App.xaml, update <MaterialTheme /> with the override from the previous steps:

<MaterialTheme xmlns="using:Uno.Material"
               ColorOverrideSource="ms-appx:///Styles/Application/MaterialColorsOverride.xaml" />

Change Default Font

By default, Uno Material comes pre-packaged with the Roboto font family and automatically includes it in your application. Every type scale derives from the single DefaultFontFamily root token; per-scale weight nuance comes from the *FontWeight tokens, resolved from that one family reference.

If you would like Uno Material to use a different font:

Add the custom font following Custom Fonts documentation. Prefer a family that resolves multiple weights (a variable font, or a font shipping a font manifest) so the *FontWeight tokens render as designed.

In App.xaml, set the DefaultFontFamily property on the theme:

<MaterialTheme xmlns="using:Uno.Material"
               DefaultFontFamily="ms-appx:///Assets/Fonts/MyCustomFont.ttf#MyCustomFont" />

That one value regenerates the DefaultFontFamily root token and every type-scale *FontFamily key derived from it, and it can also be changed at runtime — see Typography Font Swap.

To change only some appearances or some scales instead, provide a font override dictionary:

Add a Resource Dictionary named MaterialFontsOverride.xaml to the application project, for example under Styles/Application, and redefine the individual *FontFamily token(s) in it:

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <FontFamily x:Key="DisplayLargeFontFamily">ms-appx:///Assets/Fonts/MyCustomFont.ttf#MyCustomFont</FontFamily>
    <FontFamily x:Key="DisplayMediumFontFamily">ms-appx:///Assets/Fonts/MyCustomFont.ttf#MyCustomFont</FontFamily>

</ResourceDictionary>

In App.xaml, reference it from the theme:

<MaterialTheme xmlns="using:Uno.Material"
               FontOverrideSource="ms-appx:///Styles/Application/MaterialFontsOverride.xaml" />

A key declared in the override wins over the generated one — see Typography Font Swap.

Important

Overriding the legacy MaterialLightFontFamily / MaterialMediumFontFamily / MaterialRegularFontFamily keys no longer changes the type scales — see the migration notes.

Using C# Markup

Uno Material also has support for C# Markup through a Uno.Material.WinUI.Markup NuGet Package.

To get started with Uno Material in your C# Markup application, add the Uno.Material.WinUI.Markup NuGet package to your application project.

Then, add the following code to your App.xaml.cs:

using Uno.Material.Markup;

this.Build(r => r.UseMaterial(
     //optional
     new Styles.ColorPaletteOverride(),
     //optional
     new Styles.MaterialFontsOverride()));

Uno Material

Important

Warning

Getting Started

MaterialTheme

Constructors

Properties

Creating a new project with Uno Material

Note

Installing Uno Material in an existing project

Customization

Seed Color Palette

Color Overrides using Material Theme Builder and DSP format

Manual Color Overrides

Change Default Font

Important

Using C# Markup

Additional Resources

`MaterialTheme`