Upgrading Uno Material

Important

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

Upgrading to Uno Themes v8

Uno Themes 8.0 reworks seed color generation so the palette faithfully reproduces the seed color you provide. If your app never sets PrimarySeed, nothing changes — the built-in palettes, style keys, and brush resources are untouched, and you can upgrade without code changes. If your app does use a seed, the generated colors will look different after the upgrade — the sections below explain how and why.

Seed-generated palettes look different

Two changes affect every app that sets PrimarySeed:

  • A color-math fix. 7.x silently washed out saturated seeds — a vivid brand color generated a muted palette. 8.0 corrects this, so generated palettes are more vivid in every mode. This part of the change has no opt-out.
  • A new default generation mode. The default is now SeedColorMode="Fidelity": the light PrimaryColor is your seed color verbatim, the color rendered on top of it (OnPrimaryColor) is picked automatically for readable contrast, and the supporting palettes follow the seed's saturation — a muted seed now produces a muted palette. To keep the previous always-vibrant recipe, set SeedColorMode="TonalSpot":
<MaterialTheme xmlns="using:Uno.Material">
    <MaterialTheme.Colors>
        <ut:ThemeColors xmlns:ut="using:Uno.Themes"
                        PrimarySeed="#6750A4"
                        SeedColorMode="TonalSpot" />
    </MaterialTheme.Colors>
</MaterialTheme>

See Two generation modes for the full description of both modes and guidance on which to choose.

UseHighFidelityColors is now obsolete

This only affects code that subclasses BaseTheme. The protected UseHighFidelityColors property is [Obsolete], replaced by the public SeedColorMode property on ThemeColors (also available at runtime via SemanticThemeHelper.SeedColorMode). An existing override keeps working — true maps to Fidelity and false to TonalSpot — but an explicit SeedColorMode assignment on Colors wins over the override.

Runtime seed changes repaint immediately

Changing a seed color at runtime now recolors everything already on screen — including the HighContrast theme — with no page re-navigation or theme toggle needed. If your app worked around the 7.x behavior by recreating its root content after a seed change, that workaround can be removed. See Runtime Seed Color Changes.

To make this possible, the semantic *Brush resources are now shared, long-lived instances whose Color and Opacity are rewritten in place when a seed or override changes. If your code caches a brush.Color snapshot or expects a fresh brush instance per theme rebuild, hold on to the resource key instead.

Upgrading to Uno Themes v7

Uno Themes 7.0 introduces the Simple design system, the theme-agnostic Semantic Design Language, design tokens, and opt-in seed color generation. Visual defaults are unchanged — no semantic color or brush resource key was renamed or removed, and seed generation is off unless you enable it — so most apps upgrade without code changes. The sections below cover the changes that may require action.

What's new in v7

  • Simple theme: new Uno.Simple.WinUI and Uno.Simple.WinUI.Markup packages providing a minimal, density-driven design system. See Simple - Getting Started.
  • Semantic Design Language: design-system-agnostic style aliases (FilledButtonStyle, OutlinedTextBoxStyle, …) shared by Material and Simple, so apps can switch design systems without changing style keys. See Semantic Design Language.
  • Design tokens: spacing (Space*), shape (Radius*), and density (ControlHeight*, IconSize*) tokens, driven globally by the new DefaultSpacing, DefaultDensity, and DefaultCornerRadius theme properties. See Design Tokens.
  • Seed color generation (opt-in): generate a full palette from one or more seed colors via the new Colors property (ThemeColors) and SemanticThemeHelper. See Seed Color Palette.
  • Control extensions: new ControlExtensions.LeadingIcon and ControlExtensions.TrailingIcon attached properties; ControlExtensions.Icon keeps working and now forwards its value to LeadingIcon. See Control Extensions.
  • XAML Hot Reload: theme resources now participate in Hot Reload.

Cupertino styles are unchanged in v7.

Packages and dependencies

Uno Themes 7.0 requires Uno.WinUI 6.4.229 or later. If your app uses the Uno SDK with UnoFeatures (for example <UnoFeatures>Material</UnoFeatures>), package versions are managed automatically and no action is needed; apps pinning package versions manually should update Uno.WinUI accordingly.

The packages no longer include macOS and Mac Catalyst (net9.0-macos / net9.0-maccatalyst) binaries. Move these heads to the Skia Desktop target (net9.0-desktop) instead.

BaseTheme API changes

This only affects code that subclasses BaseTheme to build a custom design system — apps consuming MaterialTheme, CupertinoTheme, or SimpleTheme from XAML are unaffected. GenerateSpecificResources() has been removed: provide the static styles URI through the new DefaultStylesSource property, and append dynamic resource dictionaries with AddThemeDictionary() from an AddThemeSpecificResources() override.

ColorOverrideSource and ColorOverrideDictionary deprecated

Color configuration is now grouped on the new Colors property, a ThemeColors object that also hosts the seed color properties. The legacy properties are deprecated but still work — they write through to the corresponding Colors members internally:

Deprecated member Replacement
BaseTheme.ColorOverrideSource OverrideSource on Colors (ThemeColors)
BaseTheme.ColorOverrideDictionary OverrideDictionary on Colors (ThemeColors)

Before:

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

After:

