rootcastleco/rei-skills / registry/external-reviewed/maui-theming
maui-theming
VerifiedGuide 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).
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.1 KB |
| SKILL.md | skill md | 16.1 KB |
| references/theming-api.md | markdown | 4.2 KB |
references/theming-api.md
View on GitHub# Theming API Reference
## AppThemeBinding Markup Extension
Selects a value based on the current system theme.
| Property | Description |
|----------|-------------|
| `Light` | Value used when the device is in light mode |
| `Dark` | Value used when the device is in dark mode |
| `Default`| Fallback value when the device theme is unknown |
### XAML Usage
```xml
<Label Text="Themed text"
TextColor="{AppThemeBinding Light=Green, Dark=Red}"
BackgroundColor="{AppThemeBinding Light=White, Dark=Black}" />
<!-- With StaticResource or DynamicResource values -->
<Label TextColor="{AppThemeBinding Light={StaticResource LightPrimary},
Dark={StaticResource DarkPrimary}}" />
```
### C# Extension Methods
```csharp
var label = new Label();
// Color-specific helper
label.SetAppThemeColor(Label.TextColorProperty, Colors.Green, Colors.Red);
// Generic helper for any type
label.SetAppTheme<Color>(Label.TextColorProperty, Colors.Green, Colors.Red);
```
## ResourceDictionary Theming (Custom Themes)
Use separate `ResourceDictionary` files with matching keys to define themes, then swap them at runtime.
### Define Theme Dictionaries
When using compiled XAML with `x:Class` (as shown below), each ResourceDictionary needs a code-behind file that calls `InitializeComponent()`. Dictionaries loaded via `Source` without `x:Class` do not need code-behind.
**LightTheme.xaml**
```xml
<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**
```csharp
namespace MyApp.Themes;
public partial class LightTheme : ResourceDictionary
{
public LightTheme() => InitializeComponent();
}
```
**DarkTheme.xaml.cs** — same pattern, different values, same keys.
### Consume with DynamicResource
Use `DynamicResource` (not `StaticResource`) so values update at runtime when the dictionary changes:
```xml
<ContentPage BackgroundColor="{DynamicResource PageBackgroundColor}">
<Label Text="Hello"
TextColor="{DynamicResource PrimaryTextColor}" />
<Button Text="Action"
BackgroundColor="{DynamicResource AccentColor}" />
</ContentPage>
```
### Switch Themes at Runtime
Remove only the previous theme. `MergedDictionaries.Clear()` also removes the
template's `Colors.xaml` / `Styles.xaml`, silently unstyling the whole app.
```csharp
static ResourceDictionary? _currentTheme;
void ApplyTheme(ResourceDictionary theme)
{
var merged = Application.Current!.Resources.MergedDictionaries;
if (_currentTheme is not null)
merged.Remove(_currentTheme);
merged.Add(theme);
_currentTheme = theme;
}
// Usage
ApplyTheme(new DarkTheme());
```
## System Theme Detection
### Current Theme
```csharp
AppTheme currentTheme = Application.Current!.RequestedTheme;
// Returns AppTheme.Light, AppTheme.Dark, or AppTheme.Unspecified
```
### Override the System Theme
```csharp
// Force a specific theme regardless of OS setting
Application.Current!.UserAppTheme = AppTheme.Dark;
// Reset to follow the system theme
Application.Current!.UserAppTheme = AppTheme.Unspecified;
```
### React to Theme Changes
```csharp
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:
```xml
<Label TextColor="{AppThemeBinding
Light={DynamicResource LightPrimary},
Dark={DynamicResource DarkPrimary}}" />
```
Or react to system changes and swap full ResourceDictionaries:
```csharp
Application.Current!.RequestedThemeChanged += (s, e) =>
{
ApplyTheme(e.RequestedTheme == AppTheme.Dark
? new DarkTheme()
: new LightTheme());
};
```
## Platform Support
| Platform | Minimum Version |
|----------------|-----------------|
| iOS | 13+ |
| Android | 10+ (API 29) |
| macOS Catalyst | 10.15+ |
| Windows | 10+ |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |