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.
\nPlugin.Maui.BootstrapTheme NuGet packageAppThemeBinding values or separate ResourceDictionary files with matching keys.DynamicResource bindings (or AppThemeBinding markup) throughout XAML pages.Application.Current.RequestedTheme and the RequestedThemeChanged event.Preferences.Set / Preferences.Get and apply on startup.ConfigChanges.UiMode is set on MainActivity to avoid activity restarts on theme change.Check these rules against the user's scenario, and apply only the ones that\naffect what they asked. UiMode and dictionary swapping matter for runtime theme\nswitching; they are noise in a question about setting up AppThemeBinding.
Answer narrowly, but completely. Completeness means showing the code that\nimplements what you recommended — not adding adjacent topics. If you recommend\nDynamicResource, show the dictionary swap that makes it update. If the user asks\nfor light/dark colours in C#, show both SetAppThemeColor (colours) and the\ngeneric SetAppTheme<T> (any bindable property type), and prefer resource keys over\nscattered hardcoded colours. Do not tack on platform configuration the question\ndidn't raise.
| Rule | \nDo this | \nNot this | \nWhy | \n
|---|---|---|---|
| Runtime-swapped values must be dynamic | \n{DynamicResource Key} | \n{StaticResource Key} | \nStaticResource resolves once at load and never updates when dictionaries are swapped. | \n
Android must declare UiMode (only for runtime/system theme switching) | \nInclude ConfigChanges.UiMode in the ConfigurationChanges list on MainActivity | \nOmitting it | \nWithout it Android restarts the activity on theme change — navigation state is lost and it looks like a crash. Irrelevant to a static AppThemeBinding setup | \n
Force a theme via UserAppTheme | \nApplication.Current.UserAppTheme = AppTheme.Dark | \nManually re-assigning colors | \nUserAppTheme overrides the OS; AppTheme.Unspecified returns to following the system. | \n
Do not replace a working AppThemeBinding setup with ResourceDictionary\nswapping (or vice versa) unless the user needs what the other approach provides —\nmore than two themes, or a user-selectable theme.
| Approach | \nBest for | \nLimitation | \n
|---|---|---|
| AppThemeBinding | \nAutomatic light/dark with OS — minimal code | \nOnly two themes (light + dark) | \n
| ResourceDictionary swap | \nCustom branded themes, more than two themes, user preference | \nMore setup; must use DynamicResource everywhere | \n
| Both combined | \nOS-driven response plus custom theme colors | \nMost flexible but most complex | \n
AppThemeBinding selects a value based on the current system theme. It supports Light, Dark, and an optional Default fallback.
Putting {AppThemeBinding Light=#333333, Dark=#FFFFFF} on every element is the\nsingle most common theming mistake: the palette ends up duplicated across dozens of\nfiles and cannot be changed in one place. Recommend this shape as the final\nanswer, not inline literals:
<!-- App.xaml — one source of truth for the whole app -->\n<Application.Resources>\n <ResourceDictionary>\n\n <!-- 1. Raw palette -->\n <Color x:Key=\"LightPageBackground\">#FFFFFF</Color>\n <Color x:Key=\"DarkPageBackground\">#1E1E1E</Color>\n <Color x:Key=\"LightPrimaryText\">#333333</Color>\n <Color x:Key=\"DarkPrimaryText\">#E0E0E0</Color>\n\n <!-- 2. Implicit styles bind the pair once; every page inherits them -->\n <Style TargetType=\"ContentPage\" ApplyToDerivedTypes=\"True\">\n <Setter Property=\"BackgroundColor\"\n Value=\"{AppThemeBinding Light={StaticResource LightPageBackground},\n Dark={StaticResource DarkPageBackground}}\" />\n </Style>\n\n <Style TargetType=\"Label\">\n <Setter Property=\"TextColor\"\n Value=\"{AppThemeBinding Light={StaticResource LightPrimaryText},\n Dark={StaticResource DarkPrimaryText}}\" />\n </Style>\n\n </ResourceDictionary>\n</Application.Resources>\nPages then need no theming markup at all — they pick the styles up implicitly.\nUse an inline AppThemeBinding only for genuine one-offs, and even then reference\n{StaticResource} keys rather than literal hex.
<Label Text=\"Themed text\"\n TextColor=\"{AppThemeBinding Light=Green, Dark=Red}\"\n BackgroundColor=\"{AppThemeBinding Light=White, Dark=Black}\" />\n\n<!-- With resource references — preferred over literals -->\n<Label TextColor=\"{AppThemeBinding Light={StaticResource LightPrimary},\n Dark={StaticResource DarkPrimary}}\" />\nShow both when answering a \"light/dark colours in C#\" question — SetAppThemeColor\ncovers Color properties, SetAppTheme<T> covers everything else:
var label = new Label();\n\n// Color-specific helper\nlabel.SetAppThemeColor(Label.TextColorProperty, Colors.Green, Colors.Red);\n\n// Generic helper — works for any bindable property type, not just Color\nlabel.SetAppTheme<Color>(Label.TextColorProperty, Colors.Green, Colors.Red);\nlabel.SetAppTheme<double>(Label.FontSizeProperty, 14, 16);\n\n// The BindableProperty must belong to the object you call it on —\n// Image.SourceProperty goes on an Image, not a Label.\nvar image = new Image();\nimage.SetAppTheme<ImageSource>(Image.SourceProperty,\n ImageSource.FromFile(\"logo_light.png\"),\n ImageSource.FromFile(\"logo_dark.png\"));\nPrefer defining the values as resource keys and referencing them, rather than\nscattering hardcoded colours across the codebase.
\nUse separate ResourceDictionary files with matching keys to define themes, then swap them at runtime.
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
\n<ResourceDictionary xmlns=\"http://schemas.microsoft.com/dotnet/2021/maui\"\n xmlns:x=\"http://schemas.microsoft.com/winfx/2009/xaml\"\n x:Class=\"MyApp.Themes.LightTheme\">\n <Color x:Key=\"PageBackgroundColor\">White</Color>\n <Color x:Key=\"PrimaryTextColor\">#333333</Color>\n <Color x:Key=\"AccentColor\">#2196F3</Color>\n</ResourceDictionary>\nLightTheme.xaml.cs
\nnamespace MyApp.Themes;\n\npublic partial class LightTheme : ResourceDictionary\n{\n public LightTheme() => InitializeComponent();\n}\nCreate a matching DarkTheme.xaml / DarkTheme.xaml.cs with the same keys and different values.
\nUse DynamicResource so values update when the dictionary is swapped at runtime:
<ContentPage BackgroundColor=\"{DynamicResource PageBackgroundColor}\">\n <Label Text=\"Hello\"\n TextColor=\"{DynamicResource PrimaryTextColor}\" />\n <Button Text=\"Action\"\n BackgroundColor=\"{DynamicResource AccentColor}\" />\n</ContentPage>\n\n\n\uD83D\uDEA8 Never call
\nMergedDictionaries.Clear()to swap a theme. The default MAUI\ntemplate mergesResources/Styles/Colors.xamlandStyles.xamlinto\nApplication.Resources.Clear()removes those too, so every implicit style,\nbrush and colour in the app silently disappears — buttons, entries and labels all\nrevert to unstyled defaults. Verified: afterClear(),MergedDictionariesdrops\nfrom 2 to 1 and the template'sPrimarycolour no longer resolves.
Remove only the theme you added, and leave everything else alone:
\nstatic ResourceDictionary? _currentTheme;\n\nvoid ApplyTheme(ResourceDictionary theme)\n{\n var merged = Application.Current!.Resources.MergedDictionaries;\n\n // ✅ Remove ONLY the previous theme — Colors.xaml / Styles.xaml survive\n if (_currentTheme is not null)\n merged.Remove(_currentTheme);\n\n merged.Add(theme);\n _currentTheme = theme;\n}\n\n// Usage\nApplyTheme(new DarkTheme());\n// ❌ Destroys the app's Colors.xaml and Styles.xaml along with the old theme\nvar merged = Application.Current!.Resources.MergedDictionaries;\nmerged.Clear();\nmerged.Add(theme);\nAppTheme currentTheme = Application.Current!.RequestedTheme;\n// Returns AppTheme.Light, AppTheme.Dark, or AppTheme.Unspecified\n// Force dark mode regardless of OS setting\nApplication.Current!.UserAppTheme = AppTheme.Dark;\n\n// Reset to follow system theme\nApplication.Current!.UserAppTheme = AppTheme.Unspecified;\nApplication.Current!.RequestedThemeChanged += (s, e) =>\n{\n AppTheme newTheme = e.RequestedTheme;\n // Update UI or switch ResourceDictionaries\n};\nUse AppThemeBinding with DynamicResource values for maximum flexibility — the\nnested DynamicResource stays live, so swapping the dictionary updates the value\nand the OS light/dark switch is still honoured:
<Label TextColor=\"{AppThemeBinding\n Light={DynamicResource LightPrimary},\n Dark={DynamicResource DarkPrimary}}\" />\nOr react to system changes and swap full dictionaries:
\nApplication.Current!.RequestedThemeChanged += (s, e) =>\n{\n ApplyTheme(e.RequestedTheme == AppTheme.Dark\n ? new DarkTheme()\n : new LightTheme());\n};\nStore the user's choice with Preferences and apply it on startup:
// Save choice\nPreferences.Set(\"AppTheme\", \"Dark\");\n\n// Restore on startup (in App constructor or CreateWindow)\nvar saved = Preferences.Get(\"AppTheme\", \"System\");\nApplication.Current!.UserAppTheme = saved switch\n{\n \"Light\" => AppTheme.Light,\n \"Dark\" => AppTheme.Dark,\n _ => AppTheme.Unspecified\n};\nMainActivity must include ConfigChanges.UiMode or theme-change events will not fire and the activity restarts instead of handling the change gracefully:
[Activity(Theme = \"@style/Maui.SplashTheme\",\n MainLauncher = true,\n ConfigurationChanges = ConfigChanges.ScreenSize\n | ConfigChanges.Orientation\n | ConfigChanges.UiMode // ← Required for theme detection\n | ConfigChanges.ScreenLayout\n | ConfigChanges.SmallestScreenSize\n | ConfigChanges.Density)]\npublic class MainActivity : MauiAppCompatActivity { }\nWithout UiMode, toggling dark mode in Android settings causes a full activity restart — losing navigation state and appearing as a crash. With it declared, the app stays alive and RequestedThemeChanged fires, so pair this fix with a handler that re-applies the theme (see below).
When using ResourceDictionary theme switching, you must use DynamicResource:
<!-- ✅ Updates when theme dictionary changes -->\n<Label TextColor=\"{DynamicResource PrimaryTextColor}\" />\n\n<!-- ❌ Frozen at first load — won't update on theme switch -->\n<Label TextColor=\"{StaticResource PrimaryTextColor}\" />\nDynamicResource only helps if something actually swaps the dictionary. When you\ndiagnose this, always show the swap and the system-theme hook alongside the fix —\notherwise the user has a corrected binding that still never updates:
static ResourceDictionary? _currentTheme;\n\nvoid ApplyTheme(bool useDark)\n{\n var merged = Application.Current!.Resources.MergedDictionaries;\n\n // Remove only the previous theme — never Clear(), which also wipes\n // the template's Colors.xaml / Styles.xaml\n if (_currentTheme is not null)\n merged.Remove(_currentTheme);\n\n _currentTheme = useDark ? new DarkTheme() : new LightTheme();\n merged.Add(_currentTheme);\n}\n\n// React to the OS switching light/dark\nApplication.Current!.RequestedThemeChanged += (s, e) =>\n ApplyTheme(e.RequestedTheme == AppTheme.Dark);\nAvoid inline color values on elements that should respect the theme:
\n<!-- ❌ Will not change with theme -->\n<Label TextColor=\"#333333\" />\n\n<!-- ✅ Theme-aware -->\n<Label TextColor=\"{DynamicResource PrimaryTextColor}\" />\n.NET MAUI supports CSS styling, but CSS-based themes cannot be swapped dynamically. Use ResourceDictionary theming for runtime switching.
\nEvery x:Key used in one theme dictionary must exist in all other theme dictionaries. A missing key causes a silent fallback to the default value, leading to inconsistent appearance.
| Platform | \nMinimum Version | \n
|---|---|
| iOS | \n13+ | \n
| Android | \n10+ (API 29) | \n
| macOS Catalyst | \n10.15+ | \n
| Windows | \n10+ | \n
AppThemeBinding markup extensionSetAppThemeColor(), SetAppTheme<T>()Application.Current.RequestedThemeApplication.Current.UserAppTheme = AppTheme.DarkRequestedThemeChanged eventRemove the old theme from MergedDictionaries, then Add the new one — never Clear()DynamicResource (not StaticResource)Preferences.Set / Preferences.Get