<MaterialTheme xmlns="using:Uno.Material">
    <MaterialTheme.Colors>
        <ut:ThemeColors xmlns:ut="using:Uno.Themes"
                        OverrideSource="ms-appx:///Styles/ColorPaletteOverride.xaml" />
    </MaterialTheme.Colors>
</MaterialTheme>

FontOverrideSource and FontOverrideDictionary are not deprecated and keep working unchanged.

Important

Seed generation is opt-in and no theme sets a default seed, so an upgraded app renders with exactly the same colors as 6.1, and explicit color overrides keep winning over everything else — including seed-generated palettes. For the full precedence order, see Color Precedence.

Typography and font overrides

Existing Material font overrides (MaterialRegularFontFamily / MaterialMediumFontFamily) continue to work. For overrides meant to apply across design systems, prefer the new root typeface tokens, which cascade through the whole type scale — see Typography:

Legacy key (Material-specific) Portable token Cascades to
MaterialRegularFontFamily TypefacePlain Display, Headline
MaterialMediumFontFamily TypefaceBrand Title, Label, Body, Caption

Material style changes

Native mobile styles removed

On iOS and Android, the Material v1 ToggleSwitch styles and MaterialCommandBarStyle no longer render the native platform controls — they now use the same XAML templates as all other platforms, which are close to, but not pixel-identical to, the native look. The NativeCommandBarTemplate resource key has been removed.

AppBarButton layout and text wrapping

The Material AppBarButton content now stretches horizontally and its label wraps by default (long labels previously stayed on a single centered line), and the ripple effect now honors the control's CornerRadius. To restore the previous single-line behavior, override the new AppBarButtonTextWrapping resource via Lightweight Styling:

<TextWrapping x:Key="AppBarButtonTextWrapping">NoWrap</TextWrapping>

Sizing resources are now design-token aliases

Material v2 sizing, spacing, and corner-radius resources are no longer hard-coded literals — they alias the new global design tokens. All values are numerically identical to 6.1 at the default settings, and per-key Lightweight Styling overrides keep working. Representative examples:

Resource Key 6.1 value Now aliases Default value
ButtonMinHeight 40 ControlHeightMedium 40
ButtonPadding 16,0 Space400HorizontalThickness 16,0
ButtonCornerRadius 20 Radius500CornerRadius 20

Roughly forty keys across all Material v2 controls follow this pattern. Because the values are now derived, the new DefaultSpacing, DefaultDensity (Compact / Regular / Comfy), and DefaultCornerRadius theme properties reshape every Material control globally. See Design Tokens.

StringFormatConverter is now culture-aware

StringFormatConverter now formats using the binding's ConverterLanguage (a BCP-47 tag), falling back to CultureInfo.CurrentCulture — previously it used the invariant culture. Culture-sensitive formats such as {0:d} now render localized; set ConverterLanguage on the binding to pin a specific culture.

Upgrading to Uno Themes v5

The Uno Material v5 packages introduce a new dependency on the Uno Themes package. Uno Themes is the base library for all design system implementations going forward. As a result, the following changes have been made:

Upgrading to Uno Themes 5.8

Button focus states resources removal

This update simplifies focus handling in Button style templates by removing redundant "Focused" and "PointerFocused" resource values:

Removed Resource Key
ElevatedButtonForegroundFocused
ElevatedButtonForegroundPointerFocused
ElevatedButtonIconForegroundFocused
ElevatedButtonIconForegroundPointerFocused
ElevatedButtonBackgroundFocused
ElevatedButtonBackgroundPointerFocused
ElevatedButtonBorderBrushFocused
ElevatedButtonBorderBrushPointerFocused
ElevatedButtonStateLayerBackgroundFocused
ElevatedButtonStateLayerBackgroundPointerFocused
FilledButtonForegroundPointerFocused
FilledButtonForegroundFocused
FilledButtonIconForegroundFocused
FilledButtonIconForegroundPointerFocused
FilledButtonBackgroundFocused
FilledButtonBackgroundPointerFocused
FilledButtonBorderBrushFocused
FilledButtonBorderBrushPointerFocused
FilledButtonStateLayerBackgroundFocused
FilledButtonStateLayerBackgroundPointerFocused
FilledTonalButtonForegroundFocused
FilledTonalButtonForegroundPointerFocused
FilledTonalButtonIconForegroundFocused
FilledTonalButtonIconForegroundPointerFocused
FilledTonalButtonBackgroundFocused
FilledTonalButtonBackgroundPointerFocused
FilledTonalButtonBorderBrushFocused
FilledTonalButtonBorderBrushPointerFocused
FilledTonalButtonStateLayerBackgroundFocused
FilledTonalButtonStateLayerBackgroundPointerFocused
OutlinedButtonForegroundFocused
OutlinedButtonForegroundPointerFocused
OutlinedButtonIconForegroundFocused
OutlinedButtonIconForegroundPointerFocused
OutlinedButtonBackgroundFocused
OutlinedButtonBackgroundPointerFocused
OutlinedButtonBorderBrushFocused
OutlinedButtonBorderBrushPointerFocused
OutlinedButtonStateLayerBackgroundFocused
OutlinedButtonStateLayerBackgroundPointerFocused
TextButtonForegroundFocused
TextButtonForegroundPointerFocused
TextButtonIconForegroundFocused
TextButtonIconForegroundPointerFocused
TextButtonBackgroundFocused
TextButtonBackgroundPointerFocused
TextButtonBorderBrushFocused
TextButtonBorderBrushPointerFocused
TextButtonStateLayerBackgroundFocused
TextButtonStateLayerBackgroundPointerFocused

