Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 42 ยท Styling and Resources

Themes and Dark Mode

Support light and dark mode in .NET MAUI with AppThemeBinding, RequestedTheme, UserAppTheme and a user theme picker, plus color contrast checks and swappable resource themes.

Users expect apps to follow the system theme, and many want to choose their own. MAUI makes both easy: the framework tells you whether the device is in light or dark mode, and one XAML markup extension switches values automatically. This lesson covers AppThemeBinding, forcing a theme from code, saving the user's choice, and building a custom theme (for example a "high contrast" or brand theme) from resource dictionaries.

The theme APIs depend on the platform's UI. XAML and MAUI code is shown read-only. The runnable stand-ins implement the decision logic and a color contrast calculator, which you can reuse as plain C#.

AppThemeBinding

AppThemeBinding is a markup extension with Light and Dark values (and an optional Default):

XML
<ContentPage BackgroundColor="{AppThemeBinding Light=White, Dark=#121212}">
    <Label Text="Hello"
           TextColor="{AppThemeBinding Light={StaticResource Black}, Dark={StaticResource White}}" />
</ContentPage>

When the system theme changes, every binding updates immediately. It also works for images, which is great for logos that need a light and a dark variant:

XML
<Image Source="{AppThemeBinding Light=logo_light.png, Dark=logo_dark.png}" />

The Light/Dark pairs can live in your styles, which keeps pages clean:

XML
<Style TargetType="Label">
    <Setter Property="TextColor" Value="{AppThemeBinding Light={StaticResource Gray900}, Dark={StaticResource White}}" />
</Style>

Put the pair in a style or a named resource once, rather than repeating AppThemeBinding on every control.

Reading and forcing the theme

C#
AppTheme current = Application.Current!.RequestedTheme;   // Light, Dark or Unspecified (what the system wants)
AppTheme forced = Application.Current.UserAppTheme;       // what you forced; Unspecified means "follow system"

Application.Current.UserAppTheme = AppTheme.Dark;         // override the system
Application.Current.UserAppTheme = AppTheme.Unspecified;  // follow the system again

Application.Current.RequestedThemeChanged += (s, e) =>
{
    Console.WriteLine($"System theme is now {e.RequestedTheme}");
};

RequestedTheme is always the system choice and UserAppTheme is your override. The visible theme is the override unless it is Unspecified. Setting UserAppTheme also affects AppThemeBinding and the native controls.

A user setting with three choices

A good settings screen offers System, Light and Dark. Save the choice in Preferences and apply it at startup:

C#
public enum ThemeChoice { System, Light, Dark }

public class ThemeService(ISettingsStore settings)
{
    const string Key = "theme_choice";

    public ThemeChoice Current
    {
        get => (ThemeChoice)settings.Get(Key, (int)ThemeChoice.System);
        set
        {
            settings.Set(Key, (int)value);
            Apply();
        }
    }

    public void Apply()
    {
        Application.Current!.UserAppTheme = Current switch
        {
            ThemeChoice.Light => AppTheme.Light,
            ThemeChoice.Dark => AppTheme.Dark,
            _ => AppTheme.Unspecified
        };
    }
}

Call Apply() in App's constructor (or CreateWindow) so there is no flash of the wrong theme at launch.

Status bar and system UI

The status bar text should flip with the theme. The .NET MAUI Community Toolkit offers StatusBarBehavior for this, and NavigationPage/Shell colors (Shell.BackgroundColor, BarBackgroundColor) can also use AppThemeBinding. On Android the splash screen and system bars are configured in Platforms/Android/Resources/values/styles.xml; test dark mode on a real device, because the emulator hides some differences.

Custom themes with swappable dictionaries

AppThemeBinding covers light and dark. For more themes (brand variants, high contrast, seasonal colors), keep one ResourceDictionary per theme and swap them at runtime. For this to work you reference the colors with DynamicResource:

XML
<!-- Themes/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="PageBackground">#FFFFFF</Color>
    <Color x:Key="PrimaryText">#1B1B1B</Color>
</ResourceDictionary>
C#
void SetTheme(ResourceDictionary theme)
{
    var merged = Application.Current!.Resources.MergedDictionaries;
    var old = merged.OfType<ThemeBase>().FirstOrDefault();   // or track the previous dictionary yourself
    if (old is not null) merged.Remove(old);
    merged.Add(theme);
}
XML
<ContentPage BackgroundColor="{DynamicResource PageBackground}">

Every theme must define the same keys. A missing key in one theme leaves the old value or fails at runtime.

Contrast: the part people forget

Switching colors is easy; making them readable is the real job. The WCAG guidelines define a contrast ratio between two colors: at least 4.5:1 for normal text and 3:1 for large text. You can check your palette in code, in a unit test even.

C# Stand-in: WCAG contrast checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The grey "muted" text fails on white, and the purple brand color fails on a very dark background. Brand colors usually need a lighter variant in dark mode, which is exactly what AppThemeBinding Light=..., Dark=... is for.

Try it: a theme service you can test

The theme service logic (stored choice, system theme, and the effective theme) is plain C#. Here it runs with a fake system.

C# Stand-in: ThemeService decision logic

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Checklist for a polished dark mode

  • Do not use pure black (#000000) text on pure white or the reverse; very high contrast can strain eyes. Dark greys such as #121212 are common.
  • Test every page in both themes, including dialogs, pickers and empty states.
  • Provide dark variants of images with transparency issues and logos.
  • Use semantic names (Surface, OnSurface) so a third theme is easy to add later.
  • Respect the system setting by default and offer an override.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Application.Current.RequestedTheme return?

    RequestedTheme is the system's choice. UserAppTheme is your override.
  2. 2. How do you make the app follow the system theme again after forcing Dark?

    AppTheme.Unspecified clears the override so the system theme applies.
  3. 3. Why must custom swappable themes use DynamicResource?

    StaticResource is resolved once at load, so a swapped dictionary would not be picked up.
  4. 4. What minimum contrast ratio does WCAG AA require for normal body text?

    AA requires 4.5:1 for normal text and 3:1 for large text.

Summary

  • AppThemeBinding switches values between light and dark automatically.
  • RequestedTheme is the system's theme; UserAppTheme is your override.
  • Offer System, Light and Dark, and save the choice in preferences.
  • More than two themes: swap ResourceDictionary files with DynamicResource.
  • Verify contrast with numbers, not only your eyes.

Next: Visual States and Triggers