---

name: maui-theming description: >- Guide for theming .NET MAUI apps — light/dark mode via AppThemeBinding, ResourceDictionary theme switching, DynamicResource bindings, system theme detection, and user theme preferences. Use when: "dark mode", "light mode", "theming", "AppThemeBinding", "theme switching", "ResourceDictionary theme", "dynamic resources", "system theme detection", "color scheme", "app theme", "DynamicResource". Do not use for: localization or language switching (see .NET MAUI localization documentation), accessibility visual adjustments (see .NET MAUI accessibility documentation), app icons or splash screens (see .NET MAUI app icons documentation), or Bootstrap-style class theming (see Plugin.Maui.BootstrapTheme NuGet package). license: MIT

.NET MAUI Theming

Apply light/dark mode support, custom branded themes, and runtime theme switching in .NET MAUI apps using AppThemeBinding, ResourceDictionary swapping, and system theme detection APIs.

When to Use

• Adding light and dark mode support to a .NET MAUI app
• Creating custom branded themes with ResourceDictionary
• Detecting and responding to system theme changes at runtime
• Letting users choose a preferred theme (light, dark, or system default)
• Combining OS-driven theme response with custom color palettes

When Not to Use

• Localization or language switching — see .NET MAUI localization docs
• Accessibility-specific visual adjustments — see .NET MAUI accessibility docs
• App icon or splash screen configuration — see .NET MAUI app icon docs
• Bootstrap-style class theming — see the Plugin.Maui.BootstrapTheme NuGet package

Inputs

• A .NET MAUI project targeting .NET 8 or later
• XAML pages or C# UI code that need theme-aware styling

Workflow

1. Detect the current theme approach in the project (AppThemeBinding, ResourceDictionary, or none).
2. Choose the appropriate strategy: AppThemeBinding for simple light/dark, ResourceDictionary swap for custom/multiple themes, or both combined.
3. Define theme resources — inline AppThemeBinding values or separate ResourceDictionary files with matching keys.
4. Replace hardcoded colors with DynamicResource bindings (or AppThemeBinding markup) throughout XAML pages.
5. Add system theme detection via Application.Current.RequestedTheme and the RequestedThemeChanged event.
6. Implement user preference persistence with Preferences.Set / Preferences.Get and apply on startup.
7. Verify Android ConfigChanges.UiMode is set on MainActivity to avoid activity restarts on theme change.
8. Test both light and dark themes on at least one target platform, confirming all UI elements respond correctly.

Rules That Change the Answer

Check these rules against the user's scenario, and apply only the ones that affect what they asked. UiMode and dictionary swapping matter for runtime theme switching; they are noise in a question about setting up AppThemeBinding.

Answer narrowly, but completely. Completeness means showing the code that implements what you recommended — not adding adjacent topics. If you recommend DynamicResource, show the dictionary swap that makes it update. If the user asks for light/dark colours in C#, show both SetAppThemeColor (colours) and the generic SetAppTheme<T> (any bindable property type), and prefer resource keys over scattered hardcoded colours. Do not tack on platform configuration the question didn't raise.

| Rule | Do this | Not this | Why | |---|---|---|---| | Runtime-swapped values must be dynamic | {DynamicResource Key} | {StaticResource Key} | StaticResource resolves once at load and never updates when dictionaries are swapped. | | Android must declare UiMode (only for runtime/system theme switching) | Include ConfigChanges.UiMode in the ConfigurationChanges list on MainActivity | Omitting it | Without it Android restarts the activity on theme change — navigation state is lost and it looks like a crash. Irrelevant to a static AppThemeBinding setup | | Force a theme via UserAppTheme | Application.Current.UserAppTheme = AppTheme.Dark | Manually re-assigning colors | UserAppTheme overrides the OS; AppTheme.Unspecified returns to following the system. |

Do not replace a working AppThemeBinding setup with ResourceDictionary swapping (or vice versa) unless the user needs what the other approach provides — more than two themes, or a user-selectable theme.

Choosing an Approach

| Approach | Best for | Limitation | |----------|----------|------------| | AppThemeBinding | Automatic light/dark with OS — minimal code | Only two themes (light + dark) | | ResourceDictionary swap | Custom branded themes, more than two themes, user preference | More setup; must use DynamicResource everywhere | | Both combined | OS-driven response plus custom theme colors | Most flexible but most complex |

AppThemeBinding (OS Light/Dark)

AppThemeBinding selects a value based on the current system theme. It supports Light, Dark, and an optional Default fallback.

Define the palette once — don't scatter literals

Putting {AppThemeBinding Light=#333333, Dark=#FFFFFF} on every element is the single most common theming mistake: the palette ends up duplicated across dozens of files and cannot be changed in one place. Recommend this shape as the final answer, not inline literals:

<!-- App.xaml — one source of truth for the whole app -->
<Application.Resources>
    <ResourceDictionary>

        <!-- 1. Raw palette -->
        <Color x:Key="LightPageBackground">#FFFFFF</Color>
        <Color x:Key="DarkPageBackground">#1E1E1E</Color>
        <Color x:Key="LightPrimaryText">#333333</Color>
        <Color x:Key="DarkPrimaryText">#E0E0E0</Color>

        <!-- 2. Implicit styles bind the pair once; every page inherits them -->
        <Style TargetType="ContentPage" ApplyToDerivedTypes="True">
            <Setter Property="BackgroundColor"
                    Value="{AppThemeBinding Light={StaticResource LightPageBackground},
                                            Dark={StaticResource DarkPageBackground}}" />
        </Style>

        <Style TargetType="Label">
            <Setter Property="TextColor"
                    Value="{AppThemeBinding Light={StaticResource LightPrimaryText},
                                            Dark={StaticResource DarkPrimaryText}}" />
        </Style>

    </ResourceDictionary>