Upgrading to Uno Themes 5.4

We have standardized the naming of styles and resource keys. This change aims to simplify resource key usage and align the naming convention across Uno Themes.

Changes to Resource Keys

Old Resource Key New Resource Key
MaterialTextBoxClearGlyphWidth TextBoxClearGlyphWidth
MaterialTextBoxClearGlyphHeight TextBoxClearGlyphHeight
MaterialFilledTextBoxCornerRadius FilledTextBoxCornerRadius
MaterialFilledTextBoxPadding FilledTextBoxPadding
MaterialFilledTextBoxMinHeight FilledTextBoxMinHeight
MaterialFilledTextBoxBorderHeightFocused FilledTextBoxBorderHeightFocused
MaterialOutlinedTextBoxBorderThickness OutlinedTextBoxBorderThickness
MaterialOutlinedTextBoxCornerRadius OutlinedTextBoxCornerRadius
MaterialOutlinedTextBoxPadding OutlinedTextBoxPadding
MaterialOutlinedTextBoxMinHeight OutlinedTextBoxMinHeight
MaterialOutlinedTextBoxBorderThicknessFocused OutlinedTextBoxBorderThicknessFocused
MaterialOutlinedTextBoxBorderThicknessPointerOver OutlinedTextBoxBorderThicknessPointerOver
OutlinedPasswordBoxBorderPadding REMOVED
OutlinedPasswordBoxBorderPaddingPointerOver REMOVED
OutlinedPasswordBoxBorderPaddingFocused REMOVED

Upgrading to Uno Themes 5.1

TextBox PlaceholderText and Header

Previously, the PlaceholderText property acted as a header, displaying in the normal state and animating upwards when the text is set or being entered. And, the Header property did nothing. Now, both PlaceholderText and Header are supported and their behaviors have changed.

New Behavior
  • PlaceholderText: Displays inside the TextBox when it's empty. Disappears when text is entered.
  • Header: Acts as a label. Animates upwards when text is entered.
Example

Old Usage:

<TextBox PlaceholderText="Enter your name" />

New Usage:

<TextBox PlaceholderText="Enter your name" Header="Name" />

Update your TextBox elements to use Header for labels and PlaceholderText for placeholders.

Converters

All Converters were moved to the base Uno.Themes library, and the new namespace is Uno.Themes.

Before:

<Page xmlns:um="using:Uno.Material">
    <Page.Resources>
        <um:FromNullToValueConverter x:Key="NotNullVisibilityConverter">
    </Page.Resources>
</Page>

After:

<Page xmlns:ut="using:Uno.Themes">
    <Page.Resources>
        <ut:FromNullToValueConverter x:Key="NotNullVisibilityConverter">
    </Page.Resources>
</Page>

Some Converters have been renamed, you can find the Old Name and New Name in the table below:

Old Name New Name
MaterialTrueToVisible TrueToVisibleConverter
MaterialTrueToCollapsed TrueToCollapsedConverter
CheckBoxIsCheckedToFocusStateCircleVisible FalseToCollapsedConverter
CheckBoxIsCheckedToFocusStateCircleCollapsed FalseToVisibleConverter
MaterialEmptyToFalse/
CupertinoEmptyToFalse		 EmptyToFalseConverter
MaterialEmptyToTrue/
CupertinoEmptyToTrue		 EmptyToTrueConverter
MaterialEmptyToVisible EmptyToVisibleConverter
MaterialEmptyToCollapsed EmptyToCollapsedConverter
MaterialNullToCollapsedConverter/
CupertinoNullToCollapsedConverter		 NullToCollapsedConverter
MaterialNullToVisibleConverter NullToVisibleConverter
MaterialNullToTransparent NullToTransparentConverter
MaterialEmptyOrNullToVisible EmptyOrNullToVisibleConverter
MaterialEmptyOrNullToCollapsed EmptyOrNullToCollapsedConverter
StringFormatConverter StringFormatConverter
FirstCharacterConverter FirstCharacterConverter
ToUpperConverter ToUpperConverter

Control Extensions

All Controls Extensions were moved to the Uno.Themes library, and the new namespace is Uno.Themes.

Before:

<Page xmlns:um="using:Uno.Material">
    <StackPanel>
        <Button Content="OUTLINED"
            Style="{StaticResource MaterialOutlinedButtonStyle}">
            <um:ControlExtensions.Icon>
                <FontIcon Glyph="&#xE946;" />
            </um:ControlExtensions.Icon>
        </Button>
    </StackPanel>
</Page>

After:

<Page xmlns:ut="using:Uno.Themes">
    <StackPanel>
        <Button Content="OUTLINED"
            Style="{StaticResource MaterialOutlinedButtonStyle}">
            <ut:ControlExtensions.Icon>
                <FontIcon Glyph="&#xE946;" />
            </ut:ControlExtensions.Icon>
        </Button>
    </StackPanel>
</Page>

Opacity and brushes

The opacity values of certain brushes has been adjusted to better align with the Figma design file:

Opacity variant Old Value New Value
Medium 0.54 0.64
Disabled 0.38 0.12
DisabledLow 0.12 removed

Existing explicit references to -DisabledLow resources should now be updated to use -Disabled.

Resources

Certain Lightweight Styling resource keys have been edited to align with those coming from Microsoft.UI.Xaml.

RatingControl

Old Key New Key
RatingControlForegroundUnselected RatingControlUnselectedForeground
RatingControlForegroundSelected RatingControlSelectedForeground
RatingControlForegroundPointerOverUnselected RatingControlUnselectedForegroundPointerOver
RatingControlForegroundPointerOverSelected RatingControlSelectedForegroundPointerOver
RatingControlForegroundDisabledSelected RatingControlSelectedForegroundDisabled
SecondaryRatingControlForegroundUnselected SecondaryRatingControlUnselectedForeground
SecondaryRatingControlForegroundSelected SecondaryRatingControlSelectedForeground
SecondaryRatingControlForegroundPointerOverUnselected SecondaryRatingControlUnselectedForegroundPointerOver
SecondaryRatingControlForegroundPointerOverSelected SecondaryRatingControlSelectedForegroundPointerOver
SecondaryRatingControlForegroundDisabledSelected SecondaryRatingControlSelectedForegroundDisabled

Upgrading to Uno.Material v3

Uno.Material v3 (not to be confused with Material Design 3 from Google) introduces support for Lightweight Styling as well as some breaking changes to the default style keys for some controls. Refer to the tables below for the changes that have been made within Uno.Material.

Styles

Removed

Key TargetType
DefaultMaterialCalendarViewStyle CalendarView
MaterialSecondaryCheckBoxStyle CheckBox
MaterialSecondaryRadioButtonStyle RadioButton

Added

Key Aliased Key TargetType Implicit Style
MaterialRatingControlStyle RatingControlStyle muxc:RatingControl true
MaterialRippleStyle RippleStyle um:Ripple true

Modified

Key Aliased Key TargetType Implicit Style
MaterialToggleMenuFlyoutItemStyle ToggleMenuFlyoutItemStyle ToggleMenuFlyoutItem false -> true
MaterialMenuFlyoutSubItemStyle MenuFlyoutSubItemStyle MenuFlyoutSubItem false -> true
MaterialMenuFlyoutSeparatorStyle MenuFlyoutSeparatorStyle MenuFlyoutSeparator false -> true
MaterialFilledPasswordBoxStyle FilledPasswordBoxStyle PasswordBox true -> false
MaterialOutlinedPasswordBoxStyle OutlinedPasswordBoxStyle PasswordBox false -> true
MaterialFilledTextBoxStyle FilledTextBoxStyle TextBox true -> false
MaterialOutlinedTextBoxStyle OutlinedTextBoxStyle TextBox false -> true
MaterialTextToggleButtonStyle TextToggleButtonStyle ToggleButton true -> false
MaterialIconToggleButtonStyle IconToggleButtonStyle ToggleButton false -> true

Resources

As a result of the Lightweight Styling support, many resource keys have been added as well as renamed. For a list of all the new resource keys, please refer to the Lightweight Styling documentation.

Along with the above list of new resource keys, below is a list of the resource keys that have been removed or renamed.

Note

Most resources, including those that have been added or renamed, have now been placed inside of a ThemeDictionary. This means that the resources should now be referenced using the ThemeResource markup extension instead of StaticResource. For more information on theme resources, see XAML theme resources documentation.

Button

Old Key New Key Value
MaterialButtonHorizontalContentAlignment ButtonHorizontalContentAlignment Center
MaterialButtonVerticalContentAlignment ButtonVerticalContentAlignment Center
MaterialButtonCornerRadius REMOVED 20
MaterialOutlinedButtonBorderThickness REMOVED 1
MaterialButtonBorderThickness REMOVED 0
MaterialTextButtonPadding REMOVED 12,0
MaterialButtonPadding REMOVED 16,0
MaterialButtonMinWidth REMOVED 40
MaterialButtonMinHeight REMOVED 40
MaterialOutlinedButtonBorderBrush REMOVED OutlineBrush
MaterialNullToTextButtonMarginConverter NullToTextButtonMarginConverter

CalendarDatePicker

Old Key New Key Value
MaterialCalendarDatePickerBackground REMOVED OnSurfaceColor*0.12

CheckBox

Old Key New Key Value
CheckAreaCornerRadius REMOVED 4
CheckAreaSize REMOVED 18
FocusAreaSize REMOVED 40
CheckAreaLength REMOVED 40
CheckBoxCheckGlyphPathStyle REMOVED M28.718018,0L32,3.2819897 10.666016,24.616999 0,13.951997 3.2810059,10.670007 10.666016,18.055033z
CheckBoxHyphenGlyphPathStyle REMOVED M0,0L32,0 32,5.3 0,5.3z

ComboBox

Old Key New Key Value
MaterialComboBoxPadding REMOVED 16,0
MaterialComboBoxOpenedBorderThickness REMOVED 2
MaterialComboBoxBorderThickness REMOVED 1
DownArrowPathData ComboBoxDownArrowPathData M0 0L5 5L10 0H0Z
UpArrowPathData ComboBoxUpArrowPathData M0 0L-5 -5L-10 0H0Z
MaterialComboBoxCornerRadius REMOVED 4