</Application.Resources>

Pages then need no theming markup at all — they pick the styles up implicitly. Use an inline AppThemeBinding only for genuine one-offs, and even then reference {StaticResource} keys rather than literal hex.

XAML (inline form, for one-offs)

<Label Text="Themed text"
       TextColor="{AppThemeBinding Light=Green, Dark=Red}"
       BackgroundColor="{AppThemeBinding Light=White, Dark=Black}" />

<!-- With resource references — preferred over literals -->
<Label TextColor="{AppThemeBinding Light={StaticResource LightPrimary},
                                   Dark={StaticResource DarkPrimary}}" />

C# Extension Methods

Show both when answering a "light/dark colours in C#" question — SetAppThemeColor covers Color properties, SetAppTheme<T> covers everything else:

var label = new Label();

// Color-specific helper
label.SetAppThemeColor(Label.TextColorProperty, Colors.Green, Colors.Red);

// Generic helper — works for any bindable property type, not just Color
label.SetAppTheme<Color>(Label.TextColorProperty, Colors.Green, Colors.Red);
label.SetAppTheme<double>(Label.FontSizeProperty, 14, 16);

// The BindableProperty must belong to the object you call it on —
// Image.SourceProperty goes on an Image, not a Label.
var image = new Image();
image.SetAppTheme<ImageSource>(Image.SourceProperty,
    ImageSource.FromFile("logo_light.png"),
    ImageSource.FromFile("logo_dark.png"));

Prefer defining the values as resource keys and referencing them, rather than scattering hardcoded colours across the codebase.

ResourceDictionary Theming (Custom Themes)

Use separate ResourceDictionary files with matching keys to define themes, then swap them at runtime.

Step 1 — Define Theme Dictionaries

When using compiled XAML with x:Class (as shown below), each dictionary needs a code-behind that calls InitializeComponent(). Dictionaries loaded via Source without x:Class do not need code-behind.

LightTheme.xaml

<ResourceDictionary xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                    x:Class="MyApp.Themes.LightTheme">
    <Color x:Key="PageBackgroundColor">White</Color>
    <Color x:Key="PrimaryTextColor">#333333</Color>
    <Color x:Key="AccentColor">#2196F3</Color>
</ResourceDictionary>

LightTheme.xaml.cs

namespace MyApp.Themes;

public partial class LightTheme : ResourceDictionary
{
    public LightTheme() => InitializeComponent();
}

Create a matching DarkTheme.xaml / DarkTheme.xaml.cs with the same keys and different values.

Step 2 — Consume with DynamicResource

Use DynamicResource so values update when the dictionary is swapped at runtime:

<ContentPage BackgroundColor="{DynamicResource PageBackgroundColor}">
    <Label Text="Hello"
           TextColor="{DynamicResource PrimaryTextColor}" />
    <Button Text="Action"
            BackgroundColor="{DynamicResource AccentColor}" />
</ContentPage>

Step 3 — Switch Themes at Runtime

🚨 Never call MergedDictionaries.Clear() to swap a theme. The default MAUI template merges Resources/Styles/Colors.xaml and Styles.xaml into Application.Resources. Clear() removes those too, so every implicit style, brush and colour in the app silently disappears — buttons, entries and labels all revert to unstyled defaults. Verified: after Clear(), MergedDictionaries drops from 2 to 1 and the template's Primary colour no longer resolves.

Remove only the theme you added, and leave everything else alone:

static ResourceDictionary? _currentTheme;

void ApplyTheme(ResourceDictionary theme)
{
    var merged = Application.Current!.Resources.MergedDictionaries;

    // ✅ Remove ONLY the previous theme — Colors.xaml / Styles.xaml survive
    if (_currentTheme is not null)
        merged.Remove(_currentTheme);

    merged.Add(theme);
    _currentTheme = theme;
}

// Usage
ApplyTheme(new DarkTheme());

// ❌ Destroys the app's Colors.xaml and Styles.xaml along with the old theme
var merged = Application.Current!.Resources.MergedDictionaries;
merged.Clear();
merged.Add(theme);

System Theme Detection

Read the Current Theme

AppTheme currentTheme = Application.Current!.RequestedTheme;
// Returns AppTheme.Light, AppTheme.Dark, or AppTheme.Unspecified

Override the System Theme

// Force dark mode regardless of OS setting
Application.Current!.UserAppTheme = AppTheme.Dark;

// Reset to follow system theme
Application.Current!.UserAppTheme = AppTheme.Unspecified;

React to Theme Changes

Application.Current!.RequestedThemeChanged += (s, e) =>
{
    AppTheme newTheme = e.RequestedTheme;
    // Update UI or switch ResourceDictionaries
};

Combining Both Approaches

Use AppThemeBinding with DynamicResource values for maximum flexibility — the nested DynamicResource stays live, so swapping the dictionary updates the value and the OS light/dark switch is still honoured:

<Label TextColor="{AppThemeBinding
    Light={DynamicResource LightPrimary},
    Dark={DynamicResource DarkPrimary}}" />

O