DatePicker

Old Key New Key Value
MaterialDatePickerBackgroundColorBrush REMOVED OnSurfaceColor*0.12
MaterialDatePickerFlyoutPresenterSpacerFill REMOVED OnSurfaceFocusedBrush
MaterialDatePickerFlyoutElevation REMOVED 8
MaterialDatePickerFlyoutPresenterHighlightFill REMOVED PrimaryColor*0.2
MaterialDatePickerFlyoutPresenterBorderBrush REMOVED OnSurfaceFocusedBrush
MaterialDatePickerHostPadding REMOVED 24,24,8,8
MaterialDatePickerFlyoutPresenterBackgroundBrush REMOVED SurfaceBrush
MaterialDatePickerHeight REMOVED 53
MaterialDatePickerSpacerThemeWidth REMOVED 1
MaterialDateTimeFlyoutBorderThickness REMOVED 1

FloatingActionButton

Old Key New Key Value
MaterialFabIconTextPadding REMOVED 12
MaterialLargeFabCornerRadius REMOVED 28
MaterialLargeFabContentWidthOrHeight REMOVED 24
MaterialLargeFabPadding REMOVED 36
MaterialSmallFabCornerRadius REMOVED 12
MaterialSmallFabContentWidthOrHeight REMOVED 16
MaterialSmallFabPadding REMOVED 12
MaterialFabCornerRadius REMOVED 16
MaterialFabContentWidthOrHeight REMOVED 16
MaterialFabPadding REMOVED 20
MaterialTertiaryFabDisabledStateOverlay REMOVED OnSurfaceDisabledLowBrush
MaterialTertiaryFabPressedStateOverlay REMOVED OnTertiaryContainerFocusedBrush
MaterialTertiaryFabFocusedStateOverlay REMOVED OnTertiaryContainerFocusedBrush
MaterialTertiaryFabPointerOverStateOverlay REMOVED OnTertiaryContainerHoverBrush
MaterialTertiaryFabDisabledForeground REMOVED OnSurfaceDisabledBrush
MaterialTertiaryFabDisabledBackground REMOVED SystemControlTransparentBrush
MaterialTertiaryFabBackground REMOVED TertiaryContainerBrush
MaterialTertiaryFabForeground REMOVED OnTertiaryContainerBrush
MaterialSecondaryFabDisabledStateOverlay REMOVED OnSurfaceDisabledLowBrush
MaterialSecondaryFabPressedStateOverlay REMOVED OnSecondaryContainerPressedBrush
MaterialSecondaryFabFocusedStateOverlay REMOVED OnSecondaryContainerFocusedBrush
MaterialSecondaryFabPointerOverStateOverlay REMOVED OnSecondaryContainerHoverBrush
MaterialSecondaryFabDisabledForeground REMOVED OnSurfaceDisabledBrush
MaterialSecondaryFabDisabledBackground REMOVED SystemControlTransparentBrush
MaterialSecondaryFabBackground REMOVED SecondaryContainerBrush
MaterialSecondaryFabForeground REMOVED OnSecondaryContainerBrush
MaterialSurfaceFabDisabledStateOverlay REMOVED OnSurfaceDisabledLowBrush
MaterialSurfaceFabDisabledBackground REMOVED SystemControlTransparentBrush
MaterialSurfaceFabPressedStateOverlay REMOVED PrimaryPressedBrush
MaterialSurfaceFabFocusedStateOverlay REMOVED PrimaryFocusedBrush
MaterialSurfaceFabPointerOverStateOverlay REMOVED PrimaryHoverBrush
MaterialSurfaceFabDisabledForeground REMOVED OnSurfaceDisabledBrush
MaterialSurfaceFabBackground REMOVED SurfaceBrush
MaterialSurfaceFabForeground REMOVED PrimaryBrush
MaterialFabDisabledStateOverlay REMOVED OnSurfaceDisabledLowBrush
MaterialFabPressedStateOverlay REMOVED OnPrimaryContainerPressedBrush
MaterialFabFocusedStateOverlay REMOVED OnPrimaryContainerFocusedBrush
MaterialFabPointerOverStateOverlay REMOVED OnPrimaryContainerHoverBrush
MaterialFabDisabledForeground REMOVED OnSurfaceDisabledBrush
MaterialFabDisabledBackground REMOVED SystemControlTransparentBrush
MaterialFabBackground REMOVED PrimaryContainerBrush
MaterialFabForeground REMOVED OnPrimaryContainerBrush
Old Key New Key Value
NavigationViewItemExpandedGlyph REMOVED
NavigationViewItemExpandedGlyphFontSize REMOVED 8
NavigationViewItemChildrenMenuFlyoutPadding REMOVED 0,8
TopNavigationViewOverflowMenuPadding REMOVED 0,8
NavigationViewMinimalContentGridCornerRadius REMOVED 0
TopNavigationViewContentGridCornerRadius REMOVED 0
NavigationViewContentGridCornerRadius REMOVED 8,0,0,0
TopNavigationViewItemOnOverflowExpandChevronPadding REMOVED 12,0
TopNavigationViewItemOnOverflowExpandChevronMargin REMOVED -4,0,-8,0
TopNavigationViewItemOnOverflowNoIconContentPresenterMargin REMOVED 16,0,20,0
TopNavigationViewItemOnOverflowContentPresenterMargin REMOVED 12,0,20,0
TopNavigationViewItemContentOnlyExpandChevronMargin REMOVED -12,0,0,0
TopNavigationViewItemIconOnlyExpandChevronMargin REMOVED 0
TopNavigationViewItemExpandChevronMargin REMOVED -16,0,0,0
NavigationViewItemExpandChevronMargin REMOVED 0,0,-14,0
TopNavigationViewItemContentOnlyContentPresenterMargin REMOVED 12,0
TopNavigationViewItemContentPresenterMargin REMOVED 8,-1,12,-1
NavigationViewCompactItemContentPresenterMargin REMOVED 0
NavigationViewItemContentPresenterMargin REMOVED 4,-1,8,-1
TopNavigationViewOverflowButtonMargin REMOVED 0
TopNavigationViewItemSeparatorMargin REMOVED 3,0,4,0
NavigationViewCompactItemSeparatorMargin REMOVED 0,3,0,4
NavigationViewItemSeparatorMargin REMOVED 0,3,0,4
TopNavigationViewItemMargin REMOVED 0
NavigationViewItemMargin REMOVED 0
NavigationViewPaneTitlePresenterMargin REMOVED 8,4,0,0
TopNavigationViewContentMargin REMOVED 0
NavigationViewMinimalContentMargin REMOVED 0
NavigationViewContentMargin REMOVED 0
NavigationViewContentPresenterMargin REMOVED 0
NavigationViewHeaderMargin REMOVED 56,44,0,0
NavigationViewBorderThickness REMOVED 1
TopNavigationViewTopNavGridMargin REMOVED 4,0
TopNavigationViewContentGridBorderThickness REMOVED 0,1,0,0
NavigationViewMinimalContentGridBorderThickness REMOVED 0,1,0,0
NavigationViewContentGridBorderThickness REMOVED 1,1,0,0
NavigationViewPaneContentGridMargin REMOVED -1,3
NavigationViewButtonHolderGridMargin REMOVED 0
NavigationViewMinimalHeaderMargin REMOVED -24,44,0,0
TopNavigationViewItemInnerHeaderMargin REMOVED 12,0
NavigationViewItemInnerHeaderMargin REMOVED 16,0
NavigationViewItemButtonMargin REMOVED 12,0
NavigationViewItemOnLeftIconBoxMargin REMOVED 3
NavigationViewItemBorderThickness REMOVED 1
NavigationViewToggleBorderThickness REMOVED 0
TopNavigationViewItemSeparatorWidth REMOVED 1
NavigationViewItemSeparatorHeight REMOVED 1
NavigationViewSelectionIndicatorRadius REMOVED 2
NavigationViewSelectionIndicatorHeight REMOVED 24
NavigationViewSelectionIndicatorWidth REMOVED 3
NavigationViewItemOnLeftIconBoxHeight REMOVED 24
NavigationViewPaneHeaderRowMinHeight REMOVED 56
NavigationViewItemOnLeftMinHeight REMOVED 56
TopNavigationViewSettingsButtonHeight REMOVED 40
TopNavigationViewSettingsButtonWidth REMOVED 40
TopNavigationViewOverflowButtonHeight REMOVED 40
TopNavigationViewOverflowButtonWidth REMOVED 40
TopNavigationViewPaneCustomContentMinWidth REMOVED 80
NavigationViewAutoSuggestAreaHeight REMOVED 40
NavigationViewTopPaneHeight REMOVED 48
NavigationViewIconBoxWidth REMOVED 40
NavigationViewCompactPaneLength REMOVED 80
PaneToggleButtonWidth REMOVED 80
PaneToggleButtonHeight REMOVED 56
TopNavigationViewAutoSuggestBoxMargin REMOVED 4,0
NavigationViewAutoSuggestBoxMargin REMOVED 16,0
MaterialNavigationViewItemRippleFeedback REMOVED PrimaryPressedBrush
MaterialNavigationViewItemBackgroundDisabled REMOVED OnSurfaceDisabledLowBrush
MaterialNavigationViewItemBackgroundPointerOver REMOVED PrimaryHoverBrush
MaterialNavigationViewItemBackgroundPressed REMOVED PrimaryPressedBrush
MaterialNavigationViewItemBackgroundSelected REMOVED PrimarySelectedBrush
MaterialNavigationItemContentMarginWithoutIcon REMOVED 0
MaterialNavigationItemContentMargin REMOVED 12,0,0,0
MaterialNavigationItemIconLength REMOVED 24
MaterialNavigationItemLeftMargin REMOVED 12,0
MaterialNavigationViewItemCornerRadiusLeftOnly REMOVED 28,0,0,28
MaterialNavigationViewItemCornerRadius REMOVED 28
MaterialNavigationItemHeight REMOVED 56
MaterialNavigationViewButtonRippleFeedback REMOVED PrimaryPressedBrush
MaterialNavigationViewButtonBackgroundPointerOver REMOVED PrimaryHoverBrush
MaterialNavigationViewButtonBackgroundPressed REMOVED PrimaryPressedBrush
MaterialNavigationViewButtonForegroundDisabled REMOVED OnSurfaceDisabledLowBrush
MaterialNavigationViewButtonMarginWhenStackedVertically REMOVED 12,0
MaterialNavigationViewButtonIconSymbolFontSize REMOVED 24
MaterialNavigationViewButtonIconLength REMOVED 24
MaterialNavigationViewButtonCornerRadius REMOVED 28
MaterialNavigationViewButtonWidth REMOVED 56
MaterialNavigationViewContentGridCornerRadius REMOVED 14,0,0,14
MaterialNavigationViewSplitViewCornerRadius REMOVED 0,14,14,0
MaterialNavigationViewPaneBackground REMOVED SurfaceBrush
MaterialNavigationViewBackground REMOVED SurfaceBrush

PasswordBox

Old Key New Key Value
MaterialDisabledOutlinedPasswordBoxBorderBrush REMOVED OnSurfaceColor*0.12
MaterialRevealGlyphPathData REMOVED M11 0.5C6 0.5 1.73 3.61 0 8C1.73 12.39 6 15.5 11 15.5C16 15.5 20.27 12.39 22 8C20.27 3.61 16 0.5 11 0.5ZM11 13C8.24 13 6 10.76 6 8C6 5.24 8.24 3 11 3C13.76 3 16 5.24 16 8C16 10.76 13.76 13 11 13ZM11 5C9.34 5 8 6.34 8 8C8 9.66 9.34 11 11 11C12.66 11 14 9.66 14 8C14 6.34 12.66 5 11 5Z

PipsPager

Old Key New Key Value
MaterialPipsPagerNormalEllipseSize REMOVED 8
MaterialPipsPagerSelectedEllipseSize REMOVED 8
MaterialPipsPagerNavigationVisualStatesEllipseHeight REMOVED 12
MaterialPipsPagerNavigationVisualStatesEllipseWidth REMOVED 12
MaterialPipsPagerNavigationButtonWidth REMOVED 40
MaterialPipsPagerNavigationButtonHeight REMOVED 40
MaterialPipsPagerNextPageButtonData REMOVED M4.66319 5.67785C4.36844 6.10738 3.63156 6.10738 3.33681 5.67785L0.103738 0.966444C-0.191015 0.536913 0.177425 6.83871e-07 0.766931 6.32335e-07L7.23307 6.70473e-08C7.82257 1.55111e-08 8.19101 0.536912 7.89626 0.966443L4.66319 5.67785Z
MaterialPipsPagerPreviousPageButtonData REMOVED M3.33681 0.322148C3.63156 -0.107383 4.36844 -0.107382 4.66319 0.322148L7.89626 5.03356C8.19101 5.46309 7.82257 6 7.23307 6L0.766932 6C0.177427 6 -0.191014 5.46309 0.103739 5.03356L3.33681 0.322148Z
MaterialPipsPagerNavigationButtonBorderThickness REMOVED 0
MaterialPipsPagerButtonBorderThickness REMOVED 0
MaterialPipsPagerVerticalOrientationButtonHeight REMOVED 12
MaterialPipsPagerVerticalOrientationButtonWidth REMOVED 12
MaterialPipsPagerHorizontalOrientationButtonHeight REMOVED 12
MaterialPipsPagerHorizontalOrientationButtonWidth REMOVED 12

ProgressBar

Old Key New Key Value
MaterialProgressBarHeight REMOVED 4
MaterialProgressBarMinWidth REMOVED 250

ProgressRing

Old Key New Key Value
M3MaterialIndeterminateAnimation_Uno REMOVED embedded://Uno.Material/Uno.Material.Assets.MaterialIndeterminate.json
M3MaterialDeterminateAnimation_Uno REMOVED embedded://Uno.Material/Uno.Material.Assets.MaterialDeterminate.json
M3MaterialIndeterminateAnimation_Win REMOVED ms-appx:///Uno.Material/Assets/MaterialIndeterminate.json
M3MaterialDeterminateAnimation_Win REMOVED ms-appx:///Uno.Material/Assets/MaterialDeterminate.json

RadioButton

Old Key New Key Value
RadioBorderThickness REMOVED 2
RadioCheckAreaSize REMOVED 20
RadioStatesAreaSize REMOVED 40
RadioStatesAreaLength REMOVED 40

Slider

Old Key New Key Value
MaterialSliderThumbBackgroundDisabled REMOVED SystemControlDisabledChromeDisabledHighBrush
MaterialSliderInlineTickBarFill REMOVED SystemControlBackgroundAltHighBrush
MaterialSliderTickBarFillDisabled REMOVED SystemControlDisabledBaseMediumLowBrush
MaterialSliderTickBarFill REMOVED OnSecondaryLowBrush
MaterialSliderTrackBrush REMOVED MaterialSliderTrackColor

TextBox

Old Key New Key Value
MaterialDisabledOutlinedTextBoxBorderBrush REMOVED OnSurfaceColor*0.12
M3ClearGlyphPathData REMOVED M10 0C4.47 0 0 4.47 0 10C0 15.53 4.47 20 10 20C15.53 20 20 15.53 20 10C20 4.47 15.53 0 10 0ZM10 18C5.59 18 2 14.41 2 10C2 5.59 5.59 2 10 2C14.41 2 18 5.59 18 10C18 14.41 14.41 18 10 18ZM10 8.59L13.59 5L15 6.41L11.41 10L15 13.59L13.59 15L10 11.41L6.41 15L5 13.59L8.59 10L5 6.41L6.41 5L10 8.59Z

ToggleButton

Old Key New Key Value
MaterialToggleButtonPadding REMOVED 16,8
MaterialToggleButtonBorderRadius REMOVED 4
MaterialToggleButtonForegroundThemeBrush REMOVED OnSurfaceBrush
MaterialToggleButtonTextLabelBrush REMOVED PrimaryColor

ToggleSwitch

Old Key New Key Value
MaterialPrimaryVariantLowThumbColorBrush REMOVED MaterialPrimaryVariantLowThumbColor
MaterialToggleSwitchOnLowBackgroundBrush REMOVED OnSurfaceSelectedBrush
MaterialToggleSwitchOnLowButtonBrush REMOVED OnSurfaceSelectedBrush
MaterialToggleSwitchOffBackgroundBrush REMOVED OnSurfaceLowBrush
MaterialToggleSwitchOffButtonBrush REMOVED OnPrimaryBrush
MaterialToggleSwitchOnBackgroundBrush REMOVED PrimaryVariantLightBrush
MaterialToggleSwitchOnButtonBrush REMOVED PrimaryBrush
MaterialToggleSwitchHeaderMargin REMOVED 0,0,12,0

Upgrading to Uno.Material v2

Starting with version 2.0.0 of the Uno.Material and Uno.Material.WinUI packages, users can now take advantage of the new Material Design 3 design system from Google. Along with the new Material Design 3 styles, our Uno.Material NuGet packages will continue to support the previous Material Design 2 styles. In order to achieve this backward compatibility, we have had to make some changes to the way Uno.Material is initialized within your App.xaml.

Note

In order to avoid any confusion going forward in this article, we will be referring to the new collection of Material Design 3 styles as the "v2" styles and the previous collection of Material Design 2 styles will be referred to as the "v1" styles.

There are two available paths once you have updated to the new Uno.Material v2 package:

  • Continue to keep using the v1 styles; or,
  • Migrate app to reference the new v2 styles

Continue Using v1 Styles

Warning

In order to continue using the v1 styles, some changes are required in your App.xaml.

The Uno.Material v2 NuGet package contains both sets of v1 and v2 styles. Within your App.xaml, you will need to replace the references to MaterialColors and MaterialResources with MaterialColorsV1 and MaterialResourcesV1. MaterialFonts remains unchanged.

Migrating to v2 Styles

Both MaterialColors and MaterialResources will now always initialize the latest version of the Material styles. It is also possible to directly reference the MaterialColorsV2 and MaterialResourcesV2 ResourceDictionaries if needed.

The v2 styles introduce a new naming system for its resource keys. Refer to the Material Styles Matrix for the updated style keys. In addition to the new style keys, the Uno.Material color palette and text resources have also been updated to align with the Material Design 3 Color System and the Material Design 3 Typography Guidelines.

Color Update

A new color palette has been created for v2, meaning any color palette overrides ResourceDictionary in your app must be updated with the new resource keys. An example of the new color palette can be seen in the new Uno.Material default palette. For more information on the updated colors, you can refer to the "Colors and Themes" section of the Material 3 Migration Guide.

Note

As of v2, the Brush resources have been relocated to ThemeDictionaries. To reference these Brush resources, use the ThemeResource binding. More information on theme resources can be found in XAML theme resources documentation.

Typography Updates

Text styles have also been modified in v2. There is no 1-to-1 mapping between v1 and v2 text styles in terms of font-sizes and usages. The "Typography" section of the Material 3 Migration Guide can be helpful for choosing the right style.

Below is a table that is not a strict guideline, but, is provided to you as a suggestion of mapping text styles from v1 to v2:

Previous Style New Style
MaterialHeadline1 MaterialDisplaySmall
MaterialHeadline2 MaterialHeadlineLarge
MaterialHeadline3 MaterialHeadlineMedium
MaterialHeadline4 MaterialHeadlineSmall
MaterialHeadline5 MaterialTitleLarge
MaterialSubtitle1 MaterialTitleMedium
MaterialSubtitle2 MaterialTitleSmall
MaterialBody1 MaterialBodyLarge
MaterialBody2 MaterialBodyMedium
MaterialCaption MaterialBodySmall
MaterialButtonText MaterialLabelLarge
MaterialOverline MaterialLabelMedium
N/A MaterialLabelSmall
N/A MaterialLabelExtraSmall
N/A MaterialCaptionLarge
N/A MaterialCaptionMedium
N/A MaterialCaptionSmall
N/A MaterialDisplayLarge
N/A MaterialDisplayMedium

Notable Style Key Changes

Control Previous Style Key New Style Key
Button MaterialButtonIconStyle MaterialIconButtonStyle
Button MaterialContainedButtonStyle MaterialFilledButtonStyle
ToggleButton MaterialToggleButtonIconStyle MaterialIconToggleButtonStyle

Notable Package Changes

Namespace Previous Package New Package
ControlExtensions.Icon Uno.Material.Extensions Uno.Material
Ripple Uno.Material.Controls Uno.Material